Folios and CAF

Folio availability by document type, requesting stamping, and uploading your own CAF.

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.

Method	Path	What it does
`GET`	`/folios`	Folio availability per doc type
`POST`	`/folios/requests`	Request a new CAF from the SII (async)
`GET`	`/cafs`	List CAFs held for this empresa
`POST`	`/cafs`	Upload a CAF you already hold
`DELETE`	`/cafs/{caf_id}`	Deactivate a CAF (history is preserved)

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

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`

Request a new CAF from the SII (async)

The SII's timbraje is a scripted portal flow, not a webservice. Returns a job.

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`

List CAFs held for this empresa

Every CAF (folio authorization) uploaded for the empresa, with its range, tipo_dte and how many folios remain.

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`

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.

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":"<AUTORIZACION>…</AUTORIZACION>"}'

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

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.

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

GET /folios

POST /folios/requests

GET /cafs

POST /cafs

DELETE /cafs/{caf_id}

On this page

`GET /folios`

`POST /folios/requests`

`GET /cafs`

`POST /cafs`

`DELETE /cafs/{caf_id}`