Ir al contenido

Registrar rango de numeración / resolución

POST
/v1/tenant/numbering-ranges
curl --request POST \
--url https://example.com/v1/tenant/numbering-ranges \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "kind": "invoice", "prefix": "", "from": 1, "to": 1, "current": 1, "resolutionNumber": "example", "resolutionDate": "2026-04-15", "validFrom": "2026-04-15", "validTo": "2026-04-15", "technicalKey": "example", "active": true }'
X-Tenant-Id
string

Id o NIT del facturador. Obligatorio con llaves de cuenta; ignorado con llaves restringidas.

Media typeapplication/json

Un rango de numeración, con resolución de la DIAN o propio del facturador

object
kind
required

Tipo de documento que numera

string
Allowed values: invoice credit_note debit_note support_document support_document_adjustment pos_document pos_credit_adjustment pos_debit_adjustment payroll payroll_adjustment radian_event
prefix

Prefijo que va antes del número: hasta 4 caracteres, vacío por defecto

string
"" <= 4 characters
from
required

Primer número autorizado

integer
<= 9007199254740991
to
required

Último número autorizado

integer
> 0 <= 9007199254740991
current

Último número ya usado (0, por defecto, si no se ha usado ninguno: el siguiente es from)

integer
<= 9007199254740991
resolutionNumber

Número de la resolución de la DIAN; obligatorio para facturas, documentos soporte y documentos POS

string
<= 50 characters
resolutionDate

Fecha de la resolución

string format: date
validFrom

Primer día de vigencia de la resolución

string format: date
validTo

Último día de vigencia de la resolución; después de él no se puede emitir

string format: date
technicalKey

Clave técnica de la resolución, del portal de la DIAN; obligatoria para facturas de venta (entra en el CUFE)

string
<= 100 characters
active

Si está en uso (true por defecto); el rango activo más reciente de un tipo es el que numera sus documentos

boolean

Rango creado

Media typeapplication/json
object
data
required

Rango creado

object
id
required

Id del rango (rangeId al emitir)

string
tenantId
required

Id del facturador

string
kind
required

Tipo de documento que numera

string
Allowed values: invoice credit_note debit_note support_document support_document_adjustment pos_document pos_credit_adjustment pos_debit_adjustment payroll payroll_adjustment radian_event
prefix
required

Prefijo que va antes del número (puede estar vacío)

string
from
required

Primer número autorizado

integer
>= -9007199254740991 <= 9007199254740991
to
required

Último número autorizado

integer
>= -9007199254740991 <= 9007199254740991
current
required

Último número asignado (0: aún no se usa)

integer
>= -9007199254740991 <= 9007199254740991
resolutionNumber

Número de la resolución de la DIAN

string
resolutionDate

Fecha de la resolución (YYYY-MM-DD)

string
validFrom

Primer día de vigencia de la resolución (YYYY-MM-DD)

string
validTo

Último día de vigencia de la resolución (YYYY-MM-DD)

string
technicalKey

Clave técnica (solo factura de venta)

string
active
required

Si está en uso; el rango activo más reciente de un tipo es el que numera sus documentos

boolean
createdAt
required

Cuándo se creó

string format: date-time

Example

{
"data": {
"kind": "invoice",
"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"
}
}