Documents

Base: https://api.facturia.cl/v1. Every endpoint in this chapter authenticates with Authorization: Bearer unless stated otherwise, and the error envelope is the one in Errors.

GET /documents

List emitted documents

List documents for the empresa, newest first, filterable by tipo_dte, status and date range.

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

Parameters

Responses

POST /documents

Emit a DTE

Returns 201 with status: queued and folio: null. The folio arrives when the document reaches sent: it is allocated by the engine after the row exists, so no 201 can carry one. null there is a WAIT, not a failure and not a placeholder — observe it with document.sent, or by re-reading the document on the cadence Facturia-Poll-After gives you.

The SII round-trip after that is a state machine you watch the same way. Everything not supplied is defaulted from the empresa profile (emisor block, giro, dirección), the receptor registry, and the tipo's tax rules.

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

Parameters

Body

POST /documents/previews

Price and validate a document without emitting it

Runs the ENTIRE emission validator — the same refusals, in the same words — and then performs none of the emission. folio is null because none was taken; folio_preview is the folio that WOULD be used, read from the counter and not reserved.

Stored for an hour and readable with GET /documents/previews/\{preview_id\}, which returns what was computed rather than re-pricing: totals that moved between being shown and being approved is the failure this flow exists to prevent.

Emit it by sending \{"preview_id": "prev_…"\} to POST /documents. Emitting the same preview twice returns the ORIGINAL document with 200 and spends no second folio — a property enforced in the database, because an agent retrying a tool call is the ordinary case here and agents rarely send an 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}]}'

Parameters

Body

GET /documents/previews/{preview_id}

Retrieve a stored preview

Returns what was computed, never a re-computation. A preview that has been emitted stays readable with emitted: true and a consumed_at; an unconsumed one is gone an hour after it was created and answers 404.

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

Parameters

Responses

GET /documents/{document_id}

Retrieve a document

One document: its lifecycle status, totals, public_links if any are live, and rejection_reasons if the SII refused it.

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

Parameters

Responses

GET /documents/{document_id}/pdf

Download the PDF

The document's rendered PDF (?copy=original or cedible where Ley 19.983 gives one). 409 artifact_not_ready if the SII has not accepted the document yet — the representación impresa is rendered on acceptance, not before.

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

Parameters

Responses

GET /documents/{document_id}/xml

Download the signed XML exactly as sent to the SII

The exact XML Facturia sent to the SII (or will send), for a caller that wants the wire bytes rather than the parsed object.

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

Parameters

Responses

GET /documents/{document_id}/events

Lifecycle events for one document

The document's own event history — every document.* webhook Facturia published for it, in order, independent of whether delivery succeeded.

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

Parameters

Responses

POST /documents/{document_id}/retry

Retry a document in failed

Reuses the already-assigned folio. Never creates a second document.

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

Parameters

Responses

POST /documents/{document_id}/send

Email the document to the receptor

202 when THIS call created the send; 200 with the SAME job when an identical one (same document, same addresses, same attachments) already exists — one email, one job id, mirroring §10.2's "emitting the same preview twice returns the original document". Both statuses carry the same body, so a client that only handles one of them is handling half the 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"]}'

Parameters

Body

POST /documents/{document_id}/cesion

Ask the SII whether this factura is cedible

READ-ONLY (ticket #47). Queues a query against the SII's own registro (WSREGISTRORECLAMODTE.consultarDocDteCedible) and caches the answer on the document's cesion object. Nothing here cedes the invoice, builds an AEC, or writes to the Registro de Cesión de Créditos — that operation takes no action code and cannot change SII state.

Under Ley 19.983 a factura becomes assignable when the receptor gives acuse de recibo, or when eight días corridos pass without a reclamo; one declared as paid al contado never does (Circular N°35 de 23.06.2017). Only the SII knows which of those applies, so this is a report, never a computation.

202 when this call queued the question, 200 when an identical one is already in flight. Poll GET /documents/\{document_id\} for the answer; there is no webhook.

Accepts a documents:read key: the caller this exists for is a factoring integration, which should not need one that can issue invoices.

In test mode the answer is simulated in-process against the empresa's simulated clock and no SII socket is opened — 24 until eight days after acceptance, 25 after.

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)"

Parameters

