Contingencia

Hay dos contingencias distintas. No las confundas.

	Falla de la DIAN (tipo 04)	Falla del facturador (tipo 03)
Quién falla	Los servicios de validación de la DIAN	Tu empresa o tu sistema
Qué se expide	La factura electrónica, firmada y entregada sin validación previa	Una factura de talonario o papel
Quién la declara	Nadie: foliios la detecta	Tu empresa, en foliios
Qué haces tú	Normalmente, nada	Todo el proceso: factura de papel

Esta guía es la primera. Las normas y los plazos están en el marco normativo; aún tienen revisión pendiente de Armando.

Qué hace foliios cuando la DIAN no responde

1. foliios transmite el documento. Si la DIAN no está disponible, lo marca dian_unavailable y reintenta con el calendario del anexo técnico: tres reintentos con pausas de segundos ante una falla del servicio, o reintentos cada 2 minutos ante un tiempo agotado.
2. Si se agotan los reintentos, el documento pasa a contingency: foliios escribe y firma una vez el documento como tipo 04 (mismo prefijo y número), lo archiva, publica el evento document.contingency y lo entrega al comprador sin validación previa.
3. foliios sigue transmitiendo ese mismo documento (los mismos bytes firmados, con el mismo CUFE) cada 15 minutos hasta que la DIAN lo acepte. Entonces el documento pasa a accepted, sale document.accepted y se entrega otra vez el contenedor ya validado.
4. Si el documento se acerca a su plazo de transmisión, el barrido publica una sola vez document.contingency_deadline_approaching, con transmission_deadline.

Tu integración no reenvía ni emite de nuevo: espera. Un documento en contingency no es un error. Guarda su id y deja que llegue a accepted.

import time
from foliios_inicio import EMPRESA, llamar

# Ante contingencia: no reenvíes, consulta hasta que quede aceptado.
while documento["status"] in ("pending", "sending", "dian_unavailable", "contingency"):
    time.sleep(10)
    _, documento, _ = llamar("GET", f"/v1/companies/{EMPRESA}/documents/{documento['id']}")
print(documento["status"])

Un documento accepted que pasó por contingencia conserva la marca de que pasó por ella; es lo que comprueba contingency en la verificación de integración.

Probarla en el sandbox

El escenario dian_unavailable recorre toda la contingencia, sin atajos:

curl -s -X POST "https://api.foliios.com/v1/companies/$FOLIIOS_COMPANY_ID/documents" \
  -H "Authorization: Bearer $FOLIIOS_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: contingencia-1" -H "Foliios-Sandbox-Scenario: dian_unavailable" \
  -d @factura.json

En el sandbox, la transmisión posterior llega en segundos, no en minutos como en habilitación y producción (el valor exacto está en escenarios), y enseguida verás cuatro eventos: document.contingency, document.delivered (etapa de contingencia), document.accepted y document.delivered (etapa validada). El detalle de cada evento está en eventos de webhook y el escenario, en escenarios.

Qué incluye y qué no

• El documento tipo 04 se escribe y se firma una sola vez: lo que se entrega al comprador es exactamente lo que después se transmite.
• La fecha de emisión queda fija desde que empieza la contingencia, aunque cambie el día.
• Las notas crédito y débito no tienen contingencia: se emiten con normalidad cuando el problema se supera.
• Si el documento termina failed (un error de configuración), nunca va a contingencia: la contingencia es solo para la indisponibilidad de la DIAN. Ver rechazos y reenvío.
• El comprador recibe el tipo 04 por correo mientras tanto. Ver entrega por correo.