Estados del documento

La API responde antes de que la DIAN valide: un documento nace pending y avanza por estos estados. Tu sistema sigue su avance consultándolo (GET .../documents/{document_id}) o con webhooks.

Estados

Estado	Qué significa	Qué hacer
pending	Recibido, numerado y en cola para transmitirse.	Esperar.
sending	Se está transmitiendo a la DIAN, o esperando la verificación de una respuesta dudosa.	Esperar.
accepted	La DIAN lo validó. Es definitivo.	Guardar number y cufe. Se entrega al comprador.
rejected	La DIAN lo rechazó. dian.rules dice qué reglas y cómo corregirlas.	Corregir y reenviar. El número queda libre en facturas.
dian_unavailable	La DIAN no respondió; foliios reintenta solo.	Esperar.
contingency	Se agotaron los reintentos: el documento se emitió como contingencia (tipo 04) y se sigue transmitiendo.	Nada: queda aceptado cuando la DIAN vuelve. Ver contingencia.
failed	Un problema de configuración o del formato impide transmitirlo. No se reintenta solo. dian.failure_code dice por qué.	Corregir la causa y reintentar si el código lo permite.

Transiciones

pending -> sending
sending -> accepted | rejected | dian_unavailable | failed
dian_unavailable -> sending (reintento) | contingency (reintentos agotados)
contingency -> sending (transmisión del tipo 04)
rejected -> pending (con resubmit)
failed -> pending (con retry, solo fallos reintentables)
failed -> sending (retry de duplicate_unverified: solo verifica con la DIAN)

accepted es terminal. Cualquier otra transición no existe.

La entrega al comprador es otro estado

El estado delivery del documento es independiente del estado ante la DIAN: un documento puede estar accepted con la entrega failed, y la emisión nunca falla por la entrega.

delivery.status	Significa
pending	Espera su envío o el siguiente reintento (next_attempt_at).
sent	El servicio de correo aceptó el mensaje para el comprador.
failed	No se enviará sin intervención. failure_code dice por qué.
not_applicable	El documento no tiene correo del comprador (por ejemplo, consumidor final): se entrega por otro medio.

Es null mientras la entrega no empieza. Ver entrega por correo.

Eventos de webhook por estado

Cada cambio importante genera un evento: document.accepted, document.rejected, document.failed, document.contingency, document.contingency_deadline_approaching, document.delivered, document.delivery_failed y document.delivery_not_applicable. Su forma está en la referencia de eventos.