# Folios and CAF (/en/docs/referencia/folios) Base: `https://api.facturia.cl/v1`. Every endpoint in this chapter authenticates with `Authorization: Bearer` unless stated otherwise, and the error envelope is the one in [Errors](/en/docs/errores). | Method | Path | What it does | | -------- | ------------------------------------------- | --------------------------------------- | | `GET` | [`/folios`](#get-folios) | Folio availability per doc type | | `POST` | [`/folios/requests`](#post-folios-requests) | Request a new CAF from the SII (async) | | `GET` | [`/cafs`](#get-cafs) | List CAFs held for this empresa | | `POST` | [`/cafs`](#post-cafs) | Upload a CAF you already hold | | `DELETE` | [`/cafs/{caf_id}`](#delete-cafs-caf-id) | Deactivate a CAF (history is preserved) | ## `GET /folios` [#get-folios] **Folio availability per doc type** Folio ranges (CAF-backed) available to the empresa, with how many of each `tipo_dte` remain before a new request is needed. ```bash curl -sS https://api.facturia.cl/v1/folios \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" ``` **Parameters** | Parameter | In | Required | Type | Notes | | ------------------ | ------ | -------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Facturia-Empresa` | header | — | string | Target empresa: canonical RUT (`77928532-4`) or empresa id (`emp_…`). Required on every empresa-scoped call unless the key is an empresa token. This header is the ONLY mechanism: there is no `?empresa=` query parameter and no `empresa` body field. Omitted where required → `400 empresa_required`; outside the allowlist → `403 empresa_not_allowed`. | | `tipo_dte` | query | — | `33` · `34` · `39` · `41` · `46` · `52` · `56` · `61` | | **Responses** | Code | Meaning | Body | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | | `200` | Folio ranges. | lista de FolioRange | | `400` | Malformed or missing input. | ErrorResponse | | `401` | Missing, malformed or revoked key. | ErrorResponse | | `403` | Valid key, not permitted — scope, empresa allowlist, or mode. | ErrorResponse | | `429` | Too many requests. | ErrorResponse | | `default` | An error not otherwise enumerated for this operation, in the same §5.5 envelope as every other refusal. Branch on `error.code`, never on the HTTP status alone or on `error.message` — a code this operation has not been seen to throw yet is still safer to route on than a string meant for a human. | ErrorResponse | ## `POST /folios/requests` [#post-folios-requests] **Request a new CAF from the SII (async)** The SII's timbraje is a scripted portal flow, not a webservice. Returns a job. ```bash curl -sS -X POST 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":33}' ``` **Parameters** | Parameter | In | Required | Type | Notes | | ------------------ | ------ | -------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Facturia-Empresa` | header | — | string | Target empresa: canonical RUT (`77928532-4`) or empresa id (`emp_…`). Required on every empresa-scoped call unless the key is an empresa token. This header is the ONLY mechanism: there is no `?empresa=` query parameter and no `empresa` body field. Omitted where required → `400 empresa_required`; outside the allowlist → `403 empresa_not_allowed`. | | `Idempotency-Key` | header | — | string | Client-generated key, unique per logical operation, retained 24h and scoped to (account, empresa, endpoint). Replays return the original response with `Facturia-Idempotent-Replay: true`. Same key + different body → `409`. | **Body** | Field | Type | Required | Notes | | ------------- | ----------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tipo_dte` | `33` · `34` · `39` · `41` · `46` · `52` · `56` · `61` | yes | 33 factura afecta · 34 factura exenta · 39 boleta afecta · 41 boleta exenta · 46 factura de compra · 52 guía de despacho · 56 nota de débito · 61 nota de crédito. Boletas (39/41) travel a different SII transport; that is invisible through this API. | | `quantity` | integer | — | Folios requested. Omit to let Facturia size it from consumption history. | | **Responses** | | | | | Code | Meaning | Body | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `202` | Job accepted. | Job | | `401` | Missing, malformed or revoked key. | ErrorResponse | | `402` | `subscription_required` - this live act needs an active subscription for the EMPRESA the request names, and that empresa has none (enforced). The subscription is per empresa: another empresa on the same account is unaffected, and `error.details` carries `empresa`, `empresa_rut`, `empresa_name`, `account_plan`, `subscription_status`, `grace_until`, `blocked_by`, a `next` handoff and a `checkout_url` pointing at that empresa. Or `plan_limit_reached` - a plan quota is exhausted (declared, not yet enforced). Test mode is never gated on either. **ELIGIBILITY IS EVALUATED FIRST** (2026-09-04, #475). This refusal now arrives ONLY when the empresa is otherwise able to emit: while its checklist is unfinished, its `puesta en vivo` pending or the empresa suspended, the act is refused by `422 empresa_not_emitting` with the checklist handoff instead. So this `402` and `Empresa.capabilities.blocked_by` can no longer name two different next actions for one state — which they did, the object saying «sign the mandato» while the door said «pay». | ErrorResponse | | `403` | Valid key, not permitted — scope, empresa allowlist, or mode. | ErrorResponse | | `422` | Well-formed but violates a domain rule — folios exhausted, acuse window closed. | ErrorResponse | | `429` | Too many requests. | ErrorResponse | | `default` | An error not otherwise enumerated for this operation, in the same §5.5 envelope as every other refusal. Branch on `error.code`, never on the HTTP status alone or on `error.message` — a code this operation has not been seen to throw yet is still safer to route on than a string meant for a human. | ErrorResponse | ## `GET /cafs` [#get-cafs] **List CAFs held for this empresa** Every CAF (folio authorization) uploaded for the empresa, with its range, `tipo_dte` and how many folios remain. ```bash curl -sS https://api.facturia.cl/v1/cafs \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" ``` **Parameters** | Parameter | In | Required | Type | Notes | | ------------------ | ------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Facturia-Empresa` | header | — | string | Target empresa: canonical RUT (`77928532-4`) or empresa id (`emp_…`). Required on every empresa-scoped call unless the key is an empresa token. This header is the ONLY mechanism: there is no `?empresa=` query parameter and no `empresa` body field. Omitted where required → `400 empresa_required`; outside the allowlist → `403 empresa_not_allowed`. | | `limit` | query | — | integer | | | `cursor` | query | — | string | Opaque cursor from a previous response's `next_cursor`. | **Responses** | Code | Meaning | Body | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `200` | A list of CAFs. | lista de Caf | | `401` | Missing, malformed or revoked key. | ErrorResponse | | `403` | Valid key, not permitted — scope, empresa allowlist, or mode. | ErrorResponse | | `429` | Too many requests. | ErrorResponse | | `default` | An error not otherwise enumerated for this operation, in the same §5.5 envelope as every other refusal. Branch on `error.code`, never on the HTTP status alone or on `error.message` — a code this operation has not been seen to throw yet is still safer to route on than a string meant for a human. | ErrorResponse | ## `POST /cafs` [#post-cafs] **Upload a CAF you already hold** Upload a CAF file obtained from the SII's own portal. Rejected if its range overlaps one already on file for the same `tipo_dte`. ```bash curl -sS -X POST https://api.facturia.cl/v1/cafs \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"caf_xml":"…"}' ``` **Parameters** | Parameter | In | Required | Type | Notes | | ------------------ | ------ | -------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Facturia-Empresa` | header | — | string | Target empresa: canonical RUT (`77928532-4`) or empresa id (`emp_…`). Required on every empresa-scoped call unless the key is an empresa token. This header is the ONLY mechanism: there is no `?empresa=` query parameter and no `empresa` body field. Omitted where required → `400 empresa_required`; outside the allowlist → `403 empresa_not_allowed`. | | `Idempotency-Key` | header | — | string | Client-generated key, unique per logical operation, retained 24h and scoped to (account, empresa, endpoint). Replays return the original response with `Facturia-Idempotent-Replay: true`. Same key + different body → `409`. | **Body** | Field | Type | Required | Notes | | ------------- | ------ | -------- | -------------------------------------------------------------- | | `caf_xml` | string | yes | The raw `<AUTORIZACION>` XML as downloaded from the SII. | | **Responses** | | | | | Code | Meaning | Body | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `201` | CAF registered. | Caf | | `400` | Malformed or missing input. | ErrorResponse | | `401` | Missing, malformed or revoked key. | ErrorResponse | | `403` | Valid key, not permitted — scope, empresa allowlist, or mode. | ErrorResponse | | `429` | Too many requests. | ErrorResponse | | `default` | An error not otherwise enumerated for this operation, in the same §5.5 envelope as every other refusal. Branch on `error.code`, never on the HTTP status alone or on `error.message` — a code this operation has not been seen to throw yet is still safer to route on than a string meant for a human. | ErrorResponse | ## `DELETE /cafs/{caf_id}` [#delete-cafs-caf-id] **Deactivate a CAF (history is preserved)** Deactivate a CAF (`active: false`). Folios already allocated from it are unaffected; the range simply stops offering new ones. ```bash curl -sS -X DELETE https://api.facturia.cl/v1/cafs/caf_01K2P4V8QW2M \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" ``` **Parameters** | Parameter | In | Required | Type | Notes | | ------------------ | ------ | -------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `caf_id` | path | yes | string | | | `Facturia-Empresa` | header | — | string | Target empresa: canonical RUT (`77928532-4`) or empresa id (`emp_…`). Required on every empresa-scoped call unless the key is an empresa token. This header is the ONLY mechanism: there is no `?empresa=` query parameter and no `empresa` body field. Omitted where required → `400 empresa_required`; outside the allowlist → `403 empresa_not_allowed`. | **Responses** | Code | Meaning | Body | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `204` | Deactivated. | — | | `401` | Missing, malformed or revoked key. | ErrorResponse | | `403` | Valid key, not permitted — scope, empresa allowlist, or mode. | ErrorResponse | | `404` | No such object under this key. | ErrorResponse | | `429` | Too many requests. | ErrorResponse | | `default` | An error not otherwise enumerated for this operation, in the same §5.5 envelope as every other refusal. Branch on `error.code`, never on the HTTP status alone or on `error.message` — a code this operation has not been seen to throw yet is still safer to route on than a string meant for a human. | ErrorResponse |