Emitir una nota de débito
La nota de débito aumenta el monto de un comprobante ya aceptado por SUNAT: intereses por mora, aumentos de valor o penalidades. 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/debit-notesPOST https://faktura.cgallardo.me/v1/debit-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 de débito creada para tu empresa. Debe empezar con la misma letra que el comprobante: F para facturas (FD01) y B para boletas (BD01). |
reason_code |
texto | Sí | Motivo SUNAT, de 2 dígitos (catálogo 10; 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 (unit_price incluye IGV). |
issue_date |
fecha | No | Igual que al emitir: hoy (por defecto) o hasta 3 días atrás, nunca antes de la fecha del comprobante afectado (NoteIssuedBeforeAffected). |
items |
lista | Sí | Entre 1 y 500 ítems con el cargo adicional; en las notas de débito siempre son obligatorios (NoteItemsRequired). |
items[].description |
texto | Sí | Descripción del interés, aumento de valor o penalidad, hasta 500 caracteres. |
items[].quantity |
número o texto | Sí | Cantidad mayor que 0, hasta 10 decimales. |
items[].unit_price |
número o texto | Sí | 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 corresponde a bolsas plásticas. |
items[].unit_code |
texto | No | Unidad de medida (NIU por defecto, ZZ para servicios). |
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. |
En las notas de débito no se admiten descuentos ni el bloque payment.
Motivos admitidos (catálogo 10)
Sección titulada «Motivos admitidos (catálogo 10)»reason_code |
Motivo |
|---|---|
01 |
Intereses por mora |
02 |
Aumento en el valor |
03 |
Penalidades / otros conceptos |
Ejemplo: nota de débito por intereses
Sección titulada «Ejemplo: nota de débito por intereses»curl -X POST https://faktura-test.cgallardo.me/v1/debit-notes \ -H "Authorization: Bearer sk_test_..." \ -H "Content-Type: application/json" \ -d '{ "affected_document_id": "01a1d60a-7aa5-735b-9cf0-94b9d58a67ac", "series": "FD01", "reason_code": "01", "items": [ { "description": "Intereses por mora", "quantity": 1, "unit_price": 11.80 } ] }'use Illuminate\Support\Facades\Http;
$response = Http::withToken('sk_test_...') ->post('https://faktura-test.cgallardo.me/v1/debit-notes', [ 'affected_document_id' => '01a1d60a-7aa5-735b-9cf0-94b9d58a67ac', 'series' => 'FD01', 'reason_code' => '01', 'items' => [ [ 'description' => 'Intereses por mora', 'quantity' => 1, 'unit_price' => 11.80, ], ], ]);
$data = $response->json();const response = await fetch('https://faktura-test.cgallardo.me/v1/debit-notes', { method: 'POST', headers: { Authorization: 'Bearer sk_test_...', 'Content-Type': 'application/json', }, body: JSON.stringify({ affected_document_id: '01a1d60a-7aa5-735b-9cf0-94b9d58a67ac', series: 'FD01', reason_code: '01', items: [{ description: 'Intereses por mora', quantity: 1, unit_price: 11.80 }], }),});const data = await response.json();Respuesta 201 Created
Sección titulada «Respuesta 201 Created»Devuelve el comprobante con document_type: "08" y el bloque note:
{ "document_type": "08", "full_number": "FD01-1", "status": "pending", "totals": { "taxed": "10.00", "exempt": "0.00", "unaffected": "0.00", "free": "0.00", "igv": "1.80", "icbper": "0.00", "total_taxes": "1.80", "discounts": "0.00", "charges": "0.00", "total": "11.80" }, "note": { "reason_code": "01", "reason_description": "INTERESES POR MORA", "affected_document": { "id": "01a1d60a-7aa5-735b-9cf0-94b9d58a67ac", "document_type": "01", "full_number": "F001-1" } }}Flujo recomendado
Sección titulada «Flujo recomendado»- Comprueba que el comprobante original esté
accepteduobservedconGET /v1/documents/{id}. - Elige el motivo del catálogo 10 (
01intereses por mora,02aumento en el valor,03penalidades) y la serie que corresponda a la letra del comprobante (FD01para facturas,BD01para boletas). - Emite
POST /v1/debit-notesconIdempotency-Keyy lositemsque detallan el cargo adicional. - Confirma la aceptación de SUNAT por webhook o
GET /v1/documents/{id}.
Otro caso, una penalidad contractual, está en los ejemplos de notas y anulaciones.
Respuestas y errores
Sección titulada «Respuestas y errores»| Estado | reason |
Significado |
|---|---|---|
201 |
— | Nota de débito 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 |
Error de validación o regla de negocio. Ver todos en Errores de notas. |
429 |
TooManyRequests |
Superaste las 120 peticiones por minuto. |