# Previews (/docs/emision/previews)

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 [#borrador]

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

```json
{
  "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.

* `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 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` [#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 [#emitir-lo-aprobado]

```bash
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 [#cuándo-usarlo]

- [Sí](/docs/mcp/herramientas): Cuando un agente arma el documento — es el flujo `draft_document` → `emit_document` del servidor MCP.

- [Sí](/docs/emision): 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.