Folios y CAF
Cómo se administran los folios, cuándo pedir más y las dos realidades del timbraje del SII que la API expone con honestidad.
Un DTE no puede existir sin un folio sacado de un CAF (Código de Autorización de Folios) que el SII concede por tipo de documento. Facturia lo administra por ti; los endpoints existen para que puedas mirarlo e intervenir.
Ver disponibilidad
curl https://api.facturia.cl/v1/folios \
-H "Authorization: Bearer $FACTURIA_KEY" -H "Facturia-Empresa: $EMPRESA"{
"object": "list",
"url": "/v1/folios",
"data": [
{ "object": "folio_range", "tipo_dte": 33, "next_folio": 412, "available": 589, "ranges": [{ "caf_id": "caf_01K2P...", "from": 1, "to": 1000, "expires_at": null }], "status": "ok" },
{ "object": "folio_range", "tipo_dte": 39, "next_folio": 9884, "available": 116, "ranges": [{ "caf_id": "caf_01K2N...", "from": 9000, "to": 10000 }], "status": "low" },
{ "object": "folio_range", "tipo_dte": 61, "next_folio": 34, "available": 0, "ranges": [], "status": "exhausted" }
],
"has_more": false
}Pedir más
El timbraje del SII es un flujo de portal guionizado, no un webservice, así que la solicitud es asíncrona y devuelve un job.
curl -sS https://api.facturia.cl/v1/folios/requests \
-H "Authorization: Bearer $FACTURIA_KEY" -H "Facturia-Empresa: $EMPRESA" \
-H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
-d '{"tipo_dte": 61, "quantity": 100}'{
"id": "job_01K2R8B4V6WQ2X",
"object": "job",
"type": "folio_request",
"status": "queued",
"tipo_dte": 61,
"quantity": 100,
"created_at": "2026-08-14T13:10:02Z"
}Consulta GET /v1/jobs/{job_id} o escucha folios.replenished.
Traer tu propio CAF
curl -sS https://api.facturia.cl/v1/cafs \
-H "Authorization: Bearer $FACTURIA_KEY" -H "Facturia-Empresa: $EMPRESA" \
-H "Content-Type: application/json" \
-d '{"caf_xml":"<AUTORIZACION>…</AUTORIZACION>"}'Validamos que el RE del CAF coincida con el RUT de la empresa, registramos el rango y nunca
bajamos un contador existente. GET /v1/cafs los lista; DELETE /v1/cafs/{caf_id} desactiva sin
borrar la historia.
Las dos realidades del SII
Trampa
El primer CAF de un emisor nuevo es de una sola vez y no se puede partir
Lo dimensionamos deliberadamente durante la puesta en marcha. Si te quedas corto, la siguiente solicitud es un trámite nuevo.
Trampa
Cinco CAF descargados sin usar bloquean el timbraje
Por eso auto_request_folios usa un umbral en vez de pedir con avidez: acumular CAF sin consumir es
exactamente lo que te deja sin poder pedir más.
La automatización
auto_request_folios viene encendida por defecto — es la única automatización que sí lo está.
Cuando los folios disponibles de un tipo caen bajo auto_request_folios_threshold (50 por defecto),
pedimos el siguiente CAF al SII automáticamente.
Está encendida porque quedarse sin folios detiene la emisión y no hay desventaja en tener folios en
mano. Se apaga en PATCH /v1/empresas/{empresa_id}/automation_settings como cualquier otra.
Eventos: folios.low (bajo el umbral), folios.exhausted (la emisión ya está fallando),
folios.replenished.