Registrar evento RADIAN
const url = 'https://example.com/v1/radian-events?wait=true';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"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"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}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" }'Authorizations
Sección titulada «Authorizations»Parameters
Sección titulada «Parameters»Header Parameters
Sección titulada «Header Parameters»Id o NIT del facturador. Obligatorio con llaves de cuenta; ignorado con llaves restringidas.
Repetir la petición con la misma llave devuelve el mismo documento, sin emitir otro.
Solo con API keys de sandbox (sk_sandbox_…): elige el resultado de la DIAN simulada: accepted (por defecto), rejected:
Query Parameters
Sección titulada «Query Parameters»True: espera la respuesta de la DIAN en la misma petición
Request Bodyrequired
Sección titulada «Request Bodyrequired»Un evento RADIAN que el facturador registra sobre una factura electrónica
object
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
La factura sobre la que es el evento
object
Número completo de la factura, con prefijo
CUFE de la factura: 96 caracteres hexadecimales
Tipo de la factura; 01 (factura electrónica de venta) si no se envía
Quién recibe el evento: la otra parte de la factura (para 030 a 033, el emisor de la factura)
object
1 = persona jurídica, 2 = persona natural
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
Número del documento de identidad, sin dígito de verificación
Dígito de verificación del NIT; obligatorio cuando idType es 31
Razón social
La persona que realiza el evento por el facturador; obligatoria para 030 y 032 (quien recibió)
object
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
Número del documento de identidad de la persona
Nombres de la persona
Apellidos de la persona
Cargo de la persona
Dependencia o área de la persona
Motivo del reclamo; obligatorio para 031: 01 documento con inconsistencias, 02 mercancía no entregada, 03 mercancía entregada parcialmente, 04 servicio no prestado
Una nota de texto libre
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
Responses
Sección titulada «Responses»Documento creado (201) o el mismo de antes con la misma Idempotency-Key (200)
object
Documento creado (201) o el mismo de antes con la misma Idempotency-Key (200)
object
Id del documento
Tipo de documento
Pending → sent → accepted / rejected; retrying y failed cuando la DIAN no responde
Ambiente DIAN: 1 = producción, 2 = habilitación (pruebas)
True cuando se emitió con una API key de sandbox (DIAN simulada, sin consumir bolsa)
Número completo (prefijo + consecutivo)
Prefijo del rango de numeración (puede estar vacío)
Consecutivo dentro del rango
CUFE, CUDE, CUDS o CUNE
Tipo y algoritmo del código único, ej. CUFE-SHA384
Cuándo se emitió; la fecha y hora del XML son este instante en hora de Bogotá
Sus valores y su contraparte
object
Valor del documento: el total a pagar, o el total de la nómina
Valor antes de impuestos (en nómina, los devengados)
Impuestos (en nómina, las deducciones)
Moneda, ISO 4217
Número de identificación de la contraparte: el comprador, el vendedor o el empleado
Nombre de la contraparte
Contenido del código QR de la representación gráfica
Lo que respondió la DIAN
object
Último código de estado de la DIAN: 00 procesado correctamente, 99 rechazado (null: aún sin respuesta)
Último texto de estado de la DIAN (null: aún sin respuesta)
Reglas de validación que la DIAN reportó
Llave de seguimiento de la DIAN (ZipKey), para documentos enviados al set de pruebas (null en los demás)
Cuántas veces se envió o se consultó su estado
Último error transitorio (la DIAN caída, un timeout); null una vez pasa
Documento al que hace referencia: una nota, a su factura; un ajuste, a su nómina (null: ninguno)
Cuándo se creó
Cuándo cambió por última vez
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)
Un error: un código estable para los programas y un mensaje para los desarrolladores
object
El error
object
Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)
Qué salió mal, para desarrolladores (puede cambiar; compare por code)
Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué
Id de la petición, para soporte
Example generated
{ "error": { "code": "example", "message": "example", "details": "example", "requestId": "example" }}Falta la credencial o no es válida (UNAUTHORIZED)
Un error: un código estable para los programas y un mensaje para los desarrolladores
object
El error
object
Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)
Qué salió mal, para desarrolladores (puede cambiar; compare por code)
Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué
Id de la petición, para soporte
Example generated
{ "error": { "code": "example", "message": "example", "details": "example", "requestId": "example" }}Sin saldo de documentos (INSUFFICIENT_BALANCE)
Un error: un código estable para los programas y un mensaje para los desarrolladores
object
El error
object
Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)
Qué salió mal, para desarrolladores (puede cambiar; compare por code)
Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué
Id de la petición, para soporte
Example generated
{ "error": { "code": "example", "message": "example", "details": "example", "requestId": "example" }}La llave no puede hacer esto (FORBIDDEN)
Un error: un código estable para los programas y un mensaje para los desarrolladores
object
El error
object
Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)
Qué salió mal, para desarrolladores (puede cambiar; compare por code)
Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué
Id de la petición, para soporte
Example generated
{ "error": { "code": "example", "message": "example", "details": "example", "requestId": "example" }}No existe, o no es de esta cuenta (NOT_FOUND)
Un error: un código estable para los programas y un mensaje para los desarrolladores
object
El error
object
Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)
Qué salió mal, para desarrolladores (puede cambiar; compare por code)
Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué
Id de la petición, para soporte
Example generated
{ "error": { "code": "example", "message": "example", "details": "example", "requestId": "example" }}Conflicto con el estado actual (CONFLICT, INVALID_STATE)
Un error: un código estable para los programas y un mensaje para los desarrolladores
object
El error
object
Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)
Qué salió mal, para desarrolladores (puede cambiar; compare por code)
Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué
Id de la petición, para soporte
Example generated
{ "error": { "code": "example", "message": "example", "details": "example", "requestId": "example" }}Regla de negocio (VALIDATION_ERROR, NUMBERING_*, CERTIFICATE_UNAVAILABLE…)
Un error: un código estable para los programas y un mensaje para los desarrolladores
object
El error
object
Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)
Qué salió mal, para desarrolladores (puede cambiar; compare por code)
Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué
Id de la petición, para soporte
Example generated
{ "error": { "code": "example", "message": "example", "details": "example", "requestId": "example" }}Demasiadas peticiones para esta cuenta (RATE_LIMITED; vea X-RateLimit-* y Retry-After)
Un error: un código estable para los programas y un mensaje para los desarrolladores
object
El error
object
Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)
Qué salió mal, para desarrolladores (puede cambiar; compare por code)
Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué
Id de la petición, para soporte
Example generated
{ "error": { "code": "example", "message": "example", "details": "example", "requestId": "example" }}Error del servicio o de la DIAN (DIAN_UNAVAILABLE, DIAN_PROTOCOL_ERROR)
Un error: un código estable para los programas y un mensaje para los desarrolladores
object
El error
object
Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)
Qué salió mal, para desarrolladores (puede cambiar; compare por code)
Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué
Id de la petición, para soporte
Example generated
{ "error": { "code": "example", "message": "example", "details": "example", "requestId": "example" }}