Errores comunes al registrar eventos RADIAN: diagnóstico y checklist de integración

Por Ing. Carlos Méndez | 15 de octubre de 2026

Ing. Carlos Méndez es arquitecto de software con más de 10 años integrando sistemas fiscales en América Latina. Ha liderado implementaciones de facturación electrónica en Colombia, México y Centroamérica para ISVs de mediana y gran escala.

Los errores al registrar eventos RADIAN se concentran en cinco causas: eventos enviados fuera del orden requerido, plazos vencidos, XML o firma inválidos, causales de reclamo incorrectas y reintentos que duplican un evento ya registrado; cada una deja una huella distinta en la respuesta de validación de la DIAN y se resuelve con un cambio concreto. Lo que cuesta tiempo no es corregirlas sino reconocerlas, porque muchos equipos tratan todo rechazo como un error genérico de comunicación.

Esta guía ofrece una matriz de diagnóstico por síntoma, explica cómo leer las respuestas de la DIAN, y cierra con un checklist previo a producción. Es el artículo de soporte del cluster de eventos RADIAN, cuyo pilar es la guía técnica de eventos RADIAN.

Cómo leer la respuesta de validación de la DIAN

Cada evento enviado recibe una respuesta de validación que distingue entre aceptación, aceptación con notificaciones y rechazo. Las reglas de validación del anexo técnico se clasifican por severidad: las que provocan rechazo impiden que el evento quede registrado, mientras que las notificaciones lo dejan registrado pero advierten una inconsistencia. Un sistema debe guardar la respuesta completa, no solo el estado final, porque el detalle de la regla incumplida es lo que permite diagnosticar.

Un error habitual es mapear toda respuesta distinta de aceptada a un reintento automático. Un rechazo por regla de negocio, como una causal inválida o un evento fuera de orden, no se corrige reintentando: se corrige cambiando el contenido o resolviendo primero el evento previo. Solo los fallos de transporte (timeouts, indisponibilidad) justifican un reintento.

Matriz de diagnóstico por síntoma

Síntoma                                   | Causa probable                          | Corrección
------------------------------------------|-----------------------------------------|-------------------------------------------
Rechazo al enviar 033 o 034               | Falta 030 o 032 previo                  | Registrar primero los eventos prerrequisito
Rechazo al enviar 031                     | Plazo vencido o causal inválida         | Verificar fecha límite y lista de causales
Rechazo por firma                         | Certificado vencido o XAdES mal formado | Renovar certificado; validar la firma local
Rechazo por referencia                    | CUFE inexistente o de otro NIT          | Validar CUFE y NIT antes de enviar
Evento registrado dos veces               | Reintento tras timeout                  | Idempotencia por CUFE + tipo de evento
Estado local distinto al de la DIAN       | Evento registrado por otro canal        | Reconciliación periódica por consulta
Aceptación tácita inesperada               | Alertas ausentes o festivo mal contado  | Calendario de festivos y alertas escalonadas

Errores de orden y de plazo

Los errores de orden aparecen cuando el sistema permite enviar un evento sin que existan sus prerrequisitos: una aceptación sin recibo del bien, un reclamo sobre una factura ya aceptada. La defensa es una máquina de estados local que bloquee la transición antes de llamar a la API, y no depender de que la DIAN rechace. Es más barato y da al usuario un mensaje comprensible. El detalle del orden correcto está en la guía de acuse de recibo y recibo del bien.

Los errores de plazo tienen dos orígenes: contar días corridos en lugar de hábiles, y usar un calendario de festivos desactualizado. Ambos desplazan el vencimiento y provocan o bien un reclamo tardío o bien una aceptación tácita no deseada. Los plazos y su efecto están desarrollados en las guías de aceptación tácita y expresa y del reclamo de la factura.

Errores de firma, XML y referencias

Los eventos se firman con XAdES y deben respetar el esquema ApplicationResponse del anexo técnico. Los fallos más frecuentes son certificados vencidos, cadenas de certificación incompletas, codificación de caracteres inconsistente y cálculo incorrecto del CUDE por variaciones en el formato de fecha u hora. Conviene validar el XML y la firma localmente contra el esquema antes de enviar, y alertar con antelación al vencimiento del certificado.

