Ir al contenido

Crear API key (de cuenta o restringida a un facturador)

POST
/v1/api-keys
curl --request POST \
--url https://example.com/v1/api-keys \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "name": "example", "tenantId": "example", "environment": "test" }'
Media typeapplication/json

Una API key nueva

object
name
required

Un nombre para distinguir las llaves, ej. “ERP producción”

string
>= 1 characters <= 100 characters
tenantId

Restringe la llave a un facturador, por su id (una llave para entregarle a ese facturador); null o sin enviar: llave de cuenta, para cualquiera de sus facturadores

Any of:
string
<= 36 characters
environment

Ambiente de la llave (prefijo sk_test_, sk_live_ o sk_sandbox_); test por defecto. sandbox enruta las peticiones a una DIAN simulada controlada por X-Sandbox-Outcome y nunca consume bolsas; en test y live, el software del facturador elige el ambiente DIAN

string
default: test
Allowed values: test live sandbox

La llave, con su secreto

Media typeapplication/json
object
data
required

La llave, con su secreto

object
id
required

Id de la llave (para revocarla)

string
name
required

Nombre que se le dio

string
prefix
required

Inicio visible de la llave, para reconocerla

string
tenantId
required

Facturador al que está restringida (null: llave de cuenta)

string | null
environment
required

Ambiente de la llave en su prefijo: sk_test_, sk_live_ o sk_sandbox_ (DIAN simulada, sin consumir bolsas)

string
Allowed values: test live sandbox
createdAt
required

Cuándo se creó

string format: date-time
lastUsedAt
required

Cuándo la usó la última petición (null: nunca)

Any of:

Fecha y hora en UTC (ISO 8601)

string format: date-time
revokedAt
required

Cuándo se revocó (null: funciona); una llave revocada se rechaza

Any of:

Fecha y hora en UTC (ISO 8601)

string format: date-time
secret
required

La llave completa (sk_test_… / sk_live_… / sk_sandbox_…). Solo se muestra esta vez: guárdela

string

Example

{
"data": {
"environment": "test",
"createdAt": "2026-01-15T15:30:00.000Z",
"lastUsedAt": "2026-01-15T15:30:00.000Z",
"revokedAt": "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"
}
}