Documentación / API / Notas de crédito

Vista previa de una nota de crédito (sin timbrar)

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

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.

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/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

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

StatuscodeCuándo aparece
400validation_errorEl 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.
401unauthorizedFalta el header Authorization o la llave es inválida.
403forbiddenNo eres miembro de la cuenta del header x-account-id.
404not_foundEl emisor o la factura relacionada no existen en tu cuenta.
429rate_limitedExcediste 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» (llama create_credit_note), «Pedir cambios» y «Descargar PDF». Ver el servidor MCP.

Continuar