# Folios y CAF (/docs/referencia/folios) Base: `https://api.facturia.cl/v1`. Todos los endpoints de este capítulo se autentican con `Authorization: Bearer` salvo que se diga lo contrario, y el sobre de error es el de [Errores](/docs/errores). | Método | Ruta | Qué hace | | -------- | ------------------------------------------- | ---------------------------------------------- | | `GET` | [`/folios`](#get-folios) | Disponibilidad de folios por tipo de documento | | `POST` | [`/folios/requests`](#post-folios-requests) | Solicita un CAF nuevo al SII (asíncrono) | | `GET` | [`/cafs`](#get-cafs) | Lista los CAF que esta empresa tiene cargados | | `POST` | [`/cafs`](#post-cafs) | Carga un CAF que ya tienes | | `DELETE` | [`/cafs/{caf_id}`](#delete-cafs-caf-id) | Desactiva un CAF (el historial se conserva) | ## `GET /folios` [#get-folios] **Disponibilidad de folios por tipo de documento** Los rangos de folios (respaldados por CAF) disponibles para la empresa, con cuántos quedan de cada `tipo_dte` antes de necesitar una nueva solicitud. ```bash curl -sS https://api.facturia.cl/v1/folios \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ------------------ | ------ | --------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | | `tipo_dte` | query | — | `33` · `34` · `39` · `41` · `46` · `52` · `56` · `61` | | **Respuestas** | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | | `200` | Los rangos de folios. | lista de FolioRange | | `400` | Entrada mal formada o incompleta. | ErrorResponse | | `401` | Llave ausente, mal formada o revocada. | ErrorResponse | | `403` | Llave válida pero sin permiso: scope, lista blanca de empresas o modo. | ErrorResponse | | `429` | Demasiadas solicitudes. | ErrorResponse | | `default` | Un error no enumerado aparte para esta operación, en el mismo sobre §5.5 que cualquier otro rechazo. Ramifica por `error.code`, nunca solo por el estado HTTP ni por `error.message` — un código que esta operación aún no se ha visto lanzar sigue siendo más seguro para decidir que un texto pensado para una persona. | ErrorResponse | ## `POST /folios/requests` [#post-folios-requests] **Solicita un CAF nuevo al SII (asíncrono)** El timbraje del SII es un flujo de portal guionizado, no un webservice. Devuelve un 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}' ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ------------------ | ------ | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | | `Idempotency-Key` | header | — | string | Llave que genera el cliente, única por operación lógica, retenida 24 h y con alcance (cuenta, empresa, endpoint). Un replay devuelve la respuesta original con `Facturia-Idempotent-Replay: true`. Misma llave y cuerpo distinto → `409`. | **Cuerpo** | Campo | Tipo | Requerido | Notas | | -------------- | ----------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tipo_dte` | `33` · `34` · `39` · `41` · `46` · `52` · `56` · `61` | sí | 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. Las boletas (39/41) viajan por otro transporte del SII; eso es invisible desde esta API. | | `quantity` | integer | — | Cuántos folios pides. Omítelo y Facturia dimensiona según tu historial de consumo. | | **Respuestas** | | | | | Código | Significado | Cuerpo | | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `202` | Job aceptado. | Job | | `401` | Llave ausente, mal formada o revocada. | ErrorResponse | | `402` | `subscription_required` - este acto real necesita una suscripción activa de la EMPRESA que el request nombra, y esa empresa no la tiene (se aplica de verdad). La suscripción es por empresa: las demás empresas de la misma cuenta no se ven afectadas, y `error.details` trae `empresa`, `empresa_rut`, `empresa_name`, `account_plan`, `subscription_status`, `grace_until`, `blocked_by`, un handoff `next` y un `checkout_url` que apunta a esa empresa. O bien `plan_limit_reached` - una cuota de plan agotada (declarado, todavía sin emisor). El modo de prueba nunca se bloquea por ninguno de los dos. **LA ELEGIBILIDAD SE EVALÚA PRIMERO** (2026-09-04, #475). Este rechazo ahora llega SOLO cuando la empresa por lo demás puede emitir: mientras su checklist está incompleto, su puesta en vivo pendiente o la empresa suspendida, el acto se rechaza con `422 empresa_not_emitting` y el handoff del checklist. Así este `402` y `Empresa.capabilities.blocked_by` ya no pueden nombrar dos acciones siguientes distintas para un mismo estado — que es lo que hacían: el objeto decía «firma el mandato» y la puerta decía «paga». | ErrorResponse | | `403` | Llave válida pero sin permiso: scope, lista blanca de empresas o modo. | ErrorResponse | | `422` | Bien formado pero viola una regla del dominio: folios agotados, ventana de acuse cerrada. | ErrorResponse | | `429` | Demasiadas solicitudes. | ErrorResponse | | `default` | Un error no enumerado aparte para esta operación, en el mismo sobre §5.5 que cualquier otro rechazo. Ramifica por `error.code`, nunca solo por el estado HTTP ni por `error.message` — un código que esta operación aún no se ha visto lanzar sigue siendo más seguro para decidir que un texto pensado para una persona. | ErrorResponse | ## `GET /cafs` [#get-cafs] **Lista los CAF que esta empresa tiene cargados** Todos los CAF (autorización de folios) cargados para la empresa, con su rango, `tipo_dte` y cuántos folios quedan. ```bash curl -sS https://api.facturia.cl/v1/cafs \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ------------------ | ------ | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | | `limit` | query | — | integer | | | `cursor` | query | — | string | Cursor opaco tomado del `next_cursor` de una respuesta anterior. | **Respuestas** | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `200` | Una lista de CAF. | lista de Caf | | `401` | Llave ausente, mal formada o revocada. | ErrorResponse | | `403` | Llave válida pero sin permiso: scope, lista blanca de empresas o modo. | ErrorResponse | | `429` | Demasiadas solicitudes. | ErrorResponse | | `default` | Un error no enumerado aparte para esta operación, en el mismo sobre §5.5 que cualquier otro rechazo. Ramifica por `error.code`, nunca solo por el estado HTTP ni por `error.message` — un código que esta operación aún no se ha visto lanzar sigue siendo más seguro para decidir que un texto pensado para una persona. | ErrorResponse | ## `POST /cafs` [#post-cafs] **Carga un CAF que ya tienes** Carga un archivo CAF obtenido desde el portal del SII. Se rechaza si su rango se traslapa con uno ya registrado para el mismo `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":"…"}' ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ------------------ | ------ | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | | `Idempotency-Key` | header | — | string | Llave que genera el cliente, única por operación lógica, retenida 24 h y con alcance (cuenta, empresa, endpoint). Un replay devuelve la respuesta original con `Facturia-Idempotent-Replay: true`. Misma llave y cuerpo distinto → `409`. | **Cuerpo** | Campo | Tipo | Requerido | Notas | | -------------- | ------ | --------- | --------------------------------------------------------------------- | | `caf_xml` | string | sí | El XML `<AUTORIZACION>` crudo, tal como lo descargaste del SII. | | **Respuestas** | | | | | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `201` | CAF registrado. | Caf | | `400` | Entrada mal formada o incompleta. | ErrorResponse | | `401` | Llave ausente, mal formada o revocada. | ErrorResponse | | `403` | Llave válida pero sin permiso: scope, lista blanca de empresas o modo. | ErrorResponse | | `429` | Demasiadas solicitudes. | ErrorResponse | | `default` | Un error no enumerado aparte para esta operación, en el mismo sobre §5.5 que cualquier otro rechazo. Ramifica por `error.code`, nunca solo por el estado HTTP ni por `error.message` — un código que esta operación aún no se ha visto lanzar sigue siendo más seguro para decidir que un texto pensado para una persona. | ErrorResponse | ## `DELETE /cafs/{caf_id}` [#delete-cafs-caf-id] **Desactiva un CAF (el historial se conserva)** Desactiva un CAF (`active: false`). Los folios ya asignados desde él no se ven afectados; el rango solo deja de ofrecer folios nuevos. ```bash curl -sS -X DELETE https://api.facturia.cl/v1/cafs/caf_01K2P4V8QW2M \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ------------------ | ------ | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `caf_id` | path | sí | string | | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | **Respuestas** | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `204` | Desactivado. | — | | `401` | Llave ausente, mal formada o revocada. | ErrorResponse | | `403` | Llave válida pero sin permiso: scope, lista blanca de empresas o modo. | ErrorResponse | | `404` | No existe ese objeto bajo esta llave. | ErrorResponse | | `429` | Demasiadas solicitudes. | ErrorResponse | | `default` | Un error no enumerado aparte para esta operación, en el mismo sobre §5.5 que cualquier otro rechazo. Ramifica por `error.code`, nunca solo por el estado HTTP ni por `error.message` — un código que esta operación aún no se ha visto lanzar sigue siendo más seguro para decidir que un texto pensado para una persona. | ErrorResponse |