Vista previa de una nota de crédito (sin timbrar)
Desde la v1.54.0, valida una nota de crédito 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/credit_notes y corre todas sus validaciones, incluidas las de sobre-crédito y anticipos. Responde los totales, los datos del CFDI 4.0 de egreso 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.
Las validaciones son las mismas que al timbrar porque las dos rutas comparten el mismo código: una nota que excede lo que queda por acreditar de la factura responde el mismo 400 con subcode over_credit, y una nota 07 que pasa del anticipo pendiente responde over_apply_anticipo.
Es opcional: POST /v1/credit_notes no la exige. No pide Idempotency-Key, no consume timbre ni saldo, no incrementa el folio del emisor, no cuenta para el monto acreditado de la factura y no crea ningún recurso. Para timbrar lo que se aprobó, manda el mismo cuerpo a POST /v1/credit_notes con tu Idempotency-Key.
serie es la del cuerpo o NC. folio es el del cuerpo o, si no lo mandas, el siguiente folio del emisor (folioIsProjected: true): puede cambiar si se timbran otros documentos antes. fecha es la hora de la vista previa, salvo que el cuerpo traiga una.
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/credit_notes/preview \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"merchantId": "mkq2f8v3x1t7p9d4n6c0b5rz",
"relatedInvoiceId": "inv7k3q9x2m4v1t8p6d0n5cb",
"tipoRelacion": "03",
"formaPago": "03",
"items": [
{
"productCode": "43201808",
"unitCode": "H87",
"description": "Devolución: teclado mecánico 75%",
"quantity": 1,
"unitPrice": 2500,
"ivaRate": 0.16
}
],
"pricesIncludeTax": false
}'Respuesta
{
"object": "credit_note_preview",
"livemode": false,
"merchantId": "mkq2f8v3x1t7p9d4n6c0b5rz",
"emisor": { "rfc": "EKU9003173C9", "name": "ESCUELA KEMPER URGATE" },
"tipoRelacion": "03",
"relatedUuid": "5fb2822e-396d-4725-8521-cdc4bdd20ccf",
"relatedInvoiceId": "inv7k3q9x2m4v1t8p6d0n5cb",
"serie": "NC",
"folio": "54",
"folioIsProjected": true,
"fecha": "2026-11-18T10:15:00",
"formaPago": "03",
"usoCfdi": "G02",
"currency": "MXN",
"exchangeRate": 1,
"subtotal": 2500,
"discount": 0,
"total": 2900,
"receiver": {
"rfc": "XIA190128J61",
"nombre": "XENON INDUSTRIAL ARTICLES",
"domicilioFiscal": "01160",
"regimenFiscal": "601"
},
"cfdi": { "Version": "4.0", "TipoDeComprobante": "E", "...": "recortado" },
"html": "<!DOCTYPE html>…"
}Errores
| Status | code | Cuándo aparece |
|---|---|---|
| 400 | validation_error | El mismo cuerpo lo rechazaría POST /v1/credit_notes: mismo detail, subcode y errors que el timbrado. Incluye over_credit (la nota excede lo que queda por acreditar de la factura), anticipo_rules y over_apply_anticipo, una factura relacionada que no está timbrada o es de otro emisor, un emisor archivado o sin CSD, y una nota que 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 emisor o la factura relacionada no existen 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
- 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_credit_note, con la misma tarjeta que la factura: «Autorizar y timbrar» (llamacreate_credit_note), «Pedir cambios» y «Descargar PDF». Ver el servidor MCP.
