Factura de papel (contingencia del facturador)

Si tu empresa no puede facturar electrónicamente (se cayó tu sistema o tu conexión) y expide facturas de talonario o papel mientras dure el problema, foliios te da las herramientas para transcribirlas después a documentos electrónicos y transmitirlas; el proceso es de tu empresa.

Esta es la contingencia tipo 03. Si el problema es de la DIAN, no hagas nada de esto: ver contingencia.

Lo que haces tú y lo que hace foliios

Paso	Tu empresa	foliios
Antes	Pide a la DIAN la numeración de talonario o papel y la registra en el portal como resolución de papel	La guarda sin clave técnica y con numeración manual
Empieza la falla	Declara la contingencia (`POST .../contingencies`) con el motivo y la hora de inicio	Abre el período (uno abierto por empresa)
Aviso a la DIAN	El representante legal firma una carta y la envía a la DIAN	Genera el borrador de la carta. No la envía
Durante la falla	Expide facturas de papel	Nada: el papel no pasa por foliios
Transcripción	Envía cada papel (`POST .../transcriptions`) tal como se expidió	Valida, arma el documento tipo 03, lo firma y lo transmite por el flujo normal
Se supera la falla	Cierra la contingencia con la hora en que se superó y envía la carta de superación	Fija el plazo de transmisión y avisa por webhook

foliios no sabe cuántos papeles se expidieron: solo conoce los que se transcriben. Transcribir todos los papeles del período, y enviar las cartas, es responsabilidad de tu empresa.

1. Declarar

curl -s -X POST "https://api.foliios.com/v1/companies/$FOLIIOS_COMPANY_ID/contingencies" \
  -H "Authorization: Bearer $FOLIIOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"reason": "Falla del sistema de caja", "started_at": "2026-11-04T08:30:00-05:00"}'

reason es obligatorio (va en la carta); started_at es opcional, en RFC 3339 y no puede ser futuro. Responde 201 con la contingencia open. Una sola abierta por empresa (409 contingency_already_open); la siguiente no puede empezar antes de que termine la anterior (409 contingency_overlaps).

2. Transcribir cada papel

curl -s -X POST "https://api.foliios.com/v1/companies/$FOLIIOS_COMPANY_ID/contingencies/$CONTINGENCY_ID/transcriptions" \
  -H "Authorization: Bearer $FOLIIOS_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "paper": {"resolution_id": "ID_DE_LA_RESOLUCION_DE_PAPEL", "number": 41, "issue_date": "2026-11-04"},
    "customer": {"identification": {"type": "nit", "number": "900555555"}, "name": "Cliente Ejemplo S.A.S."},
    "lines": [{"code": "PARQ-01", "description": "Parqueadero por horas", "quantity": "3", "unit": "HUR",
               "unit_price": "4000.00", "taxes": [{"scheme": "iva", "percent": "19"}]}],
    "payment": {"form": "cash", "means": "10"}
  }'

El cuerpo es el del papel tal como se expidió: su número y su fecha en paper, y el contenido con los campos de una factura (sin resolution_id, number, type, invoice_type ni correction). Responde 202 con el documento (type: paper_transcription) en pending, que sigue el ciclo normal de transmisión.

No lleva Idempotency-Key: el papel es la clave. El mismo papel con el mismo cuerpo devuelve el mismo documento (Idempotent-Replayed: true); con otro cuerpo, 409 paper_already_transcribed.
La fecha del papel debe estar dentro del período (422 paper_outside_contingency) y de la vigencia de su resolución (422 paper_outside_resolution).
La resolución debe ser de papel: con una electrónica, 422 resolution_kind_mismatch (y una resolución de papel no emite facturas por el endpoint normal).
Solo se transcriben facturas de venta.
La transcripción se transmite de inmediato, aunque la contingencia siga abierta.
Un rechazo se corrige con resubmit (rechazos y reenvío).

from foliios_inicio import EMPRESA, llamar

def transcribir(contingencia_id, papel, contenido):
    estado, doc, cabeceras = llamar(
        "POST",
        f"/v1/companies/{EMPRESA}/contingencies/{contingencia_id}/transcriptions",
        {"paper": papel, **contenido},
    )
    assert estado == 202, doc
    return doc

3. Cerrar

curl -s -X POST "https://api.foliios.com/v1/companies/$FOLIIOS_COMPANY_ID/contingencies/$CONTINGENCY_ID/close" \
  -H "Authorization: Bearer $FOLIIOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"ended_at": "2026-11-04T18:00:00-05:00"}'

ended_at es opcional, no futuro ni anterior al inicio. Cerrarla dos veces responde 409 contingency_already_closed. La respuesta trae transmission_deadline, el plazo para transmitir las transcripciones.

4. Seguir el plazo

GET .../contingencies/{contingency_id} devuelve cada transcripción con el estado de su documento, pending_transcriptions (las no aceptadas), el plazo y overdue (plazo vencido con pendientes). Cuando faltan 12 horas o menos, o ya venció, foliios envía por webhook document.contingency_deadline_approaching por cada transcripción no aceptada.

La carta a la DIAN

GET .../contingencies/{contingency_id}/letter devuelve un borrador en texto plano con los datos del correo (para, asunto, adjunto, cuerpo) y la carta: con la contingencia abierta, declara el inconveniente; cerrada, informa la superación. El espacio de la firma y los datos de contacto quedan para tu empresa. foliios no firma ni envía nada a la DIAN: la firma del representante legal y el envío son tuyos.

Probarlo en el sandbox

En el sandbox puedes declarar y cerrar la contingencia del facturador y pedir la carta, sin efecto fiscal y sin que se envíe ninguna carta.