Documentación / API / Facturas

Vista previa de una factura en PDF

POSThttps://api.cfdi.express/v1/invoices/preview/pdfAPI key

Desde la v1.53.0, la misma vista previa en PDF: plantilla del PDF timbrado, marca de agua PREVIEW y sin UUID, sellos ni QR. No timbra ni cobra.

Mismo cuerpo y mismas validaciones que POST /v1/invoices/preview.

Con delivery=file (el default) responde el PDF con Content-Type: application/pdf, Cache-Control: no-store y Content-Disposition: attachment. El archivo se llama Vista previa factura {serie} {folio}.pdf, por ejemplo Vista previa factura A 53.pdf.

Con delivery=url sube el PDF y responde JSON con una liga firmada que vence en 15 minutos. Es el único caso en que se guarda algo: el PDF temporal de la liga.

Autenticación
Authorization: Bearer sk_test_... | sk_live_...

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

Parámetros

Query string

CampoTipoDescripción
deliverystringfile (default): el PDF. url: JSON con una liga temporal de descarga.

Ejemplos

cURL — guardar el PDF
curl -X POST "https://api.cfdi.express/v1/invoices/preview/pdf" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d @factura.json \
  -o "vista-previa.pdf"
cURL — liga temporal
curl -X POST "https://api.cfdi.express/v1/invoices/preview/pdf?delivery=url" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d @factura.json

Respuesta

200 OK (delivery=url)
{
  "object": "invoice_preview_pdf",
  "filename": "Vista previa factura A 53.pdf",
  "url": "https://files.cfdi.express/previews/...pdf?X-Amz-Expires=900&...",
  "expiresAt": "2026-11-17T17:45:00.000Z"
}

Errores

StatuscodeCuándo aparece
400validation_errorEl mismo cuerpo lo rechazaría POST /v1/invoices, o delivery no es file ni url.
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.
503pdf_unavailableEl generador de PDF no está disponible, o el almacenamiento no está disponible con delivery=url (usa delivery=file). Reintenta en unos momentos.

Notas

  • El PDF lleva la leyenda «VISTA PREVIA — SIN VALIDEZ FISCAL» y el pie «Vista previa de un CFDI versión 4.0 — no es un comprobante fiscal.». En lugar del UUID dice «Se asigna al timbrar».
  • Por MCP es la herramienta download_invoice_preview_pdf, que solo puede llamar la tarjeta de vista previa (botón «Descargar PDF»), no el modelo.

Continuar