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.
Un CAF vence a los seis meses
La Resolución Exenta SII N° 58, de 05 de julio de 2017
le puso plazo al CAF: los otorgados desde el 01 de julio de 2018 valen seis meses corridos contados
desde su fecha de autorización (el campo <FA> que trae el propio archivo). Pasado el plazo,
«los folios no utilizados de los CAF no podrán ser emitidos, careciendo de validez para efectos
tributarios», y el SII rechaza al momento de su recepción todo documento que lleve un folio de un
CAF vencido.
expires_at en cada rango de GET /v1/folios es esa fecha: el último día hábil de uso. Un rango
se rechaza recién desde el día siguiente.
Trampa
La resolución alcanza a los documentos con derecho a crédito fiscal
Su propio texto se limita a «los documentos tributarios electrónicos que otorgan derecho al crédito
fiscal» — factura (33), liquidación-factura (43), factura de compra (46), nota de débito (56) y nota
de crédito (61). Para esos, Facturia rechaza la emisión antes de gastar el folio, con el código
caf_expired. Para el resto (34, 39, 41, 52) solo avisa y emite igual:
no vamos a bloquear con nuestra lectura de un alcance legal un documento que el SII probablemente
acepte.
Trampa
Los folios vencidos sin usar hay que anularlos, y no es opcional
La misma resolución (§2°) obliga a anularlos. Y como cinco CAF sin usar bloquean el timbraje, un rango vencido que quede sin anular te puede impedir pedir el que lo reemplaza. La opción está en Servicios online → Factura electrónica → Sistema de facturación de mercado → Timbraje electrónico → Anular folios. Facturia no la ejecuta por ti: anular folios es un acto del contribuyente ante el SII.
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.
Un rango vencido cuenta como agotado para esta cuenta: aunque le queden números, ya no se puede emitir con él, así que el umbral se cruza solo y la reposición se dispara antes de que te enteres emitiendo.