Emitir nota de crédito
POST /api/documents/{document_id}/credit-note
Autenticación: Bearer del usuario del tenant (Authorization: Bearer <api_token>).
Emite una nota de crédito (07) sobre una factura o boleta aceptada: anulación, devolución total o por ítem, descuentos o rebajas posteriores. Sale por el mismo proceso que Emitir comprobante electrónico (XML firmado, PDF y envío según la configuración).
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 09 (crédito), 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 (FC.. / BC..): 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). No puede superar la vendida ni, en devoluciones, lo que falta devolver. |
items[].unit_price |
numeric > 0 | No | Precio unitario con IGV. Por defecto el de la línea. No puede superar el de la línea. |
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 crédito (note_type, catálogo 09 de SUNAT):
| Código | Tipo | Cuándo usarlo | Por la API |
|---|---|---|---|
01 |
Anulación de la operación | La venta no se realizó: anula todo el comprobante. | Solo total (sin items) y sin notas previas. Devuelve el stock. |
02 |
Anulación por error en el RUC | El comprobante se emitió a un RUC equivocado (luego emites uno nuevo al correcto). | Solo total. Devuelve el stock. |
03 |
Corrección por error en la descripción | Corregir textos sin cambiar importes. | No (422): emítela desde el sistema web. |
04 |
Descuento global | Descuento posterior sobre el total. | Total o parcial. No mueve stock. |
05 |
Descuento por ítem | Descuento posterior sobre algunas líneas. | Total o parcial. No mueve stock. |
06 |
Devolución total | El cliente devolvió todo. | Solo total y sin notas previas. Devuelve el stock. |
07 |
Devolución por ítem | El cliente devolvió parte de los productos. | Total o parcial. Devuelve el stock de lo devuelto. |
08 |
Bonificación | Bonificación posterior. | Total o parcial. Devuelve el stock. |
09 |
Disminución en el valor | Rebaja de precio posterior a la venta. | Total o parcial. No mueve stock. |
10 |
Otros conceptos | Otros casos. | Total o parcial. Devuelve el stock. |
11 |
Ajustes de operaciones de exportación | Solo exportaciones. | Total o parcial. |
12 |
Ajustes afectos al IVAP | Solo operaciones con IVAP. | Total o parcial. |
13 |
Ajustes – montos y/o fechas de pago | Cambiar cuotas de una venta al crédito. | No (422): emítela desde el sistema web. |
Los tipos activos de tu empresa los da Catálogos → Tipos de nota de crédito (catalogs/credit-note-types).
Estado del comprobante (state_type_id) y qué se puede hacer:
| Estado | Significado | Editar | Nota de crédito / débito |
|---|---|---|---|
01 |
Registrado (aún no enviado a SUNAT) | Sí | No: corrígelo editándolo o envíalo primero |
03 |
Enviado, espera respuesta | No (409) |
No (409): espera la respuesta |
05 |
Aceptado | No (409): usa una nota |
Sí |
07 |
Observado | No (409): usa una nota |
No (409) |
09 |
Rechazado | No (409): emite un comprobante nuevo |
No (409) |
11 |
Anulado | No (409) |
No (409) |
13 |
Por anular | No (409) |
No (409) |
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). - Saldo: el total de la nota más las notas de crédito vigentes no puede superar el total del comprobante (ver Notas de un comprobante).
- Devoluciones: lo devuelto de cada producto (esta nota más las anteriores que reingresaron stock) no puede superar lo vendido.
- Los tipos
01,02y06son por el total: no envíesitems, y solo si el comprobante no tiene notas de crédito previas. - El stock reingresa al almacén de la línea original salvo en los tipos que no devuelven mercadería (
03,04,05,09,13).
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 nota01aceptada, tiene descuentos/cargos/anticipos o falta el certificado digital.422{success: false, message}si falta el motivo, el tipo no existe o no se emite por la API, la serie no corresponde, la fecha no es válida, una línea no es del comprobante, la cantidad o el precio superan lo vendido, o el total supera el saldo.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": "07",
"description": "Devolución parcial: el cliente devolvió 1 gaseosa",
"series": "FC01",
"date_of_issue": "2026-11-07",
"items": [
{
"line_id": "1",
"quantity": 1
}
],
"actions": {
"send_xml_signed": true,
"send_email": false,
"format_pdf": "a4"
}
}
Respuestas
201 — Nota total (anulación)
{
"success": true,
"data": {
"id": 1533,
"number": "BC01-12",
"document_type_id": "07",
"state_type_id": "01",
"state_type_description": "Registrado",
"external_id": "0f3e2a77-8d1b-4b0e-b1c8-5d2f6a9e3c44",
"filename": "20123456789-07-BC01-12",
"hash": "Wc1p8mB2tE7zK0yQ4nR6vS3aD5f=",
"date_of_issue": "2026-11-07",
"currency_type_id": "PEN",
"total": 60.0,
"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": "B001-245",
"external_id": "9b1c6c1e-5e63-4d7c-9a51-7d3c2b1f0a11"
},
"note_type": "01",
"response": []
},
"message": "Nota de crédito BC01-12 registrada."
}
201 — Devolución parcial
{
"success": true,
"data": {
"id": 1533,
"number": "FC01-13",
"document_type_id": "07",
"state_type_id": "01",
"state_type_description": "Registrado",
"external_id": "0f3e2a77-8d1b-4b0e-b1c8-5d2f6a9e3c44",
"filename": "20123456789-07-BC01-12",
"hash": "Wc1p8mB2tE7zK0yQ4nR6vS3aD5f=",
"date_of_issue": "2026-11-07",
"currency_type_id": "PEN",
"total": 15.0,
"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": "07",
"response": []
},
"message": "Nota de crédito FC01-13 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 aún no fue enviado a SUNAT (estado Registrado): no admite notas. Si tiene errores, edítalo; si está bien, envíalo y espera que sea aceptado."
}
409 — Rechazado
{
"success": false,
"message": "El comprobante fue rechazado por SUNAT y no admite notas: emite un comprobante nuevo."
}
409 — Ya anulado
{
"success": false,
"message": "El comprobante ya fue anulado con la nota de crédito BC01-12: no admite más notas."
}
422 — Supera el saldo
{
"success": false,
"message": "El total de la nota (30) supera el saldo disponible del comprobante (25)."
}
422 — Supera lo vendido
{
"success": false,
"message": "La cantidad a devolver de \"GASEOSA 500 ML\" (2) supera lo que queda por devolver (1)."
}
422 — Serie no corresponde
{
"success": false,
"message": "La serie FC01 no es una serie de nota de crédito del establecimiento del comprobante que empiece con B (las notas de una boleta usan series B)."
}
422 — Tipo total con items
{
"success": false,
"message": "La nota de crédito tipo 06 es por el total del comprobante: no envíes items."
}
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.