Vista previa de una factura (sin timbrar)
Desde la v1.53.0, valida una factura de ingreso y la arma exactamente como se timbraría, sin timbrarla: no cobra, no aparta folio y no guarda nada.
Recibe el mismo cuerpo que POST /v1/invoices y corre todas sus validaciones. Responde los totales, los datos del CFDI 4.0 sin sellar y html: la representación impresa, con la misma plantilla que el PDF, la marca de agua PREVIEW y la leyenda «VISTA PREVIA — SIN VALIDEZ FISCAL», sin UUID, sellos ni QR.
Sirve para que una persona revise la factura antes de timbrarla. Para timbrar lo que se aprobó, manda el mismo cuerpo a POST /v1/invoices con tu Idempotency-Key.
Es opcional: POST /v1/invoices no la exige. No pide Idempotency-Key, no consume timbre ni saldo, no incrementa el folio del emisor y no crea ningún recurso.
folio es el del cuerpo o, si no lo mandas, el siguiente folio del emisor (folioIsProjected: true): puede cambiar si se timbran otras facturas antes. fecha es la hora de la vista previa, salvo que el cuerpo traiga una.
La guía completa, con el flujo del servidor MCP, está en vista previa de la factura antes de timbrar.
En video
Authorization: Bearer sk_test_... | sk_live_...El header x-account-id indica la cuenta. Si no eres miembro, la respuesta es 403.
Ejemplos
curl -X POST https://api.cfdi.express/v1/invoices/preview \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"merchantId": "mkq2f8v3x1t7p9d4n6c0b5rz",
"metodoPago": "PPD",
"formaPago": "99",
"usoCfdi": "G03",
"receiver": {
"rfc": "XIA190128J61",
"name": "XENON INDUSTRIAL ARTICLES",
"zip": "01160",
"regimenFiscal": "601"
},
"items": [
{
"productCode": "43201808",
"unitCode": "H87",
"description": "Teclado mecánico 75%",
"quantity": 20,
"unitPrice": 2500,
"ivaRate": 0.16
}
],
"pricesIncludeTax": false
}'Respuesta
{
"object": "invoice_preview",
"livemode": false,
"merchantId": "mkq2f8v3x1t7p9d4n6c0b5rz",
"emisor": { "rfc": "EKU9003173C9", "name": "ESCUELA KEMPER URGATE" },
"kind": "nominal",
"serie": "A",
"folio": "53",
"folioIsProjected": true,
"fecha": "2026-11-17T11:30:00",
"metodoPago": "PPD",
"formaPago": "99",
"usoCfdi": "G03",
"currency": "MXN",
"exchangeRate": 1,
"subtotal": 50000,
"discount": 0,
"total": 58000,
"receiver": {
"rfc": "XIA190128J61",
"nombre": "XENON INDUSTRIAL ARTICLES",
"domicilioFiscal": "01160",
"regimenFiscal": "601"
},
"cfdi": { "Version": "4.0", "TipoDeComprobante": "I", "...": "recortado" },
"html": "<!DOCTYPE html>…"
}Errores
| Status | code | Cuándo aparece |
|---|---|---|
| 400 | validation_error | El mismo cuerpo lo rechazaría POST /v1/invoices: mismo detail, subcode y errors que el timbrado. También cuando la factura no tiene conceptos o da un total en cero. |
| 401 | unauthorized | Falta el header Authorization o la llave es inválida. |
| 403 | forbidden | No eres miembro de la cuenta del header x-account-id. |
| 404 | not_found | El merchantId no existe en tu cuenta. |
| 429 | rate_limited | Excediste el límite de requests por minuto de tu cuenta (300 por default). La respuesta incluye Retry-After. |
Notas
receiverviene como se timbra:rfc,nombre,domicilioFiscalyregimenFiscal(másresidenciaFiscalynumRegIdTribsi aplican). En una factura global,nombreesPUBLICO EN GENERAL.- Nunca responde 402: la vista previa no usa saldo. Un rechazo del SAT (
sat_rejected) solo puede aparecer al timbrar. - Por MCP es la herramienta
preview_invoice. En ChatGPT y Claude muestra una tarjeta con los botones «Autorizar y timbrar», «Pedir cambios» y «Descargar PDF». Ver el servidor MCP.
