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

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

`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
`422`	Bien formado pero viola una regla del dominio: folios agotados, ventana de acuse cerrada.	ErrorResponse

`GET /cafs`

Lista los CAF que esta empresa tiene cargados

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

`POST /cafs`

Carga un CAF que ya tienes

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

`DELETE /cafs/{caf_id}`

Desactiva un CAF (el historial se conserva)

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.	—
`404`	No existe ese objeto bajo esta llave.	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}`