Emitir nota de débito
POST /api/documents/{document_id}/debit-note
Autenticación: Bearer del usuario del tenant (Authorization: Bearer <api_token>).
Emite una nota de débito (08) sobre una factura o boleta aceptada para cobrar intereses, un aumento de valor u otros cargos posteriores. Sale por el mismo proceso que Emitir comprobante electrónico. No mueve stock.
Quién puede usarlo: cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde 403.
Formato de respuesta: estándar {success, data, message?} (registro único). Responde 201 al registrar la nota.
Parámetros de la ruta:
| Campo | Tipo | Obligatorio | Descripción / valores permitidos |
|---|---|---|---|
id |
integer | Sí | Id interno del comprobante ({document_id}). |
Cuerpo (JSON):
| Campo | Tipo | Obligatorio | Descripción / valores permitidos |
|---|---|---|---|
note_type |
string | Sí | Código del catálogo 10 (débito), activo en la empresa. Ver la tabla de tipos. |
description |
string (máx. 500) | Sí | Motivo o sustento de la nota (sale en el XML y el PDF). |
series |
string (4) | No | Serie de la nota del establecimiento del comprobante (FD.. / BD..): las notas de una factura usan series que empiezan con F y las de una boleta con B. Si no la envías se usa la primera disponible. |
date_of_issue |
string Y-m-d |
No | Fecha de la nota. Por defecto hoy. No puede ser anterior a la del comprobante ni futura. |
items |
array | No | Sin items: nota total con todas las líneas del comprobante. Con items: solo esas líneas. |
items[].line_id |
integer | Uno de los dos | Id de la línea del comprobante (items[].line_id de Notas de un comprobante). |
items[].item_id |
integer | Uno de los dos | Id del producto. Si el producto está en varias líneas, usa line_id. |
items[].quantity |
numeric > 0 | Sí | Cantidad (en la misma unidad o presentación de la línea). |
items[].unit_price |
numeric > 0 | No | Precio unitario con IGV. Por defecto el de la línea. Para intereses o aumentos es el importe a cobrar por unidad. |
actions.send_xml_signed |
boolean | No | Enviar a SUNAT al emitir si la empresa tiene el envío automático activo. Por defecto true. |
actions.send_email |
boolean | No | Enviar la nota por correo al cliente. Por defecto false. |
actions.format_pdf |
string | No | a4 (por defecto), a5, ticket, ticket_58 o ticket_50. |
Tipos de nota de débito (note_type, catálogo 10 de SUNAT):
| Código | Tipo | Cuándo usarlo | Por la API |
|---|---|---|---|
01 |
Intereses por mora | El cliente pagó tarde y se le cobran intereses. | Sí |
02 |
Aumento en el valor | Se cobra un mayor valor posterior a la venta. | Sí |
03 |
Otros conceptos | Otros cargos posteriores. | Sí |
10 |
Ajustes de operaciones de exportación | Solo exportaciones. | Sí |
11 |
Ajustes afectos al IVAP | Solo operaciones con IVAP. | Sí |
13 |
Penalidades | Penalidad al cliente (operación inafecta). | No (422): emítela desde el sistema web. |
Los tipos activos de tu empresa los da Catálogos → Tipos de nota de débito (catalogs/debit-note-types). Una nota de débito no mueve stock.
Respuesta 201: data.id (id de la nota), data.number (serie-número), data.state_type_id, data.external_id (para consultar o enviar la nota), data.total, data.affected_document (comprobante modificado), data.links (xml, pdf y cdr si ya fue enviada) y data.response (respuesta de SUNAT si se envió).
Reglas:
- Solo sobre facturas y boletas aceptadas (
05); nunca sobre otra nota. Ver la tabla de estados. - No se emite si el comprobante ya tiene una nota de crédito de anulación (
01) aceptada. - Si el comprobante tiene descuentos, cargos o anticipos, la nota se emite desde el sistema web (que reparte esos importes en las líneas): responde
409. - Las líneas parciales solo admiten operaciones onerosas (gravado
10, exonerado20, inafecto30, exportación40) sin ISC ni ICBPER; para líneas gratuitas o con esos tributos emite la nota total. - Un producto vendido con series o lotes solo admite la cantidad completa de su línea.
- La nota usa el cliente, la moneda y el tipo de cambio del comprobante y queda en estado
01(o05si se envió y SUNAT la aceptó). Si no se envía al emitir, envíala con Enviar comprobante a SUNAT (documents/send, con suexternal_id). - Un vendedor solo emite notas sobre sus comprobantes (
403en los de otro vendedor). - Sin
itemsla nota repite todas las líneas del comprobante con sus importes: para intereses o aumentos envíaitemscon el importe a cobrar (unit_pricecon IGV).
Errores:
403si el comprobante es de otro vendedor.404si el comprobante no existe.409si el comprobante no está aceptado (05), es una nota, ya fue anulado con una nota de crédito01aceptada, tiene descuentos/cargos/anticipos o falta el certificado digital.422{success: false, message}si falta el motivo, el tipo no existe o es13(penalidades), la serie no corresponde, la fecha no es válida o una línea no es del comprobante.401sin token o con un token inválido.
Parámetros
| Parámetro | Dónde | Obligatorio | Ejemplo | Descripción |
|---|---|---|---|---|
document_id |
ruta | sí | 1 |
Cuerpo
Content-Type: application/json
{
"note_type": "01",
"description": "Intereses por pago fuera de plazo",
"items": [
{
"line_id": "1",
"quantity": 1,
"unit_price": 5.9
}
],
"actions": {
"send_xml_signed": true
}
}
Respuestas
201 — Intereses
{
"success": true,
"data": {
"id": 1534,
"number": "FD01-3",
"document_type_id": "08",
"state_type_id": "01",
"state_type_description": "Registrado",
"external_id": "0f3e2a77-8d1b-4b0e-b1c8-5d2f6a9e3c44",
"filename": "20123456789-08-FD01-3",
"hash": "Wc1p8mB2tE7zK0yQ4nR6vS3aD5f=",
"date_of_issue": "2026-11-07",
"currency_type_id": "PEN",
"total": 5.9,
"links": {
"xml": "https://empresa.dominio/downloads/document/xml/0f3e2a77-8d1b-4b0e-b1c8-5d2f6a9e3c44",
"pdf": "https://empresa.dominio/downloads/document/pdf/0f3e2a77-8d1b-4b0e-b1c8-5d2f6a9e3c44",
"cdr": ""
},
"affected_document": {
"id": 1520,
"number": "F001-310",
"external_id": "9b1c6c1e-5e63-4d7c-9a51-7d3c2b1f0a11"
},
"note_type": "01",
"response": []
},
"message": "Nota de débito FD01-3 registrada."
}
403 — Registro de otro vendedor
{
"success": false,
"message": "No tienes permiso para acceder a este registro."
}
404 — No existe
{
"success": false,
"message": "Registro no encontrado."
}
409 — No aceptado
{
"success": false,
"message": "El comprobante fue enviado a SUNAT y espera su respuesta: emite la nota cuando esté aceptado."
}
422 — Penalidad
{
"success": false,
"message": "La nota de débito tipo 13 (penalidades) no se emite por la API: emítela desde el sistema web."
}
422 — Sin motivo
{
"success": false,
"message": "Indica el motivo o sustento de la nota (description)."
}
Pruébalo
Prueba este endpoint con tu empresa y tu token: elige la URL en Servers, pega el token en Authorize y haz clic en Try it out.