Estados y respuestas

Qué responde la API cuando la DIAN valida, rechaza o no contesta (201, 202, 402, 422, 503) y cómo continuar sin duplicar documentos.

Ver como Markdown

Trevol valida, numera, firma, envía a la DIAN y responde apenas la DIAN valida (la meta es 3 segundos o menos; en la prueba del 23 de octubre de 2026, en habilitación, la mediana fue 1,9 s).

Qué responde

HTTP	Qué pasó
201	La DIAN validó el documento (`status: accepted`).
422 `dian_rejected`	La DIAN lo rechazó; `document` trae el documento y sus reglas traducidas.
422 `validation_error`	Trevol lo rechazó antes de numerar: no se gastó nada.
402 `insufficient_balance`	Producción sin saldo: queda `pending` con su número.
202 `processing` (versión 2026-10-22)	La DIAN no contestó. Trevol termina el documento (le pregunta por el CUFE y, si hace falta, lo reenvía) y te avisa por webhook con `….accepted`, `….rejected` o `….error`. No crees otro documento para esa venta. Trae `Location` y `Retry-After: 30`.
202 `sending` (versión 2026-10-22)	Otra petición, o el fondo, lo está enviando ahora. Igual que el anterior.
202 `validating` (las dos versiones)	La propia DIAN responde después: el set de pruebas de habilitación de la nómina o del documento equivalente todavía valida el documento, o un evento RADIAN quedó en «en proceso de validación» (98). No es un error y no se reenvía: Trevol solo consulta y te avisa por webhook.
503 `dian_unavailable` (versión 2026-10-21)	La DIAN no contestó: reintenta con la misma `Idempotency-Key`. Trevol además lo verifica en segundo plano (solo consulta; no reenvía).

Todos los errores están en el catálogo de errores.

Un 202 no es un error

HTTP202

HTTP/1.1 202 Accepted
Location: /v1/invoices/inv_08cd6774e31e401c9fa0fbf92b3fbdc0
Retry-After: 30
Trevol-Version: 2026-10-22

{
  "id": "inv_08cd6774e31e401c9fa0fbf92b3fbdc0",
  "object": "invoice",
  "status": "processing",
  "number": "SETP994307052",
  "cufe": null,
  "dian": { "status_code": null, "rules": [] }
}

Un 202 ya tiene su id y su número. Para saber cómo terminó, espera el webhook o consulta el documento:

GET /v1/invoices/{id}

cURL

curl "https://api.trevol.si/v1/invoices/inv_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b" \
  -H "Authorization: Bearer $TREVOL_API_KEY"

Probar en el Playground

Los SDK no reintentan un 202 ni lo convierten en excepción: lo devuelven como cualquier respuesta, con su status.

Los estados de un documento

`status`	Significado
`pending`	Numerado, sin enviar (por ejemplo, sin saldo).
`sending`	Se está enviando a la DIAN.
`processing`	Solo en 2026-10-22: la DIAN no confirmó y Trevol lo resuelve.
`validating`	Nómina, documento equivalente y eventos: la DIAN responde después, en las dos versiones.
`accepted`	Validado por la DIAN.
`rejected`	La DIAN lo rechazó; se corrige con `PUT` y el mismo número.
`error`	No se pudo enviar.
`contingency`	Documento equivalente en contingencia.

Rechazos y correcciones

Rechazado por la DIAN: corrige con PUT (cuerpo completo, nueva Idempotency-Key). Sale con el mismo número. Un rechazo no bloquea los demás envíos. Cada regla trae su explicación en español: Reglas de la DIAN.
Pendiente o en error: POST …/send lo vuelve a enviar (por ejemplo, después de recargar saldo).
Validado: ya no se cambia; se corrige con una nota crédito o débito.