Previews
Precio y validación completos sin gastar un folio — el paso que existe cuando las cifras vienen de algo blando, como una persona o un agente.
La emisión es irreversible: gasta un folio y produce un documento legal. Cuando las cifras vinieron de algo blando — una persona describiendo una factura en prosa, un agente LLM armándola — quieres un paso que la valorice y la muestre antes de que nada de eso ocurra.
Borrador
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"},
"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"
}Un preview corre el validador de emisión entero — las mismas negativas, con las mismas palabras — y después no ejecuta nada de la emisión.
folioesnullporque no se tomó ninguno.folio_previewes el folio que se usaría, leído del contador y no reservado.- Se guarda por una hora y se puede leer con
GET /v1/documents/previews/{preview_id}, que devuelve lo que se calculó en vez de volver a valorizar: que los totales se muevan entre que se muestran y que se aprueban es exactamente la falla que este flujo existe para evitar.
resolution_method
Dice cómo se identificó al receptor:
| Valor | Significado |
|---|---|
rut_exact | Se identificó por RUT |
anonymous | Una boleta sin receptor |
needs_clarification | Diste un nombre y no un RUT, así que el documento iría al consumidor anónimo |
En el último caso, pide el RUT. No vamos a adivinar uno.
Emitir lo aprobado
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"}'El request guardado se reproduce por el camino de creación normal, así que nada de la emisión difiere de una directa.
Trampa
Emitir el mismo preview dos veces devuelve el documento original
No un segundo documento: un 200 en vez del 201, sin gastar un folio nuevo. Esa propiedad está
garantizada en la base de datos, no en un proceso, así que sobrevive a reintentos concurrentes.
Existe porque un agente reintentando una llamada de herramienta es el caso ordinario aquí, y los
agentes rara vez mandan un Idempotency-Key.
Junto a preview_id solo puedes enviar external_id y metadata. Ninguno de los dos puede cambiar
un monto, un receptor ni una fecha: las cifras que se aprobaron son las cifras que salen, y no hay
parámetro que vuelva eso falso.
Cuándo usarlo
Sí
Cuando un agente arma el documento — es el flujo draft_document → emit_document del servidor MCP.
Sí
Cuando una persona confirma en pantalla y quieres que vea el mismo número que se va a emitir.
No lo necesitas cuando tu propio sistema ya tiene las cifras exactas y las manda con totals como
aserción: en ese caso 422 totals_mismatch ya te protege del mismo error, en una sola llamada.