Documentación / API / Facturas

Vista previa de una factura (sin timbrar)

POSThttps://api.cfdi.express/v1/invoices/previewAPI key

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

Factura y complemento de pago con vista previa en Claude | CFDI Express API · 3:49 · YouTube
Autenticación
Authorization: Bearer sk_test_... | sk_live_...

El header x-account-id indica la cuenta. Si no eres miembro, la respuesta es 403.

Ejemplos

cURL
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

200 OK
{
  "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

StatuscodeCuándo aparece
400validation_errorEl 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.
401unauthorizedFalta el header Authorization o la llave es inválida.
403forbiddenNo eres miembro de la cuenta del header x-account-id.
404not_foundEl merchantId no existe en tu cuenta.
429rate_limitedExcediste el límite de requests por minuto de tu cuenta (300 por default). La respuesta incluye Retry-After.

Notas

  • receiver viene como se timbra: rfc, nombre, domicilioFiscal y regimenFiscal (más residenciaFiscal y numRegIdTrib si aplican). En una factura global, nombre es PUBLICO 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.

Continuar