Folios and CAF

A DTE (documento tributario electrónico, Chile's electronic tax document) cannot exist without a folio — the pre-authorised sequential number it carries — drawn from a CAF (Código de Autorización de Folios) that the SII, Chile's tax authority, grants per document type. Facturia manages that for you; the endpoints exist so you can watch it and step in.

Check availability

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
}

Ask for more

The SII's timbraje — the stamping run that hands out folios — is a scripted portal flow, not a webservice, so the request is asynchronous and returns a 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"
}

Poll GET /v1/jobs/{job_id} or listen for folios.replenished.

Bring your own 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>"}'

We check that the CAF's RE matches the empresa's RUT (Chile's taxpayer id), record the range, and never lower an existing counter. GET /v1/cafs lists them; DELETE /v1/cafs/{caf_id} deactivates one without erasing history.

The SII's two realities

A CAF expires after six months

Resolución Exenta SII N° 58, of 05 July 2017 put a clock on the CAF: those granted from 01 July 2018 onward are valid for six calendar months counted from their authorization date (the <FA> field the file itself carries). After that, «los folios no utilizados de los CAF no podrán ser emitidos, careciendo de validez para efectos tributarios», and the SII rejects on reception any document carrying a folio from an expired CAF.

expires_at on each range of GET /v1/folios is that date: the last day the range may be used. A range is refused from the following day, never on it.

The automation

auto_request_folios ships on by default — the only automation that does. When the folios available for a type fall below auto_request_folios_threshold (50 by default), we request the next CAF from the SII automatically.

It is on because running out of folios stops issuing altogether, and there is no downside to having folios in hand. You turn it off at PATCH /v1/empresas/{empresa_id}/automation_settings like any other.

Events: folios.low (below the threshold), folios.exhausted (issuing is already failing), folios.replenished.

An expired range counts as exhausted for this purpose: whatever numbers are left in it can no longer be issued, so the threshold is crossed on its own and replenishment fires before you find out by trying to invoice.