# Folios and CAF (/en/docs/emision/folios)

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 [#check-availability]

```bash
curl https://api.facturia.cl/v1/folios \
  -H "Authorization: Bearer $FACTURIA_KEY" -H "Facturia-Empresa: $EMPRESA"
```

```json
{
  "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 [#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.

```bash
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}'
```

```json
{
  "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 [#bring-your-own-caf]

```bash
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 [#the-siis-two-realities]

> **Trap — A new emisor's first CAF is a one-off and cannot be split**
>
> We size it deliberately during onboarding. If you come up short, the next request means starting the
> paperwork over.

> **Trap — Five downloaded CAFs left unused block timbraje**
>
> That is why `auto_request_folios` works off a threshold instead of asking greedily: piling up CAFs you
> never consume is exactly what leaves you unable to ask for more.

## A CAF expires after six months [#a-caf-expires-after-six-months]

[Resolución Exenta SII N° 58, of 05 July 2017](https://www.sii.cl/documentos/resoluciones/2017/reso58.pdf)
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.

> **Trap — The resolution reaches the documents that grant derecho a crédito fiscal**
>
> Its own text limits itself to «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) and
> nota de crédito (61). For those, Facturia **refuses the emission before a folio is spent**, with the
> code [`caf_expired`](/en/docs/errores/caf_expired). For the rest (34, 39, 41, 52) it warns and issues
> anyway: we will not block a document the SII would probably accept on our own reading of a scope
> clause.

> **Trap — Unused expired folios have to be annulled, and it is not optional**
>
> The same resolution (§2°) requires it. And since five unused CAFs block timbraje, an expired range
> left un-annulled can stop you requesting its replacement. The option lives at **Servicios online →
> Factura electrónica → Sistema de facturación de mercado → Timbraje electrónico → Anular folios**.
> Facturia does not do it for you: annulling folios is the taxpayer's own act before the SII.

## The automation [#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.