Responses

POST /documents/{document_id}/cede

Cede this factura to a factoring company, registering it in the SII's RTC

THE WRITE (ticket #60), unlike POST …/cesion above (a read). Assembles an Archivo Electrónico de Cesión — the emisor's original signed DTE plus the terms of the transfer, signed by the cedente — and uploads it to the SII's Registro Electrónico de Transferencia de Crédito. A real, irreversible act.

Works the same regardless of channel (ticket #60, ruled 2026-09-06): the AEC carries the emisor's original signed envelope verbatim, so it does not care whether the DTE was emitted through emission_channel=sfg or emission_channel=mercado. cesion_channel_unsupported, the code the old channel guard raised, is RETIRED from the catalogue.

202 with a job when this call queued a NEW attempt; 200 with the SAME job when one is already queued/submitted/aec_generated for this document (one attempt in flight at a time). GET /documents/\{document_id\} carries the newest attempt's outcome under cesion.status.

A RECEIPT IS NOT A REGISTRATION (ticket #69). The furthest the upload itself can take an attempt is submitted — the SII answered «Envío recibido OK» and issued a TrackID. Its validation happens afterwards, and a rejection is notified by e-mail to the cedente hours later, so this API claims confirmed only when the registry's own wsRPETCConsulta.getEstEnvio answers EOK («Envío Aceptado») for that TrackID. Webhooks follow that exactly: document.cesion_submitted means «AEC recibido, anotación pendiente», document.cesion_confirmed is the one to settle money on, and document.cesion_failed covers a refusal, a fence, an answer nobody recognises, and a registration that could never be confirmed.

409 cesion_attempt_may_have_registered when the newest attempt for this document had already put the signed AEC on the wire when it stopped (ticket #76). Whether it registered cannot be decided from here, so a second cesión is refused rather than risking the same credit being assigned twice. error.details carries this system's own last known registry answer for that attempt (rtc_estado, rtc_track_id) when one was ever recorded — reading it costs a column, not a new SII call; when neither was ever recorded the details say so.

In test mode this settles in the same request (§4.1) — no socket opened, the attempt lands simulated, and BOTH document.cesion_submitted and document.cesion_confirmed fire, in that order, so the event a factoring integration acts on is exercisable in test.

Live submission is owner-gated, and since the 2026-09-06 ruling (R6) also gated per empresa: the AEC assembly and the registry upload are built and checked against the SII's own schema — the first live upload (2026-09-03) was accepted by the registry with a real TrackID and then rejected at validation for a signature defect, since fixed. Opening it needs BOTH ALLOW_LIVE_CESION_SUBMITS (an operator's own shell, never a deploy) AND the ceding empresa's own connection reaching onboarding_status=emitting, active, ambiente=palena and not a sandbox connection. A live attempt missing either one is accepted and queued like any other and settles failed non-retryably, naming whichever condition is missing.

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

Parameters

Body

POST /documents/{document_id}/credit_note

Emit a nota de crédito against this document

There is no "delete an invoice" in Chile. code: 1 annuls the referenced document, 2 corrects text, 3 corrects amounts (supply items for the corrected values).

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

Parameters

Body

POST /documents/{document_id}/public_links

Create or rotate public links for this document's artifacts

Turns a public link on after the fact, or rotates an existing one (which invalidates the previous URL). A link exposes exactly one artifact of one document — never the empresa's other documents, never account data — and cannot be escalated into an API credential.

cedible (ticket #18 wave 10) is NOT in the default set: unlike pdf/xml it does not exist for every document, so a caller who did not ask for it does not get one minted silently — mirroring ?copy= on GET …/pdf, which defaults to original rather than guessing. Requesting it for a tipo outside 33/34 is 422 cedible_not_available; requesting it on an emission_channel=sfg empresa, on any tipo, is 422 cedible_not_available_for_channel (#48) — the SII proxies its own PDF for that channel and no cedible copy of it ever exists, so this refuses the mint rather than handing back a .cedible link that could only ever resolve to the non-cedible file.

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

Parameters

Body

DELETE /documents/{document_id}/public_links

Revoke every public link for this document

Revoke every live public link minted for the document. Already-cached copies of the URL keep working until they expire; this only stops new fetches.

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

Parameters

Responses