Ir al contenido

Registrar facturador (NIT)

POST
/v1/tenants
curl --request POST \
--url https://example.com/v1/tenants \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "nit": "example", "dv": "example", "idType": "11", "personType": "1", "legalName": "example", "tradeName": "example", "taxResponsibilities": [ "example" ], "taxScheme": "01", "address": { "line": "example", "cityCode": "example", "cityName": "example", "departmentCode": "example", "departmentName": "example", "postalCode": "example", "countryCode": "CO", "countryName": "example" }, "email": "hello@example.com", "phone": "example", "merchantRegistration": "example", "industryCodes": [ "example" ] }'
Media typeapplication/json

Un facturador: un NIT de la cuenta, con su propia configuración ante la DIAN

object
nit
required

NIT, de 5 a 15 dígitos, sin dígito de verificación; único en la cuenta

string
/^\d{5,15}$/
dv
required

Dígito de verificación del NIT; se valida contra el NIT

string
/^\d$/
idType

Tipo de documento de identidad; 31 (NIT) por defecto

string
default: 31
Allowed values: 11 12 13 21 22 31 41 42 47 48 50 91
personType
required

1 = persona jurídica, 2 = persona natural

string
Allowed values: 1 2
legalName
required

Razón social, como figura en el RUT

string
>= 1 characters <= 450 characters
tradeName

Nombre comercial, si es distinto

string
<= 450 characters
taxResponsibilities
required

Sus responsabilidades fiscales del RUT (los códigos de GET /v1/catalogs/tax-responsibilities, del Anexo Técnico 1.9): O-13 gran contribuyente, O-15 autorretenedor, O-23 agente de retención de IVA, O-47 régimen simple, O-48 responsable de IVA, O-49 no responsable de IVA, R-99-PN no responsable

Array<string>
>= 1 items <= 20 items
taxScheme
required

Su régimen tributario: 01 IVA, 04 INC, ZA IVA e INC, ZZ no aplica

string
Allowed values: 01 04 ZA ZZ
address
required

Su dirección fiscal

object
line
required

La dirección, ej. “Calle 100 # 10-20”

string
>= 1 characters <= 300 characters
cityCode
required

Código DIVIPOLA del municipio, 5 dígitos, ej. 11001 (Bogotá)

string
/^\d{5}$/
cityName
required

Nombre del municipio

string
>= 1 characters <= 100 characters
departmentCode
required

Código DIVIPOLA del departamento, 2 dígitos, ej. 11 (Bogotá D.C.)

string
/^\d{2}$/
departmentName
required

Nombre del departamento

string
>= 1 characters <= 100 characters
postalCode

Código postal

string
<= 10 characters
countryCode

País, ISO 3166-1 alfa-2; CO por defecto

string
default: CO >= 2 characters <= 2 characters
countryName

Nombre del país en español; Colombia si el país es CO y no se envía

string
<= 100 characters
email
required

Su correo de facturación electrónica; aparece en sus documentos

string format: email
<= 200 characters
phone

Teléfono de contacto

string
<= 50 characters
merchantRegistration

Número de matrícula mercantil en la cámara de comercio

string
<= 50 characters
industryCodes

Sus actividades económicas según su RUT: códigos CIIU de 4 dígitos, hasta 4, p. ej. [“6201”]. Se escriben en sus documentos (IndustryClassificationCode)

Array<string>
<= 4 items

Facturador creado

Media typeapplication/json
object
data
required

Facturador creado

object
id
required

Id del facturador; X-Tenant-Id recibe este id o el NIT

string
accountId
required

La cuenta dueña

string
nit
required

NIT, sin dígito de verificación

string
dv
required

Dígito de verificación del NIT

string
idType
required

Tipo de documento de identidad (31: NIT)

string
personType
required

1 = persona jurídica, 2 = persona natural

string
legalName
required

Razón social, como figura en el RUT

string
tradeName

Nombre comercial, si es distinto

string
taxResponsibilities
required

Sus responsabilidades fiscales del RUT (O-13, O-15…)

Array<string>
taxScheme
required

Su régimen tributario: 01 IVA, 04 INC, ZA IVA e INC, ZZ no aplica

string
address
required

Su dirección fiscal

object
line
required

La dirección

string
cityCode
required

Código DIVIPOLA del municipio

string
cityName
required

Nombre del municipio

string
departmentCode
required

Código DIVIPOLA del departamento

string
departmentName
required

Nombre del departamento

string
postalCode

Código postal

string
countryCode
required

País, ISO 3166-1 alfa-2

string
countryName