Los errores de referencia ocurren cuando el CUFE de la factura no existe, está mal copiado o pertenece a un NIT distinto al del participante que envía el evento. Es una validación barata de hacer del lado del ISV: confirmar que la factura está en el sistema local con su CUFE y que el NIT coincide, antes de construir el documento.

Duplicados, reintentos y reconciliación

Un timeout durante el envío deja al cliente sin saber si el evento se registró. Reintentar a ciegas puede producir duplicados o un rechazo por evento ya existente. El patrón correcto es consultar primero el estado de la factura ante la DIAN o el proveedor, y reenviar solo si el evento no consta. La clave de idempotencia natural es la combinación del CUFE y el tipo de evento, con la salvedad de los eventos que pueden repetirse legítimamente, como endosos sucesivos.

La reconciliación periódica cubre el caso complementario: eventos que se registraron por un canal ajeno al sistema, por ejemplo directamente por el adquirente en un portal. Un proceso diario que consulte el estado de las facturas con eventos pendientes y actualice el estado local evita que el cliente vea información desactualizada. Como referencia, la API de facturación electrónica de Alanube para Colombia expone el registro y la consulta de eventos RADIAN por API REST y por un servidor MCP, que permiten resolver tanto el registro programado como la consulta de estado.

Checklist previo a producción

[ ] Máquina de estados local que bloquea transiciones inválidas
[ ] Cálculo de plazo en días hábiles con calendario de festivos actualizado
[ ] Fecha límite guardada al registrar el evento 032
[ ] Alertas escalonadas antes del vencimiento
[ ] Causal de reclamo como enumerado validado contra el anexo vigente
[ ] Validación local de XML y firma antes de enviar
[ ] Monitoreo de vencimiento del certificado de firma
[ ] Idempotencia por CUFE + tipo de evento
[ ] Reintentos solo ante fallos de transporte, no ante rechazos de negocio
[ ] Persistencia de CUFE, CUDE y respuesta completa de la DIAN
[ ] Reconciliación periódica contra consulta de estado
[ ] Pruebas completas del ciclo en el ambiente de habilitación

Preguntas frecuentes

¿Cuál es el error más común al registrar eventos RADIAN?

Enviar un evento sin que existan sus prerrequisitos, por ejemplo una aceptación sin acuse de recibo ni recibo del bien, o un reclamo fuera de plazo. La DIAN lo rechaza y el ISV, si no distingue entre rechazo de negocio y fallo de transporte, suele reintentar sin éxito. Una máquina de estados local previene la mayoría de estos casos.

¿Cómo puedo saber si un evento RADIAN se registró aunque mi petición dio timeout?

Consultando el estado de la factura y sus eventos ante la DIAN o a través de su proveedor tecnológico antes de reenviar. Si el evento consta, se trata como éxito y se guarda su CUDE; si no consta, se reenvía. Este patrón evita duplicados y es la base de una integración tolerante a fallos de red.

¿Qué diferencia hay entre un rechazo y una notificación en la validación de un evento?

Un rechazo impide que el evento quede registrado y exige corregirlo y reenviarlo. Una notificación deja el evento registrado pero advierte una inconsistencia que conviene revisar. Un sistema debe almacenar ambas, pero solo disparar flujos de corrección obligatoria ante rechazos.

¿Es posible probar el ciclo completo de eventos RADIAN sin afectar facturas reales?

Sí, usando el ambiente de habilitación de la DIAN o el sandbox de un proveedor tecnológico, con facturas de prueba que recorran todos los casos: aceptación expresa, tácita, reclamo y errores de orden. Conviene incluir pruebas con plazos vencidos y con festivos, que son los casos que más fallan en producción.

Sobre el autor

Ing. Carlos Méndez es arquitecto de software con más de 10 años integrando sistemas fiscales en América Latina. Ha liderado implementaciones de facturación electrónica en Colombia, México y Centroamérica para ISVs de mediana y gran escala.