Folios y CAF

Disponibilidad de folios por tipo de documento, solicitud de timbraje y carga de CAF propios.

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.

Método	Ruta	Qué hace
`GET`	`/folios`	Disponibilidad de folios por tipo de documento
`POST`	`/folios/requests`	Solicita un CAF nuevo al SII (asíncrono)
`GET`	`/cafs`	Lista los CAF que esta empresa tiene cargados
`POST`	`/cafs`	Carga un CAF que ya tienes
`DELETE`	`/cafs/{caf_id}`	Desactiva un CAF (el historial se conserva)

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

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`

Solicita un CAF nuevo al SII (asíncrono)

El timbraje del SII es un flujo de portal guionizado, no un webservice. Devuelve un 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}'

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`

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.

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`

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.

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

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

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.

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

GET /folios

POST /folios/requests

GET /cafs

POST /cafs

DELETE /cafs/{caf_id}

En esta página

`GET /folios`

`POST /folios/requests`

`GET /cafs`

`POST /cafs`

`DELETE /cafs/{caf_id}`