Documentos

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.

GET /documents

Lista los documentos emitidos

curl -sS https://api.facturia.cl/v1/documents \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA"

Parámetros

Respuestas

POST /documents

Emite un DTE

Síncrono: devuelve 201 con un folio asignado y status: queued. La ida y vuelta al SII es asíncrona — obsérvala con webhooks o consultando el documento. Todo lo que no envías se completa desde el perfil de la empresa (bloque emisor, giro, dirección), el registro de contribuyentes y las reglas tributarias del tipo.

curl -sS -X POST https://api.facturia.cl/v1/documents \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"tipo_dte":33,"items":[{"description":"Consultoría","quantity":1,"unit_price":1200000}]}'

Parámetros

Cuerpo

POST /documents/previews

Cotiza y valida un documento sin emitirlo

Corre el validador de emisión COMPLETO — los mismos rechazos, con las mismas palabras — y después no emite nada. folio es null porque no se tomó ninguno; folio_preview es el folio que se USARÍA, leído del contador y no reservado.

Se guarda una hora y se lee con GET /documents/previews/\{preview_id\}, que devuelve lo que se calculó en vez de volver a cotizar: que los totales cambien entre que se muestran y que se aprueban es justamente la falla que este flujo existe para evitar.

Para emitirla, manda \{"preview_id": "prev_…"\} a POST /documents. Emitir dos veces la misma previsualización devuelve el documento ORIGINAL con 200 y no gasta un segundo folio — una propiedad garantizada en la base de datos, porque un agente que reintenta una llamada de herramienta es el caso normal aquí y los agentes rara vez mandan Idempotency-Key.

curl -sS -X POST https://api.facturia.cl/v1/documents/previews \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA" \
  -H "Content-Type: application/json" \
  -d '{"tipo_dte":33,"items":[{"description":"Consultoría","quantity":1,"unit_price":1200000}]}'

Parámetros

Cuerpo

GET /documents/previews/{preview_id}

Lee una previsualización guardada

Devuelve lo que se calculó, nunca un recálculo. Una previsualización ya emitida sigue siendo legible con emitted: true y un consumed_at; una sin usar desaparece una hora después de creada y responde 404.

curl -sS https://api.facturia.cl/v1/documents/previews/prev_01K2R9M3D8V5QW7N \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA"

Parámetros

Respuestas

GET /documents/{document_id}

Devuelve un documento

curl -sS https://api.facturia.cl/v1/documents/doc_01K2R7Q4XW9M3B8ZC5YHTVJD6N \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA"

Parámetros

Respuestas

GET /documents/{document_id}/pdf

Descarga el PDF

curl -sS https://api.facturia.cl/v1/documents/doc_01K2R7Q4XW9M3B8ZC5YHTVJD6N/pdf \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA"

Parámetros

Respuestas

GET /documents/{document_id}/xml

Descarga el XML firmado, exactamente como se envió al SII

curl -sS https://api.facturia.cl/v1/documents/doc_01K2R7Q4XW9M3B8ZC5YHTVJD6N/xml \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA"

Parámetros

Respuestas

GET /documents/{document_id}/events

Eventos del ciclo de vida de un documento

curl -sS https://api.facturia.cl/v1/documents/doc_01K2R7Q4XW9M3B8ZC5YHTVJD6N/events \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA"

Parámetros

Respuestas

POST /documents/{document_id}/retry

Reintenta un documento en failed

Reutiliza el folio ya asignado. Nunca crea un segundo documento.

curl -sS -X POST https://api.facturia.cl/v1/documents/doc_01K2R7Q4XW9M3B8ZC5YHTVJD6N/retry \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA"

Parámetros

Respuestas

POST /documents/{document_id}/send

Envía el documento por correo al receptor

curl -sS -X POST https://api.facturia.cl/v1/documents/doc_01K2R7Q4XW9M3B8ZC5YHTVJD6N/send \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"to":["[email protected]"],"attach":["pdf","xml"]}'

Parámetros

Cuerpo

POST /documents/{document_id}/credit_note

Emite una nota de crédito contra este documento

En Chile no existe «borrar una factura». code: 1 anula el documento referenciado, 2 corrige texto y 3 corrige montos (con items para los valores corregidos).

curl -sS -X POST https://api.facturia.cl/v1/documents/doc_01K2R7Q4XW9M3B8ZC5YHTVJD6N/credit_note \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"code":1,"reason":"content"}'

Parámetros

Cuerpo

POST /documents/{document_id}/public_links

Crea o rota los enlaces públicos de los artefactos de este documento

Enciende un enlace público después de emitir, o rota uno existente (lo que invalida la URL anterior). Un enlace expone exactamente un artefacto de un documento — nunca los demás documentos de la empresa ni datos de la cuenta — y no puede escalarse a una credencial de API.

curl -sS -X POST https://api.facturia.cl/v1/documents/doc_01K2R7Q4XW9M3B8ZC5YHTVJD6N/public_links \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"artifacts":["pdf","xml"]}'

Parámetros

Cuerpo

DELETE /documents/{document_id}/public_links

Revoca todos los enlaces públicos de este documento

curl -sS -X DELETE https://api.facturia.cl/v1/documents/doc_01K2R7Q4XW9M3B8ZC5YHTVJD6N/public_links \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA"

Parámetros

Respuestas