Saltar al contenido
Facturador

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, 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).
  • 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, 02 y 06 son por el total: no envíes items, 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:

  • 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 01 aceptada, 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.
  • 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": "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.