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

Lista los documentos de la empresa, del más nuevo al más antiguo, filtrable por tipo_dte, status y rango de fechas.

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

Responde 201 con status: queued y folio: null. El folio llega cuando el documento pasa a sent: lo asigna el motor después de que la fila existe, así que ningún 201 puede traerlo. Ese null es una ESPERA, no una falla y no un marcador de posición — obsérvalo con document.sent, o releyendo el documento a la cadencia que te da Facturia-Poll-After.

La ida y vuelta al SII que viene después es una máquina de estados que se mira igual. Todo lo que no mandas se rellena con el perfil de la empresa (bloque emisor, giro, dirección), el registro de receptores 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

Un documento: su status de ciclo de vida, los totales, public_links si tiene alguno vigente, y rejection_reasons si el SII lo rechazó.

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

El PDF renderizado del documento (?copy=original o cedible donde la Ley 19.983 da una). 409 artifact_not_ready si el SII aún no acepta el documento — la representación impresa se renderiza al aceptarse, no antes.

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

El XML exacto que Facturia envió al SII (o va a enviar), para quien quiere los bytes tal cual en vez del objeto ya interpretado.

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

El historial propio de eventos del documento — cada webhook document.* que Facturia publicó para él, en orden, sin importar si la entrega tuvo éxito.

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

202 cuando ESTA llamada creó el envío; 200 con el MISMO job cuando ya existe uno idéntico (mismo documento, mismas direcciones, mismos adjuntos) — un correo, un id de job, igual que en la §10.2 «emitir dos veces la misma previsualización devuelve el documento original». Los dos estados traen el mismo cuerpo, así que un cliente que solo maneja uno está manejando la mitad del endpoint.

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}/cesion

Pregúntale al SII si esta factura es cedible

SOLO LECTURA (ticket #47). Encola una consulta al registro del propio SII (WSREGISTRORECLAMODTE.consultarDocDteCedible) y guarda la respuesta en el objeto cesion del documento. Acá no se cede nada, no se arma ningún AEC y no se escribe en el Registro de Cesión de Créditos — esa operación no lleva código de acción y no puede cambiar el estado en el SII.

Bajo la Ley 19.983 una factura se vuelve cedible cuando el receptor da acuse de recibo, o cuando pasan ocho días corridos sin reclamo; una que el emisor declaró pagada al contado no se vuelve cedible nunca (Circular N°35 de 23.06.2017). Cuál de esas aplica lo sabe solo el SII, así que esto es un reporte, nunca un cálculo nuestro.

202 cuando esta llamada encoló la pregunta, 200 cuando ya hay una idéntica en vuelo. Consulta GET /documents/\{document_id\} para la respuesta; no hay webhook.

Acepta una llave con documents:read: el integrador que necesita esto es un sistema de factoring, y no debería tener que cargar con una llave capaz de emitir facturas.

En modo de prueba la respuesta se simula en proceso contra el reloj simulado de la empresa y no se abre ningún socket al SII — 24 hasta ocho días después de la aceptación, 25 de ahí en adelante.

curl -sS -X POST https://api.facturia.cl/v1/documents/doc_01K2R7Q4XW9M3B8ZC5YHTVJD6N/cesion \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA" \
  -H "Idempotency-Key: $(uuidgen)"

Parámetros

Respuestas

POST /documents/{document_id}/cede

Cede esta factura a un factoring, inscribiéndola en el RTC del SII

LA ESCRITURA (ticket #60), a diferencia del POST …/cesion de más arriba (una lectura). Arma un Archivo Electrónico de Cesión — el DTE original firmado por el emisor, más los términos de la transferencia, firmados por el cedente — y lo sube al Registro Electrónico de Transferencia de Crédito del SII. Un acto real e irreversible.

Funciona igual sin importar el canal (ticket #60, resuelto 2026-09-06): el AEC lleva el sobre original firmado tal cual, así que no le importa si el DTE se emitió por emission_channel=sfg o emission_channel=mercado. cesion_channel_unsupported, el código que lanzaba la antigua barrera de canal, está RETIRADO del catálogo.

202 con un job cuando esta llamada encoló un intento NUEVO; 200 con el MISMO job cuando ya hay uno queued/submitted/aec_generated para este documento (un intento en vuelo a la vez). GET /documents/\{document_id\} trae el resultado del intento más nuevo en cesion.status.

UN ACUSE DE RECIBO NO ES UN REGISTRO (ticket #69). Lo más lejos que la subida misma puede llevar un intento es submitted — el SII respondió «Envío recibido OK» y entregó un TrackID. Su validación ocurre después, y un rechazo se avisa por correo al cedente horas más tarde, así que esta API declara confirmed solo cuando la propia consulta del registro, wsRPETCConsulta.getEstEnvio, responde EOK («Envío Aceptado») para ese TrackID. Los webhooks siguen exactamente eso: document.cesion_submitted significa «AEC recibido, anotación pendiente», document.cesion_confirmed es el que sirve para mover plata, y document.cesion_failed cubre un rechazo, una barrera, una respuesta que nadie reconoce y un registro que nunca se pudo confirmar.

409 cesion_attempt_may_have_registered cuando el intento más nuevo de este documento ya había puesto el AEC firmado en el cable al detenerse (ticket #76). Desde aquí no se puede decidir si alcanzó a inscribirse, así que una segunda cesión se rechaza en vez de arriesgar que el mismo crédito quede asignado dos veces. error.details trae la última respuesta que este sistema conoce del registro para ese intento (rtc_estado, rtc_track_id) cuando alguna vez se registró — leerla cuesta una columna, no una nueva llamada al SII; cuando nunca se registró ninguna, los detalles lo dicen así en vez de adivinar.

En modo de prueba esto se resuelve en la misma request (§4.1) — no se abre socket, el intento queda simulated, y se disparan LOS DOS document.cesion_submitted y document.cesion_confirmed, en ese orden, para que el evento sobre el que actúa una integración de factoring sea ejercitable en pruebas.

El envío en vivo sigue bloqueado por el dueño, y desde la resolución 2026-09-06 (R6) también por empresa: el armado del AEC y la subida al registro están construidos y verificados contra el propio esquema del SII — la primera subida en vivo (2026-09-03) fue aceptada por el registro con un TrackID real y luego rechazada en validación por un defecto de firma, ya corregido. Abrirlo exige LAS DOS cosas a la vez: ALLOW_LIVE_CESION_SUBMITS leído desde el propio shell de un operador (nunca de un deploy), Y que la conexión de la empresa cedente haya llegado a onboarding_status=emitting, esté active, en ambiente=palena y no sea una conexión sandbox. Un intento en vivo al que le falte cualquiera de las dos se acepta y se encola como cualquier otro, y termina failed sin reintento, nombrando cuál condición falta.

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

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

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

cedible (ticket #18 wave 10) NO está en el conjunto por defecto: a diferencia de pdf/xml, no existe para todo documento, así que quien no lo pidió no recibe uno minteado en silencio — imitando ?copy= en GET …/pdf, que por defecto es original en vez de adivinar. Pedirlo para un tipo fuera de 33/34 es 422 cedible_not_available; pedirlo en una empresa emission_channel=sfg, en cualquier tipo, es 422 cedible_not_available_for_channel (#48) — el SII proxea su propio PDF para ese canal y nunca existe una copia cedible de él, así que esto rechaza el minteo en vez de devolver un link .cedible que solo podría resolver al archivo no-cedible.

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

Revoca todos los enlaces públicos vigentes acuñados para el documento. Las copias ya guardadas de la URL siguen funcionando hasta vencer; esto solo detiene descargas nuevas.

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