Emitir una nota de crédito
Una nota modifica un comprobante ya aceptado por SUNAT. La nota de crédito disminuye o anula el monto (devoluciones, anulaciones, rebajas) o reprograma el cronograma de cuotas; la nota de débito lo aumenta (intereses, penalidades). La nota hereda el cliente y la moneda del comprobante afectado y se envía a SUNAT igual que una factura o boleta (Estados).
Método: POST
Endpoint
Sección titulada «Endpoint»POST https://faktura-test.cgallardo.me/v1/credit-notesPOST https://faktura.cgallardo.me/v1/credit-notesCabeceras
Sección titulada «Cabeceras»| Cabecera | Obligatoria | Descripción |
|---|---|---|
Authorization |
Sí | Bearer <api key> (sk_test_ en pruebas, sk_live_ en producción). |
Content-Type |
Sí | application/json |
Idempotency-Key |
Recomendada | Evita duplicar la nota si reintentas (Idempotencia). |
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
affected_document_id |
UUID | Sí | id del comprobante que se modifica. Debe estar accepted u observed y no estar anulado. |
series |
texto | Sí | Serie de nota creada para tu empresa. Debe empezar con la misma letra que el comprobante: F para facturas (FC01) y B para boletas (BC01). |
reason_code |
texto | Sí | Motivo SUNAT, de 2 dígitos (catálogo 09; ver la tabla abajo). |
reason_description |
texto | No | Sustento, hasta 250 caracteres. Por defecto, la descripción oficial del motivo. |
price_includes_tax |
booleano | No | Igual que al emitir: true por defecto. |
issue_date |
fecha | No | Igual que al emitir: hasta 3 días atrás y nunca antes de la fecha del comprobante afectado (NoteIssuedBeforeAffected). |
items |
lista | Según el motivo | En los motivos 01, 02, 03 y 06 puedes omitirlos y se copian los del comprobante; en 04, 05, 07, 08, 09 y 10 son obligatorios; en 13 no se admiten. |
items[].description |
texto | Sí (en ítems) | Descripción del ítem, hasta 500 caracteres. |
items[].quantity |
número o texto | Sí (en ítems) | Cantidad mayor que 0, hasta 10 decimales. |
items[].unit_price |
número o texto | Sí (en ítems) | Precio unitario mayor que 0, hasta 10 decimales. |
items[].igv_type |
texto | No | gravado (por defecto), exonerado, inafecto, gratuito, gratuito_exonerado o gratuito_inafecto. |
items[].icbper |
booleano | No | true si el ítem devuelto corresponde a una bolsa plástica. |
items[].unit_code |
texto | No | Unidad de medida (NIU por defecto). |
items[].product_code |
texto | No | Tu código interno, hasta 30 caracteres. |
items[].sunat_product_code |
texto | No | Código de producto SUNAT (catálogo 25, UNSPSC) de 8 dígitos. |
payment |
objeto | Solo motivo 13 |
Nuevo cronograma: {"type": "credito", "installments": [{"amount": 100, "due_date": "2026-12-15"}]}. |
Motivos admitidos (catálogo 09)
Sección titulada «Motivos admitidos (catálogo 09)»reason_code |
Motivo | items |
|---|---|---|
01 |
Anulación de la operación | Opcional: sin ítems copia el comprobante completo |
02 |
Anulación por error en el RUC | Opcional: sin ítems copia el comprobante completo |
03 |
Corrección por error en la descripción | Opcional: sin ítems copia el comprobante completo |
04 |
Descuento global | Obligatorio |
05 |
Descuento por ítem | Obligatorio |
06 |
Devolución total | Opcional: sin ítems copia el comprobante completo |
07 |
Devolución por ítem | Obligatorio |
08 |
Bonificación | Obligatorio |
09 |
Disminución en el valor | Obligatorio |
10 |
Otros conceptos | Obligatorio |
13 |
Ajustes: montos y/o fechas de pago | No admite ítems: va con payment |
Una nota de crédito no puede superar el total del comprobante (CreditNoteExceedsAffectedTotal), y las notas que rebajan el monto (todas menos la 03 y la 13) no pueden sumar, entre todas, más que el comprobante (CreditNotesExceedAffectedTotal): por ejemplo, no se anula dos veces la misma factura. No se admiten los motivos de exportación (11) ni IVAP (12).
Motivo 13: cambiar el cronograma de una factura al crédito
Sección titulada «Motivo 13: cambiar el cronograma de una factura al crédito»Corrige el monto neto pendiente, las fechas o las cuotas de una factura al crédito. La nota va en cero (una línea informativa «AJUSTE DE MONTOS Y/O FECHAS DE PAGO») y lleva el nuevo cronograma; las cuotas no pueden sumar más que el neto pendiente del comprobante.
{ "affected_document_id": "01a1d5fd-…", "series": "FC01", "reason_code": "13", "payment": { "type": "credito", "installments": [ { "amount": 590, "due_date": "2026-12-15" }, { "amount": 590, "due_date": "2027-01-15" } ] }}Errores propios: PaymentAdjustmentRequiresCreditInvoice (la factura no es al crédito), PaymentAdjustmentRequiresInstallments, NoteItemsNotAllowed, InstallmentsExceedPendingAmount y PaymentOnlyForAdjustmentNotes (cronograma en otro motivo).
Flujo recomendado
Sección titulada «Flujo recomendado»- Comprueba que el comprobante esté
accepteduobservedconGET /v1/documents/{id}. - Elige el motivo:
01para anular toda la operación,07para una devolución parcial,04para un descuento posterior. - Elige la serie de nota de la misma letra que el comprobante:
FC01para facturas,BC01para boletas. - Emite
POST /v1/credit-notescon unaIdempotency-Keyy guarda elidde la nota. - Confirma con SUNAT igual que una factura: webhook o
GET /v1/documents/{id}de la nota.
Ejemplo: anular una factura con nota de crédito
Sección titulada «Ejemplo: anular una factura con nota de crédito»Anula por completo la factura F001-1 del ejemplo de facturas, de S/ 129.00:
curl -X POST https://faktura-test.cgallardo.me/v1/credit-notes \ -H "Authorization: Bearer sk_test_..." \ -H "Content-Type: application/json" \ -d '{ "affected_document_id": "01a1d60a-7aa5-735b-9cf0-94b9d58a67ac", "series": "FC01", "reason_code": "01" }'use Illuminate\Support\Facades\Http;
$response = Http::withToken('sk_test_...') ->post('https://faktura-test.cgallardo.me/v1/credit-notes', [ 'affected_document_id' => '01a1d60a-7aa5-735b-9cf0-94b9d58a67ac', 'series' => 'FC01', 'reason_code' => '01', ]);
$data = $response->json();const response = await fetch('https://faktura-test.cgallardo.me/v1/credit-notes', { method: 'POST', headers: { Authorization: 'Bearer sk_test_...', 'Content-Type': 'application/json', }, body: JSON.stringify({ affected_document_id: '01a1d60a-7aa5-735b-9cf0-94b9d58a67ac', series: 'FC01', reason_code: '01', }),});const data = await response.json();Respuesta 201 Created: un comprobante con document_type: "07" y el bloque note:
{ "document_type": "07", "full_number": "FC01-1", "status": "pending", "totals": { "taxed": "100.00", "exempt": "11.00", "unaffected": "0.00", "free": "0.00", "igv": "18.00", "icbper": "0.00", "total_taxes": "18.00", "discounts": "0.00", "charges": "0.00", "total": "129.00" }, "note": { "reason_code": "01", "reason_description": "ANULACION DE LA OPERACION", "affected_document": { "id": "01a1d60a-7aa5-735b-9cf0-94b9d58a67ac", "document_type": "01", "full_number": "F001-1" } }}¿Nota de crédito o anulación?
Sección titulada «¿Nota de crédito o anulación?»| Situación | Usa |
|---|---|
| El comprobante tiene un error y está dentro del plazo de anulación | Anulación |
| Pasó el plazo de anulación, o el cliente devuelve todo o parte | Nota de crédito |
| Hay que cobrar algo adicional sobre una venta ya emitida | Nota de débito |
Más casos (devolución parcial, descuento posterior, nota a una boleta) en los ejemplos de notas y anulaciones.
Respuestas y errores
Sección titulada «Respuestas y errores»| Estado | reason |
Significado |
|---|---|---|
201 |
— | Nota de crédito creada, firmada y encolada para SUNAT (status: "pending"). |
200 |
— | Petición repetida con la misma Idempotency-Key y el mismo cuerpo (Idempotent-Replayed: true). |
401 |
Unauthenticated |
Falta la API key, es inválida o venció. |
403 |
ApiKeyScopeInsufficient, EmitterInactive |
La clave es de solo consulta (lookup) o la empresa está desactivada. |
409 |
AffectedDocumentNotAccepted, AffectedDocumentVoided, IdempotencyKeyReused, EmitterNotReadyForProduction, CertificateExpired |
El comprobante afectado aún no fue aceptado por SUNAT, está anulado, o se reutilizó Idempotency-Key con otro cuerpo. |
422 |
AffectedDocumentNotFound, InvalidAffectedDocument, InvalidNoteReason, NoteSeriesMismatch, NoteItemsRequired, CreditNoteExceedsAffectedTotal, CreditNotesExceedAffectedTotal |
Error de validación o regla de negocio. Ver todos en Errores de notas. |
429 |
TooManyRequests |
Superaste las 120 peticiones por minuto. |