Ir al contenido

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

POST https://faktura-test.cgallardo.me/v1/debit-notes
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.

reason_code Motivo
01 Intereses por mora
02 Aumento en el valor
03 Penalidades / otros conceptos
Ventana de terminal
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 } ]
}'

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"
}
}
}
  1. Comprueba que el comprobante original esté accepted u observed con GET /v1/documents/{id}.
  2. Elige el motivo del catálogo 10 (01 intereses por mora, 02 aumento en el valor, 03 penalidades) y la serie que corresponda a la letra del comprobante (FD01 para facturas, BD01 para boletas).
  3. Emite POST /v1/debit-notes con Idempotency-Key y los items que detallan el cargo adicional.
  4. 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.

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.