Timbrar una nota de crédito (CFDI de egreso)

POSThttps://api.cfdi.express/v1/credit_notesAPI keyIdempotency-Key

Timbra un CFDI 4.0 de egreso para una devolución, un reembolso o un descuento posterior a la factura.

Relaciona la nota con la factura original de dos formas: con relatedInvoiceId si el CFDI de ingreso se timbró aquí (el receptor se copia solo), o con relatedUuid si se timbró en otro sistema (en ese caso el receiver es obligatorio).

El resultado es un recurso invoice con kind: "credit_note": lo consultas con GET /v1/invoices/{id} y lo listas con GET /v1/invoices?kind=credit_note.

Igual que el timbrado de facturas, espera hasta 20 segundos por el UUID y requiere Idempotency-Key.

Autenticación

Authorization: Bearer sk_test_... | sk_live_...

Parámetros

Headers

Campo	Tipo	Descripción
Idempotency-Keyreq	string	Llave única por devolución. Los replays devuelven la nota original.

Cuerpo (JSON)

Campo	Tipo	Descripción
merchantIdreq	string	Emisor de la nota. Debe ser el mismo que timbró la factura relacionada.
relatedInvoiceId	string	Id de la factura de ingreso timbrada aquí. Usa este o relatedUuid.
relatedUuid	string	UUID de un CFDI de ingreso timbrado fuera de esta API. Exige receiver explícito.
tipoRelacion	string	01 nota de crédito de los documentos relacionados (default) o 03 devolución de mercancía.
usoCfdi	string	Default G02 (devoluciones, descuentos o bonificaciones).
formaPagoreq	string	Cómo se devuelve el dinero (03 transferencia, 01 efectivo…). Usa 15 condonación o 99 cuando no hay movimiento de dinero.
folio	string	Folio visible, por ejemplo tu número de devolución (RET-1001).
receiver	object	Receptor (rfc, name, zip, regimenFiscal). Se hereda de la factura relacionada cuando usas relatedInvoiceId.
items[]req	array	La mercancía devuelta, o un solo concepto por el monto acreditado. Misma forma que en facturas.
pricesIncludeTax	boolean	true por default.

Ejemplos

cURL — devolución de una factura timbrada aquí

curl -X POST https://api.cfdi.express/v1/credit_notes \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: return_1001" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "mkq2f8v3x1t7p9d4n6c0b5rz",
    "relatedInvoiceId": "inv7k3q9x2m4v1t8p6d0n5cb",
    "tipoRelacion": "03",
    "formaPago": "03",
    "folio": "RET-1001",
    "items": [
      {
        "productCode": "43201808",
        "unitCode": "H87",
        "description": "Teclado mecánico 75% (devolución)",
        "quantity": 1,
        "unitPrice": 1740.00
      }
    ]
  }'

cURL — CFDI externo por UUID

curl -X POST https://api.cfdi.express/v1/credit_notes \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: return_ext_88" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "mkq2f8v3x1t7p9d4n6c0b5rz",
    "relatedUuid": "9f1b2c3d-4e5f-4a6b-8c9d-0e1f2a3b4c5d",
    "tipoRelacion": "01",
    "formaPago": "99",
    "receiver": {
      "rfc": "XIA190128J61",
      "name": "XENON INDUSTRIAL ARTICLES",
      "zip": "01160",
      "regimenFiscal": "601"
    },
    "items": [
      {
        "productCode": "01010101",
        "unitCode": "ACT",
        "description": "Bonificación comercial",
        "quantity": 1,
        "unitPrice": 500.00
      }
    ]
  }'

Respuesta

201 Created

{
  "id": "cnt4m9x2q7v1p8d3t6n0c5br",
  "object": "invoice",
  "livemode": false,
  "status": "stamped",
  "kind": "credit_note",
  "uuid": "2b7d5a11-93c4-4f0e-b6a8-77c1e9d43f10",
  "serie": "A",
  "folio": 129,
  "folioText": "RET-1001",
  "metodoPago": "PUE",
  "formaPago": "03",
  "usoCfdi": "G02",
  "currency": "MXN",
  "subtotal": 1500.00,
  "discount": 0,
  "total": 1740.00,
  "saldoPendiente": null,
  "tipoRelacion": "03",
  "relatedUuid": "9f1b2c3d-4e5f-4a6b-8c9d-0e1f2a3b4c5d",
  "relatedInvoiceId": "inv7k3q9x2m4v1t8p6d0n5cb",
  "receiver": {
    "rfc": "XIA190128J61",
    "name": "XENON INDUSTRIAL ARTICLES",
    "zip": "01160",
    "regimenFiscal": "601"
  },
  "merchantId": "mkq2f8v3x1t7p9d4n6c0b5rz",
  "files": { "status": "ready" },
  "cancellation": null,
  "stampedAt": "2026-08-18T18:15:02.441Z",
  "createdAt": "2026-08-18T18:15:00.902Z"
}

Errores

Status	code	Cuándo aparece
400	validation_error	Faltan relatedInvoiceId y relatedUuid, el receptor no viene con relatedUuid, o algún concepto es inválido.
401	unauthorized	Falta el header Authorization o la llave es inválida.
402	insufficient_credits	No hay saldo suficiente para el timbre.
404	not_found	El emisor o la factura relacionada no existen.
409	request_in_flight	Otra petición con el mismo Idempotency-Key está en proceso.
422	sat_rejected	El SAT rechazó la nota de crédito.
503	pac_unavailable	El PAC no está disponible.

Notas

Una nota de crédito no cancela la factura: la corrige contablemente. Si lo que quieres es anular el comprobante, usa la cancelación.

Continuar

POSTTimbrar factura GETObtener factura POSTCancelar factura