Eventos RADIAN

Emitir un evento RADIAN

POST /v1/radian_events · createRadianEvent

Envía un evento RADIAN sobre una factura: el acuse de recibo (030), el reclamo (031), el recibo del bien o servicio (032) y la aceptación expresa (033) de una factura RECIBIDA (invoice), o la aceptación tácita (034) de una factura PROPIA a crédito: de Trevol (invoice_id) o emitida antes con otro software y traída por la sincronización con la DIAN (invoice: {cufe, number?}; exactamente uno de los dos). Los eventos 035 a 051 necesitan un participante RADIAN y no están disponibles. El 030 y el 032 necesitan el representante legal de la empresa (lo firma): se configura en la app. Un rechazo es final: el siguiente intento es otro evento, con otro número (POST nuevo). Un evento vivo del mismo código sobre la misma factura es 409 duplicate_document con existing_id: reintenta ese con POST …/send. already_registered: true (con 201) solo significa que la DIAN ya mostraba el CUDE de ESTE evento; si la factura ya tenía ese evento por otro camino es 422 dian_rejected con already_registered_elsewhere: true. La DIAN pide el evento anterior antes del siguiente: en la 2026-10-21 es 409 previous_event_pending; en la 2026-10-22, 202 processing y Trevol lo manda cuando aparezca. Si la DIAN contesta 98 («en proceso de validación») es 202 validating: no reenvíes. Para saber si el 034 procede antes de pedirlo, usa GET /v1/invoices/{id}/tacit_acceptance (o, por CUFE, GET /v1/radian_events/tacit_acceptance?cufe=…).

Respuestas. 201 la DIAN lo validó (status: accepted). 202 solo en la versión 2026-10-22: la DIAN no contestó (processing), otra petición lo está enviando (sending) o, en habilitación, el set de pruebas todavía lo valida (validating, en las dos versiones); trae Location y Retry-After, y el resultado llega por GET y por webhook: no crees otro documento para la misma operación. 422 validation_error (se revisó a fondo ANTES de reservar: no se gastó el número, y errors[] dice el campo), dian_rejected (con document y las reglas traducidas; un rechazo es final: el siguiente intento es otro POST, con otro número), company_not_enabled o numbering_unavailable (con reason). 402 insufficient_balance (producción sin saldo: queda pending con su número). 409 external_id_in_use o duplicate_document (con existing_id). 503 dian_unavailable en la 2026-10-21. Pide Idempotency-Key: repetir la misma devuelve lo mismo sin enviar nada.

Parámetros

• Idempotency-Keycabeceratextoobligatorio
  Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).

Cuerpo (RadianEventInput, obligatorio)

• external_idtexto
  Tu identificador del documento: único entre los documentos API de la empresa y el ambiente. En los eventos es único entre los eventos (aparte de las facturas y las nóminas).
• event_codetextoobligatorio
  "030" acuse de recibo, "031" reclamo, "032" recibo del bien o servicio, "033" aceptación expresa (las cuatro sobre una factura RECIBIDA) o "034" aceptación tácita (sobre una factura PROPIA a crédito). Los 035 a 051 necesitan un participante RADIAN y no están disponibles.
• invoiceReceivedInvoice
  030–033: la factura RECIBIDA sobre la que va el evento (CUFE, número y quién la emitió). 034: la factura PROPIA por su CUFE, {cufe, number?} (solo esos dos), en lugar de invoice_id: sirve también para las facturas que no se emitieron con Trevol (las trae la sincronización con la DIAN). Si el CUFE es de una factura de Trevol, es lo mismo que mandar su invoice_id.
• invoice_idtexto
  034: el id (inv_…) de una factura de Trevol: propia, validada, a crédito y que no sea de consumidor final. Va aparte de invoice para que cada esquema sea plano en los SDK. Para una factura que no se emitió con Trevol, usa invoice: {cufe} (exactamente uno de los dos).
• claimEventClaim
  Solo en el reclamo (031) y obligatorio en él: {code: "01" a "04", note?}.
• softwareown | dian_free
  030–033: own (el Software Propio de la empresa, por defecto) o dian_free (el software gratuito de la DIAN). El 034 se firma con el Software Propio.
• providerdian | company
  030–033: quién es el proveedor tecnológico: dian (por defecto con dian_free) o company (por defecto con own).

Respuestas

Reenviar una pendiente o en error

POST /v1/radian_events/{id}/send · sendRadianEvent

Vuelve a enviar un evento pending o error con el mismo número (por ejemplo, un 034 que todavía no procedía o un 031 que esperaba al evento anterior). Un evento que la DIAN verifica (validating) solo consulta; uno rejected es final (409 invalid_state): crea otro con POST.

Sin cuerpo. Con un documento accepted responde 200 con el documento tal cual; con uno que la DIAN todavía verifica no reenvía nada (202); con uno rejected es 409 invalid_state (se corrige con PUT). No pide Idempotency-Key (reintentarlo es seguro).

Respuestas

Listar (evento RADIAN)

GET /v1/radian_events · listRadianEvents

Paginación por cursor y filtros status, external_id, created_from, created_to, event_code y invoice_cufe (el CUFE de la factura).

Parámetros

• limitconsultaentero
• starting_afterconsultatexto
• statusconsultatexto
• external_idconsultatexto
• created_fromconsultatexto
• created_toconsultatexto
• event_codeconsulta030 | 031 | 032 | 033 | 034
• invoice_cufeconsultatexto

Respuestas

Un evento radian

GET /v1/radian_events/{id} · retrieveRadianEvent

El evento tal como se envió, con su número, su CUDE, la factura y la respuesta de la DIAN. already_registered, already_registered_elsewhere y tacit se deducen de lo guardado.

Respuestas

Archivo xml

GET /v1/radian_events/{id}/xml · downloadRadianEventXml

El ApplicationResponse firmado que se mandó a la DIAN (application/xml). Los eventos no tienen PDF, ZIP ni dian_response.

Respuestas

¿Procede ya la aceptación tácita (034) de esta factura? (por CUFE)

GET /v1/radian_events/tacit_acceptance · retrieveTacitAcceptanceByCufe

Lo mismo que GET /v1/invoices/{id}/tacit_acceptance, pero por el CUFE de la factura propia: sirve también para las facturas que no se emitieron con Trevol (emitidas antes, con otro software, y traídas por la sincronización con la DIAN; la sincronización trae las de producción). Consulta GetStatusEvent y aplica la regla de los 3 días hábiles; no envía nada. invoice_id solo sale si la factura es de Trevol. 404 si el CUFE no es de una factura propia de la empresa y el ambiente de la llave; 422 si falta cufe o la factura no admite el 034 (de contado, una nota, a consumidor final, sin el XML leído por la sincronización…); 429 con más de 30 consultas por minuto por llave (el mismo límite de la otra consulta); 503 si la DIAN no contesta (reintentable).

Parámetros

• cufeconsultatextoobligatorio
  El CUFE de la factura propia.

Respuestas