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

> `POST https://api.cfdi.express/v1/credit_notes` — Timbra un CFDI 4.0 de egreso para una devolución, un reembolso o un descuento posterior a la factura.

URL de esta página: https://cfdi.express/docs/api/crear-nota-de-credito
Autenticación: requiere API key (`Authorization: Bearer sk_test_…` o `sk_live_…`)
Idempotencia: requiere el header `Idempotency-Key`.

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}](https://cfdi.express/docs/api/obtener-factura) 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`.

### Headers

| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| `Idempotency-Key` | string | sí | Llave única por devolución. Los replays devuelven la nota original. |

### Cuerpo (JSON)

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

## Ejemplos

### cURL — devolución de una factura timbrada aquí

```bash
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

```bash
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

```json
{
  "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](https://cfdi.express/docs/api/cancelar-factura).

## Relacionados

- [POST /v1/invoices](https://cfdi.express/docs/api/timbrar-factura) — Timbrar factura
- [GET /v1/invoices/{id}](https://cfdi.express/docs/api/obtener-factura) — Obtener factura
- [POST /v1/invoices/{id}/cancel](https://cfdi.express/docs/api/cancelar-factura) — Cancelar factura

---

Referencia completa: https://cfdi.express/docs/api · OpenAPI: https://api.cfdi.express/openapi.json · Llaves: https://dash.cfdi.express