Ir al contenido

Registrar evento RADIAN

POST
/v1/radian-events
curl --request POST \
--url 'https://example.com/v1/radian-events?wait=true' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "eventCode": "030", "documentReference": { "number": "example", "cufe": "example", "typeCode": "example" }, "receiver": { "personType": "1", "idType": "11", "idNumber": "example", "dv": "example", "name": "example" }, "issuerPerson": { "idType": "11", "idNumber": "example", "firstName": "example", "familyName": "example", "jobTitle": "example", "department": "example" }, "claimConcept": "01", "note": "example", "rangeId": "example" }'
X-Tenant-Id
string

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

Idempotency-Key
string
<= 255 characters

Repetir la petición con la misma llave devuelve el mismo documento, sin emitir otro.

X-Sandbox-Outcome
string
<= 60 characters

Solo con API keys de sandbox (sk_sandbox_…): elige el resultado de la DIAN simulada: accepted (por defecto), rejected: (ej. rejected:FAD06), timeout, rule90:accepted, rule90:rejected: o rule90:pending. Se rechaza con otras llaves.

wait
string
Allowed values: true false

True: espera la respuesta de la DIAN en la misma petición

Media typeapplication/json

Un evento RADIAN que el facturador registra sobre una factura electrónica

object
eventCode
required

El evento: 030 acuse de recibo de la factura, 031 reclamo, 032 recibo del bien o servicio, 033 aceptación expresa, 034 aceptación tácita

string
Allowed values: 030 031 032 033 034
documentReference
required

La factura sobre la que es el evento

object
number
required

Número completo de la factura, con prefijo

string
>= 1 characters <= 30 characters
cufe
required

CUFE de la factura: 96 caracteres hexadecimales

string
/^[0-9a-f]{96}$/
typeCode

Tipo de la factura; 01 (factura electrónica de venta) si no se envía

string
<= 4 characters
receiver
required

Quién recibe el evento: la otra parte de la factura (para 030 a 033, el emisor de la factura)

object
personType
required

1 = persona jurídica, 2 = persona natural

string
Allowed values: 1 2
idType
required

Tipo de documento de identidad (tabla 13.2.1): 11 registro civil, 12 tarjeta de identidad, 13 cédula de ciudadanía, 21 tarjeta de extranjería, 22 cédula de extranjería, 31 NIT, 41 pasaporte, 42 documento de identificación extranjero, 47 PEP, 48 PPT, 50 NIT de otro país, 91 NUIP

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

Número del documento de identidad, sin dígito de verificación

string
>= 1 characters <= 20 characters
dv

Dígito de verificación del NIT; obligatorio cuando idType es 31

string
/^\d$/
name
required

Razón social

string
>= 1 characters <= 450 characters
issuerPerson

La persona que realiza el evento por el facturador; obligatoria para 030 y 032 (quien recibió)

object
idType
required

Tipo de documento de identidad (tabla 13.2.1): 11 registro civil, 12 tarjeta de identidad, 13 cédula de ciudadanía, 21 tarjeta de extranjería, 22 cédula de extranjería, 31 NIT, 41 pasaporte, 42 documento de identificación extranjero, 47 PEP, 48 PPT, 50 NIT de otro país, 91 NUIP

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

Número del documento de identidad de la persona

string
>= 1 characters <= 20 characters
firstName
required

Nombres de la persona

string
>= 1 characters <= 100 characters
familyName
required

Apellidos de la persona

string
>= 1 characters <= 100 characters
jobTitle

Cargo de la persona

string
<= 100 characters
department

Dependencia o área de la persona

string
<= 100 characters
claimConcept

Motivo del reclamo; obligatorio para 031: 01 documento con inconsistencias, 02 mercancía no entregada, 03 mercancía entregada parcialmente, 04 servicio no prestado

string
Allowed values: 01 02 03 04
note

Una nota de texto libre

string
<= 5000 characters
rangeId

Rango de numeración a usar, por su id; si no se envía, el rango activo más reciente del facturador para ese tipo

string
<= 36 characters

Documento creado (201) o el mismo de antes con la misma Idempotency-Key (200)

Media typeapplication/json
object
data
required

Documento creado (201) o el mismo de antes con la misma Idempotency-Key (200)

object
id
required

Id del documento

string
kind
required

Tipo de documento

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
status
required

Pending → sent → accepted / rejected; retrying y failed cuando la DIAN no responde

string
Allowed values: pending sent retrying accepted rejected failed
environment
required

Ambiente DIAN: 1 = producción, 2 = habilitación (pruebas)

string
Allowed values: 1 2
sandbox
required

True cuando se emitió con una API key de sandbox (DIAN simulada, sin consumir bolsa)

boolean
number
required

Número completo (prefijo + consecutivo)

string
prefix
required

Prefijo del rango de numeración (puede estar vacío)

string
consecutive
required

Consecutivo dentro del rango

integer
>= -9007199254740991 <= 9007199254740991
uniqueCode
required

CUFE, CUDE, CUDS o CUNE

string
uniqueCodeScheme
required

Tipo y algoritmo del código único, ej. CUFE-SHA384

string
issuedAt
required

Cuándo se emitió; la fecha y hora del XML son este instante en hora de Bogotá

string format: date-time
summary
required

Sus valores y su contraparte

object
total
required

Valor del documento: el total a pagar, o el total de la nómina

string
subtotal

Valor antes de impuestos (en nómina, los devengados)

string
taxes

Impuestos (en nómina, las deducciones)

string
currency
required

Moneda, ISO 4217

string
counterpartyId

Número de identificación de la contraparte: el comprador, el vendedor o el empleado

string
counterpartyName

Nombre de la contraparte

string
qrData
required

Contenido del código QR de la representación gráfica

string
dian
required

Lo que respondió la DIAN

object
statusCode
required

Último código de estado de la DIAN: 00 procesado correctamente, 99 rechazado (null: aún sin respuesta)

string | null
statusMessage
required

Último texto de estado de la DIAN (null: aún sin respuesta)

string | null
errors
required

Reglas de validación que la DIAN reportó

Array<string>
zipKey
required

Llave de seguimiento de la DIAN (ZipKey), para documentos enviados al set de pruebas (null en los demás)

string | null
attempts
required

Cuántas veces se envió o se consultó su estado

integer
>= -9007199254740991 <= 9007199254740991
nextAttemptAt
required

Cuándo toca el próximo envío o consulta (null: ninguno pendiente)

Any of:

Fecha y hora en UTC (ISO 8601)

string format: date-time
lastError
required

Último error transitorio (la DIAN caída, un timeout); null una vez pasa

string | null
referencedDocumentId
required

Documento al que hace referencia: una nota, a su factura; un ajuste, a su nómina (null: ninguno)

string | null
acceptedAt
required

Cuándo lo aceptó la DIAN (null: no aceptado)

Any of:

Fecha y hora en UTC (ISO 8601)

string format: date-time
createdAt
required

Cuándo se creó

string format: date-time
updatedAt
required

Cuándo cambió por última vez

string format: date-time

Example

{
"data": {
"kind": "invoice",
"status": "pending",
"environment": "1",
"issuedAt": "2026-01-15T15:30:00.000Z",
"nextAttemptAt": "2026-01-15T15:30:00.000Z",
"acceptedAt": "2026-01-15T15:30:00.000Z",
"createdAt": "2026-01-15T15:30:00.000Z",
"updatedAt": "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"
}
}

Sin saldo de documentos (INSUFFICIENT_BALANCE)

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"
}
}