> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onepay.la/llms.txt
> Use this file to discover all available pages before exploring further.

# Crear empresa

> Crea una nueva empresa asociada a tu cuenta. Los usuarios con permiso switch_company serán vinculados automáticamente como miembros.

### Headers

<ParamField header="x-idempotency" type="string" required placeholder="Token único para garantizar la idempotencia de la petición">
  Token único para garantizar la idempotencia de la petición
</ParamField>

### Body

<ParamField body="type" type="string" required placeholder="organization, individual">
  Tipo de empresa. Valores permitidos: `organization` (persona jurídica), `individual` (persona natural).
</ParamField>

<ParamField body="name" type="string" required>
  Nombre comercial de la empresa (2-255 caracteres).
</ParamField>

<ParamField body="legal_name" type="string" required>
  Razón social de la empresa (2-255 caracteres).
</ParamField>

<ParamField body="document_type" type="string" required placeholder="NIT, RUT, CC, CE, PPT, PEP, PASSPORT">
  Tipo de documento. Para `organization`: `NIT`, `RUT`. Para `individual`: `CC`, `CE`, `PPT`, `PEP`, `PASSPORT`.
</ParamField>

<ParamField body="document_number" type="string" required>
  Número de documento de identidad (5-30 caracteres).
</ParamField>

<ParamField body="phone" type="string" required placeholder="+573001234567">
  Número de teléfono en formato E.164 (ejemplo: `+573001234567`).
</ParamField>

<ParamField body="email" type="string" required>
  Correo electrónico de la empresa.
</ParamField>

<ParamField body="website" type="string" required>
  Sitio web de la empresa (URL válida).
</ParamField>

<ParamField body="economic_activity" type="string" required placeholder="0111">
  Código de actividad económica CIIU (4 dígitos).
</ParamField>

<ParamField body="industry" type="string" placeholder="0742">
  Código de industria (4 dígitos).
</ParamField>

<ParamField body="sales" type="integer" required placeholder="10, 35, 110, 240, 500">
  Rango de ventas anuales en millones COP. Valores permitidos: `10`, `35`, `110`, `240`, `500`.
</ParamField>

<ParamField body="fiscal_responsibilities" type="array" required>
  Lista de códigos de responsabilidades fiscales DIAN (ejemplo: `["O_47", "R_99_PN"]`).
</ParamField>

<ParamField body="retention_rules" type="object">
  Reglas de retención aplicables a la empresa.

  <Expandable title="Propiedades">
    <ParamField body="retention_rules.iva" type="boolean">
      Agente retenedor de IVA.
    </ParamField>

    <ParamField body="retention_rules.ica" type="boolean">
      Agente retenedor de ICA.
    </ParamField>

    <ParamField body="retention_rules.fuente" type="boolean">
      Agente retenedor de renta (retención en la fuente).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="city_id" type="integer" required>
  ID de la ciudad donde opera la empresa. Consulta el [endpoint de ciudades](/client/companies/list-cities) para obtener los IDs válidos.
</ParamField>

<ParamField body="address" type="object" required>
  Dirección de la empresa.

  <Expandable title="Propiedades">
    <ParamField body="address.address" type="string" required>
      Dirección principal (2-255 caracteres).
    </ParamField>

    <ParamField body="address.hint" type="string" required>
      Información adicional (oficina, piso, etc.).
    </ParamField>

    <ParamField body="address.zipcode" type="string" required>
      Código postal (5-9 dígitos).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="documents" type="object" required>
  URLs de los documentos legales de la empresa. Cada URL debe ser accesible públicamente para su descarga.

  <Expandable title="Propiedades">
    <ParamField body="documents.rut" type="string" required>
      URL del RUT de la empresa.
    </ParamField>

    <ParamField body="documents.ccc" type="string">
      URL del certificado de cámara de comercio. Requerido si `type` es `organization`.
    </ParamField>

    <ParamField body="documents.dni" type="string" required>
      URL del documento de identidad del representante legal.
    </ParamField>

    <ParamField body="documents.bank" type="string">
      URL de la certificación bancaria. Requerido si `type` es `organization`.
    </ParamField>

    <ParamField body="documents.simple" type="string">
      URL del certificado de régimen simple. Requerido si `O_47` está en `fiscal_responsibilities`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="company_owner" type="object">
  Información del representante legal. Requerido si `type` es `organization`.

  <Expandable title="Propiedades">
    <ParamField body="company_owner.name" type="string">
      Nombre del representante legal.
    </ParamField>

    <ParamField body="company_owner.last_name" type="string">
      Apellido del representante legal.
    </ParamField>

    <ParamField body="company_owner.phone" type="string">
      Teléfono del representante en formato E.164.
    </ParamField>

    <ParamField body="company_owner.email" type="string">
      Correo electrónico del representante.
    </ParamField>

    <ParamField body="company_owner.document_type" type="string" placeholder="cc, ce">
      Tipo de documento del representante: `cc` o `ce`.
    </ParamField>

    <ParamField body="company_owner.dni" type="string">
      Número de documento del representante.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="account" type="object">
  Cuenta bancaria para dispersiones. Opcional.

  <Expandable title="Propiedades">
    <ParamField body="account.type" type="string" placeholder="SAVINGS, CHECKING">
      Tipo de cuenta: `SAVINGS` (ahorros) o `CHECKING` (corriente).
    </ParamField>

    <ParamField body="account.bank_id" type="string">
      UUID del banco. Consulta el [endpoint de bancos](/client/accounts/list-banks) para obtener los IDs válidos.
    </ParamField>

    <ParamField body="account.number" type="string">
      Número de cuenta bancaria (5-40 caracteres).
    </ParamField>

    <ParamField body="account.terms" type="boolean">
      Aceptación de los términos y condiciones.
    </ParamField>
  </Expandable>
