Previews
Full pricing and validation without spending a folio — the step that exists when the figures come from something soft, like a person or an agent.
Issuing is irreversible: it spends a folio — the pre-authorised sequential number a document must carry — and produces a legal document. When the figures came from something soft — a person describing a factura, Chile's electronic invoice, in prose; an LLM agent assembling one — you want a step that prices it and shows it before any of that happens.
Draft
curl -sS 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,
"receptor":{"rut":"76543212-K","giro":"Venta al por mayor de alimentos",
"address":{"street":"Los Militares 5001, of. 302","comuna":"Las Condes","city":"Santiago"}},
"items":[{"description":"Consultoría","quantity":2,"unit_price":500000}]}'{
"id": "prev_01K2R9...",
"preview_id": "prev_01K2R9...",
"object": "document_preview",
"tipo_dte": 33,
"totals": { "net": 1000000, "exempt": 0, "iva": 190000, "other_taxes": 0, "total": 1190000 },
"resolved_receptor": { "rut": "76543212-K", "legal_name": null, "resolution_method": "rut_exact" },
"folio_preview": 1042,
"folio": null,
"emitted": false,
"warnings": [],
"expires_at": "2026-08-14T14:12:40Z"
}A preview runs the whole issuing validator — the same refusals, in the same words — and then runs none of the issuing itself.
folioisnullbecause none was taken.folio_previewis the folio that would be used, read from the counter and not reserved.- It is kept for an hour and can be read with
GET /v1/documents/previews/{preview_id}, which returns what was calculated instead of pricing it again: totals moving between being shown and being approved is exactly the failure this flow exists to prevent.
resolution_method
It says how the receptor was identified:
| Value | Meaning |
|---|---|
rut_exact | Identified by RUT, Chile's taxpayer id |
anonymous | A boleta with no receptor |
needs_clarification | You gave a name and not a RUT, so the document would go to the anonymous consumer |
In that last case, ask for the RUT. We are not going to guess one.
Issue what was approved
curl -sS https://api.facturia.cl/v1/documents \
-H "Authorization: Bearer $FACTURIA_KEY" -H "Facturia-Empresa: $EMPRESA" \
-H "Content-Type: application/json" \
-d '{"preview_id":"prev_01K2R9...","external_id":"ORD-1042"}'The stored request is replayed through the normal creation path, so nothing about the issue differs from a direct one.
Trap
Issuing the same preview twice returns the original document
Not a second document: a 200 instead of the 201, without spending a new folio. That property is
guaranteed in the database, not in a process, so it survives concurrent retries.
It exists because an agent retrying a tool call is the ordinary case here, and agents rarely send an
Idempotency-Key.
Alongside preview_id you may send only external_id and metadata. Neither of them can change an
amount, a receptor or a date: the figures that were approved are the figures that come out, and there is
no parameter that makes that false.
When to use it
Yes
When an agent assembles the document — it is the MCP server's draft_document → emit_document flow.
Yes
When a person confirms on screen and you want them to see the same number that will be issued.
You do not need it when your own system already has the exact figures and sends them as a totals
assertion: there, 422 totals_mismatch already protects you from the same mistake, in a single call.