# Folios y CAF (/docs/emision/folios)

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 [#ver-disponibilidad]

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

## Pedir más [#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.

```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"
}
```

Consulta `GET /v1/jobs/{job_id}` o escucha `folios.replenished`.

## Traer tu propio CAF [#traer-tu-propio-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>"}'
```

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 [#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 [#un-caf-vence-a-los-seis-meses]

La [Resolución Exenta SII N° 58, de 05 de julio de 2017](https://www.sii.cl/documentos/resoluciones/2017/reso58.pdf)
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`](/docs/errores/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 [#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.