Corregir y reanudar
Qué hacer con una factura que la DIAN rechazó y con una que se quedó bloqueada antes de llegar.
Dos situaciones distintas, con soluciones distintas:
- La DIAN la rechazó. El documento no sirve. Lo corriges y vuelve a intentarse, conservando su número.
- Nunca llegó a la DIAN. Algo se atascó de nuestro lado. Lo reanudas: sigue siendo el mismo documento, con la misma firma y el mismo número.
Ninguna de las dos sirve para cambiar una factura que la DIAN validó. Esa solo se ajusta con una nota crédito o débito.
Corregir un rechazo
Solo se corrige un rechazo confirmado: dian.status: rejected, con sus motivos en dian.errors. Si el estado es unknown, no corrijas nada todavía; sigue consultando.
Consulta el documento, lee dian.errors y guarda el ETag y el revision que trae.
Arregla los datos en tu sistema, no en el cuerpo ya enviado. Si el comprador tenía la cédula mal, corrígela donde la guardas y vuelve a generar la factura desde ahí.
Llama POST /v1/documents/{id}/revisions con If-Match, Idempotency-Key y este cuerpo:
{
"reason": "Corregir la identificación del comprador rechazada por la DIAN",
"expected_revision": 1,
"replacement": { "…": "la factura completa y corregida, igual que en POST /v1/invoices" }
}replacement es una solicitud completa, con todos sus campos, no un parche con lo que cambió.
Qué se conserva y qué no:
| Se conserva | Cambia |
|---|---|
El document_id, el tipo y tu external_reference | La revisión: pasa a 2, 3… |
| El número y el prefijo ya asignados | Se crea otra operación, con su propio operation_id |
| Los archivos de la revisión anterior, con sus mismos bytes | Se generan archivos nuevos para la revisión nueva |
Al corregir se vuelven a comprobar todas las reglas, así que una corrección también puede rechazarse. Si la factura ya tenía notas, la corrección vuelve a evaluar el saldo ajustable: corregir no te deja excederlo.
expected_revision tiene que ser la revisión que leíste. Si alguien corrigió el documento entre tu consulta y tu llamada, la petición falla en lugar de pisar el trabajo del otro. Repetir la misma corrección con la misma Idempotency-Key te devuelve la que ya hiciste.
Cada revisión queda consultable en GET /v1/documents/{id}/revisions/{revision}, con la entrada y el estado que tuvo. Sus archivos se listan con el parámetro revision (Archivos).
Corregir no es reemitir
Una corrección conserva el número del documento. No la uses para «emitir otra factura»: eso es una factura nueva, con su propia referencia externa y su propia clave de idempotencia.
Reanudar un documento bloqueado
Si processing_status es action_required, el documento se quedó a mitad de camino y el campo blocked_reason dice por qué:
blocked_reason | Qué pasó | Qué hacer |
|---|---|---|
TRANSPORT_ATTEMPTS_EXHAUSTED | Lo intentamos varias veces y la DIAN no respondió. | Reanuda cuando la DIAN vuelva a responder. |
TRANSPORT_SIGNING_BLOCKED | El emisor de pruebas del sandbox no está disponible. | No es tu factura. Espera un rato y reanuda, o escríbenos. |
Se reanuda con POST /v1/documents/{id}/resumption, con If-Match, Idempotency-Key y un motivo:
{ "reason": "La dependencia se recuperó; continuar la misma operación" }Reanudar no emite nada nuevo. Conserva la revisión, el cuerpo, el número y la firma. Si ya se había firmado, se reconstruye el paquete con los mismos bytes y se comprueba su hash; no se vuelve a firmar.
Si hay indicios de que el envío sí llegó a la DIAN, reanudar solo vuelve a preguntar por ese documento, con un presupuesto acotado de consultas. Nunca lo sube dos veces.
Un documento que no está en un estado reanudable responde RESUMPTION_NOT_ALLOWED. Y un fallo anterior a la firma —una regla fiscal que no se cumplió— no se arregla por aquí: eso se corrige.
Cuál de las dos necesitas
| Lo que ves en el documento | Lo que haces |
|---|---|
dian.status: rejected | Corregir. |
processing_status: action_required con blocked_reason | Reanudar. |
dian.status: unknown | Ninguna de las dos. Consultar más tarde. |
dian.status: validated | Ninguna de las dos. Nota crédito o débito. |
dian.status: not_sent y recién enviada | Todavía puedes cancelarla. |