Nombre del país

string
email
required

Su correo de facturación electrónica; aparece en sus documentos

string
phone

Teléfono de contacto

string
merchantRegistration

Número de matrícula mercantil en la cámara de comercio

string
industryCodes

Sus actividades económicas: códigos CIIU de 4 dígitos

Array<string>
status
required

Active, o suspended: un facturador suspendido no puede emitir

string
Allowed values: active suspended
createdAt
required

Cuándo se creó

string format: date-time

Example

{
"data": {
"status": "active",
"createdAt": "2026-01-15T15:30:00.000Z"
}
}

La petición no cumple el esquema (VALIDATION_ERROR, con details por campo)

Media typeapplication/json

Un error: un código estable para los programas y un mensaje para los desarrolladores

object
error
required

El error

object
code
required

Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)

string
message
required

Qué salió mal, para desarrolladores (puede cambiar; compare por code)

string
details

Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué

requestId

Id de la petición, para soporte

string

Example generated

{
"error": {
"code": "example",
"message": "example",
"details": "example",
"requestId": "example"
}
}

Falta la credencial o no es válida (UNAUTHORIZED)

Media typeapplication/json

Un error: un código estable para los programas y un mensaje para los desarrolladores

object
error
required

El error

object
code
required

Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)

string
message
required

Qué salió mal, para desarrolladores (puede cambiar; compare por code)

string
details

Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué

requestId

Id de la petición, para soporte

string

Example generated

{
"error": {
"code": "example",
"message": "example",
"details": "example",
"requestId": "example"
}
}

La llave no puede hacer esto (FORBIDDEN)

Media typeapplication/json

Un error: un código estable para los programas y un mensaje para los desarrolladores

object
error
required

El error

object
code
required

Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)

string
message
required

Qué salió mal, para desarrolladores (puede cambiar; compare por code)

string
details

Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué

requestId

Id de la petición, para soporte

string

Example generated

{
"error": {
"code": "example",
"message": "example",
"details": "example",
"requestId": "example"
}
}

No existe, o no es de esta cuenta (NOT_FOUND)

Media typeapplication/json

Un error: un código estable para los programas y un mensaje para los desarrolladores

object
error
required

El error

object
code
required

Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)

string
message
required

Qué salió mal, para desarrolladores (puede cambiar; compare por code)

string
details

Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué

requestId

Id de la petición, para soporte

string

Example generated

{
"error": {
"code": "example",
"message": "example",
"details": "example",
"requestId": "example"
}
}

Conflicto con el estado actual (CONFLICT, INVALID_STATE)

Media typeapplication/json

Un error: un código estable para los programas y un mensaje para los desarrolladores

object
error
required

El error

object
code
required

Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)

string
message
required

Qué salió mal, para desarrolladores (puede cambiar; compare por code)

string
details

Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué

requestId

Id de la petición, para soporte

string

Example generated

{
"error": {
"code": "example",
"message": "example",
"details": "example",
"requestId": "example"
}
}

Regla de negocio (VALIDATION_ERROR, NUMBERING_*, CERTIFICATE_UNAVAILABLE…)

Media typeapplication/json

Un error: un código estable para los programas y un mensaje para los desarrolladores

object
error
required

El error

object
code
required

Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)

string
message
required

Qué salió mal, para desarrolladores (puede cambiar; compare por code)

string
details

Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué

requestId

Id de la petición, para soporte

string

Example generated

{
"error": {
"code": "example",
"message": "example",
"details": "example",
"requestId": "example"
}
}

Demasiadas peticiones para esta cuenta (RATE_LIMITED; vea X-RateLimit-* y Retry-After)

Media typeapplication/json

Un error: un código estable para los programas y un mensaje para los desarrolladores

object
error
required

El error

object
code
required

Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)

string
message
required

Qué salió mal, para desarrolladores (puede cambiar; compare por code)

string
details

Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué

requestId

Id de la petición, para soporte

string

Example generated

{
"error": {
"code": "example",
"message": "example",
"details": "example",
"requestId": "example"
}
}

Error del servicio o de la DIAN (DIAN_UNAVAILABLE, DIAN_PROTOCOL_ERROR)

Media typeapplication/json

Un error: un código estable para los programas y un mensaje para los desarrolladores

object
error
required

El error

object
code
required

Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)

string
message
required

Qué salió mal, para desarrolladores (puede cambiar; compare por code)

string
details

Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué

requestId

Id de la petición, para soporte

string

Example generated

{
"error": {
"code": "example",
"message": "example",
"details": "example",
"requestId": "example"
}
}