</ParamField>

<Note>
  Los usuarios de tu empresa que tengan el permiso `switch_company` serán vinculados automáticamente como miembros de la nueva empresa.
</Note>

### Response

<ResponseField name="id" type="string">
  Identificador único de la empresa.
</ResponseField>

<ResponseField name="name" type="string">
  Nombre comercial.
</ResponseField>

<ResponseField name="legal_name" type="string">
  Razón social.
</ResponseField>

<ResponseField name="phone" type="string">
  Teléfono de la empresa.
</ResponseField>

<ResponseField name="document_type" type="string">
  Tipo de documento.
</ResponseField>

<ResponseField name="document_number" type="string">
  Número de documento.
</ResponseField>

<ResponseField name="status" type="string">
  Estado de la empresa. Las empresas nuevas se crean con estado `pending`.
</ResponseField>

<ResponseField name="industry" type="string">
  Código de industria.
</ResponseField>

<ResponseField name="currency" type="string">
  Moneda de la empresa (por defecto `COP`).
</ResponseField>

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "9da58912-101d-46f8-86c9-20a52119c0bf",
    "name": "Acme Inc",
    "legal_name": "Acme Inc S.A.S",
    "phone": "+573001234567",
    "document_type": "NIT",
    "document_number": "123456789-1",
    "status": "pending",
    "industry": "0742",
    "currency": "COP"
  }
  ```

  ```json 422 theme={null}
  {
    "message": "El campo nombre es obligatorio. (y 5 errores más)",
    "code": 10001,
    "code_name": "validation_error",
    "errors": {
      "name": ["El campo nombre es obligatorio."],
      "document_type": ["El tipo de documento no es válido para el tipo de compañía seleccionado."],
      "fiscal_responsibilities": ["El campo fiscal responsibilities es obligatorio."]
    }
  }
  ```

  ```json 409 theme={null}
  {
    "message": "No se puede generar la operación, genera un token de idempotencia y envíelo en los headers como x-idempotency",
    "code": 10003,
    "code_name": "idempotency_error"
  }
  ```
</ResponseExample>

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.onepay.la/v1/companies \
    -X POST \
    -H "Authorization: Bearer sk_test_xxx" \
    -H "Content-Type: application/json" \
    -H "x-idempotency: company-001" \
    -d '{
      "type": "organization",
      "name": "Acme Inc",
      "legal_name": "Acme Inc S.A.S",
      "document_type": "NIT",
      "document_number": "123456789-1",
      "phone": "+573001234567",
      "email": "contacto@acme.co",
      "website": "https://acme.co",
      "economic_activity": "0111",
      "industry": "0742",
      "sales": 35,
      "fiscal_responsibilities": ["O_47"],
      "retention_rules": {
        "iva": true,
        "ica": false,
        "fuente": true
      },
      "city_id": 1,
      "address": {
        "address": "Calle 100 #15-20",
        "hint": "Oficina 301",
        "zipcode": "170004"
      },
      "documents": {
        "rut": "https://storage.example.com/rut.pdf",
        "ccc": "https://storage.example.com/ccc.pdf",
        "dni": "https://storage.example.com/dni.pdf",
        "bank": "https://storage.example.com/bank.pdf",
        "simple": "https://storage.example.com/simple.pdf"
      },
      "company_owner": {
        "name": "Juan",
        "last_name": "Pérez",
        "phone": "+573001234568",
        "email": "juan@acme.co",
        "document_type": "cc",
        "dni": "10000001"
      },
      "account": {
        "type": "savings",
        "bank_id": "9da58912-101d-46f8-86c9-20a52119c0bf",
        "number": "1234567890",
        "terms": true
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.onepay.la/v1/companies', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_test_xxx',
      'Content-Type': 'application/json',
      'x-idempotency': 'company-001'
    },
    body: JSON.stringify({
      type: 'organization',
      name: 'Acme Inc',
      legal_name: 'Acme Inc S.A.S',
      document_type: 'NIT',
      document_number: '123456789-1',
      phone: '+573001234567',
      email: 'contacto@acme.co',
      website: 'https://acme.co',
      economic_activity: '0111',
      industry: '0742',
      sales: 35,
      fiscal_responsibilities: ['O_47'],
      retention_rules: { iva: true, ica: false, fuente: true },
      city_id: 1,
      address: {
        address: 'Calle 100 #15-20',
        hint: 'Oficina 301',
        zipcode: '170004'
      },
      documents: {
        rut: 'https://storage.example.com/rut.pdf',
        ccc: 'https://storage.example.com/ccc.pdf',
        dni: 'https://storage.example.com/dni.pdf',
        bank: 'https://storage.example.com/bank.pdf',
        simple: 'https://storage.example.com/simple.pdf'
      },
      company_owner: {
        name: 'Juan',
        last_name: 'Pérez',
        phone: '+573001234568',
        email: 'juan@acme.co',
        document_type: 'cc',
        dni: '10000001'
      },
      account: {
        type: 'savings',
        bank_id: '9da58912-101d-46f8-86c9-20a52119c0bf',
        number: '1234567890',
        terms: true
      }
    })
  });

  const company = await response.json();
  console.log(company);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.onepay.la/v1/companies',
      headers={
          'Authorization': 'Bearer sk_test_xxx',
          'Content-Type': 'application/json',
          'x-idempotency': 'company-001'
      },
      json={
          'type': 'organization',
          'name': 'Acme Inc',
          'legal_name': 'Acme Inc S.A.S',
          'document_type': 'NIT',
          'document_number': '123456789-1',
          'phone': '+573001234567',
          'email': 'contacto@acme.co',
          'website': 'https://acme.co',
          'economic_activity': '0111',
          'industry': '0742',
          'sales': 35,
          'fiscal_responsibilities': ['O_47'],
          'retention_rules': {'iva': True, 'ica': False, 'fuente': True},
          'city_id': 1,
          'address': {
              'address': 'Calle 100 #15-20',
              'hint': 'Oficina 301',
              'zipcode': '170004'
          },
          'documents': {
              'rut': 'https://storage.example.com/rut.pdf',
              'ccc': 'https://storage.example.com/ccc.pdf',
              'dni': 'https://storage.example.com/dni.pdf',
              'bank': 'https://storage.example.com/bank.pdf',
              'simple': 'https://storage.example.com/simple.pdf'
          },
          'company_owner': {
              'name': 'Juan',
              'last_name': 'Pérez',
              'phone': '+573001234568',
              'email': 'juan@acme.co',
              'document_type': 'cc',
              'dni': '10000001'
          },
          'account': {
              'type': 'savings',
              'bank_id': '9da58912-101d-46f8-86c9-20a52119c0bf',
              'number': '1234567890',
              'terms': True
          }
      }
  )

  company = response.json()
  print(company)
  ```

  ```php PHP theme={null}
  <?php
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.onepay.la/v1/companies",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
      "Authorization: Bearer sk_test_xxx",
      "Content-Type: application/json",
      "x-idempotency: company-001"
    ],
    CURLOPT_POSTFIELDS => json_encode([
      "type" => "organization",
      "name" => "Acme Inc",
      "legal_name" => "Acme Inc S.A.S",
      "document_type" => "NIT",
      "document_number" => "123456789-1",
      "phone" => "+573001234567",
      "email" => "contacto@acme.co",
      "website" => "https://acme.co",
      "economic_activity" => "0111",
      "industry" => "0742",
      "sales" => 35,
      "fiscal_responsibilities" => ["O_47"],
      "retention_rules" => ["iva" => true, "ica" => false, "fuente" => true],
      "city_id" => 1,
      "address" => [
        "address" => "Calle 100 #15-20",
        "hint" => "Oficina 301",
        "zipcode" => "170004"
      ],
      "documents" => [
        "rut" => "https://storage.example.com/rut.pdf",
        "ccc" => "https://storage.example.com/ccc.pdf",
        "dni" => "https://storage.example.com/dni.pdf",
        "bank" => "https://storage.example.com/bank.pdf",
        "simple" => "https://storage.example.com/simple.pdf"
      ],
      "company_owner" => [
        "name" => "Juan",
        "last_name" => "Pérez",
        "phone" => "+573001234568",
        "email" => "juan@acme.co",
        "document_type" => "cc",
        "dni" => "10000001"
      ],
      "account" => [
        "type" => "savings",
        "bank_id" => "9da58912-101d-46f8-86c9-20a52119c0bf",
        "number" => "1234567890",
        "terms" => true
      ]
    ])
  ]);

  $response = curl_exec($curl);
  curl_close($curl);

  $company = json_decode($response, true);
  print_r($company);
  ?>
  ```
</RequestExample>