Saltar al contenido
Facturador

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, exonerado 20, inafecto 30, exportación 40) 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 (o 05 si se envió y SUNAT la aceptó). Si no se envía al emitir, envíala con Enviar comprobante a SUNAT (documents/send, con su external_id).
  • Un vendedor solo emite notas sobre sus comprobantes (403 en los de otro vendedor).
  • Sin items la nota repite todas las líneas del comprobante con sus importes: para intereses o aumentos envía items con el importe a cobrar (unit_price con IGV).

Errores:

  • 403 si el comprobante es de otro vendedor.
  • 404 si el comprobante no existe.
  • 409 si el comprobante no está aceptado (05), es una nota, ya fue anulado con una nota de crédito 01 aceptada, tiene descuentos/cargos/anticipos o falta el certificado digital.
  • 422 {success: false, message} si falta el motivo, el tipo no existe o es 13 (penalidades), la serie no corresponde, la fecha no es válida o una línea no es del comprobante.
  • 401 sin 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.