Estados de un documento

Emitir es asíncrono. Cuando el API responde 201, el documento existe pero todavía no tiene número, ni CUFE, ni ha llegado a la DIAN. El estado dice en qué punto va.

El recorrido normal

QUEUED ──build──► SIGNED ──send──► VALIDATED ──► PDF + AttachedDocument + correo
   │                 │                │
   │                 ├──► REJECTED    (la DIAN dijo que no)
   │                 └──► SENT ──► CONTINGENCY  (la DIAN no respondió)
   └──► FAILED       (no se pudo construir ni firmar)

{QUEUED, SIGNED, FAILED, CONTINGENCY, REJECTED} ──discard──► DISCARDED

Los nueve estados

Estado	Qué significa	¿retry?	¿discard?
DRAFT	Valor por defecto de la columna. Un documento emitido por el API nunca pasa por aquí: nace en QUEUED.	No	Sí
QUEUED	Aceptado y encolado. Sin número, sin CUFE, sin XML.	Sí	Sí
SIGNED	Numerado, UBL armado, CUFE calculado, firmado y validado contra el XSD. Encolado para transmitir.	Sí (solo el envío)	Sí
SENT	En vuelo hacia la DIAN.	No	No
VALIDATED	La DIAN lo aceptó. Estado final bueno.	No	No
REJECTED	La DIAN contestó que no. Los motivos quedan en dian_errors.	No	Sí
CONTINGENCY	La DIAN no respondió tras cinco intentos. El documento sigue vivo.	Sí	Sí
FAILED	Falló antes de transmitir: sin certificado, sin clave técnica, XML que no cumple el XSD.	Sí	Sí
DISCARDED	Se dio por perdido a propósito.	No	No

Los tres que hay que entender bien

SENT no se reintenta

Significa en vuelo: puede que la DIAN ya lo haya recibido y que solo se haya perdido la respuesta. Reenviarlo sería arriesgarse a un duplicado.

Ese caso se resuelve consultando el estado, no reintentando.

REJECTED es una respuesta, no un fallo

La DIAN contestó y dijo que no. Reintentar lo mismo da lo mismo: hay que leer dian_errors, corregir y emitir un documento nuevo.

Cualquier «no» de la DIAN es un rechazo, no una indisponibilidad.

CONTINGENCY no es una derrota

La DIAN no estuvo disponible tras cinco intentos con espera creciente: caída, timeout o error del servicio. El documento sigue vivo y se puede reintentar; hay una ventana de 48 horas para transmitirlo.

DISCARDED no devuelve el consecutivo

Descartar es decidir dejar de intentarlo. El registro se queda a propósito: el consecutivo ya se gastó, y esa fila es lo único que explica el hueco en la numeración si la DIAN pregunta.

No consultes en bucle

Cada transición dispara un webhook:

Evento	Cuándo
document.validated	La DIAN aceptó
document.rejected	La DIAN rechazó
document.contingency	La DIAN no respondió
document.failed	No se pudo construir
document.email_failed	El correo al adquirente no salió

Consultar sirve mientras integras. En producción, suscríbete a los eventos.

Qué hacer con cada uno

Estado	Acción
QUEUED, SIGNED, SENT	Esperar. Son transitorios.
VALIDATED	Nada. Ya está. Descarga el XML y el AttachedDocument.
REJECTED	Leer dian_errors, corregir y emitir uno nuevo.
CONTINGENCY	Reintentar. No gasta otro consecutivo.
FAILED	Leer el motivo. Casi siempre es certificado, clave técnica o software. Arreglar y reintentar.
DISCARDED	Nada. Fue una decisión.