---
name: faktura-emitir-una-nota-de-debito
description: "Emitir una nota de débito con la API de Faktura (facturación electrónica SUNAT, Perú). 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 moned… Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Emitir una nota de débito — Faktura API

## Propósito

Le da a tu asistente el contexto para **emitir una nota de débito** con la API de Faktura: 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 moned…

Instalación en Claude Code: guarda este archivo como `.claude/skills/faktura-emitir-una-nota-de-debito/SKILL.md` en tu proyecto. Fuente: https://faktura-doc.cgallardo.me/endpoints/nota-de-debito/

## Modelo mental: de dónde sale cada bloque del JSON

| Bloque / cabecera | De dónde sale |
| --- | --- |
| `Idempotency-Key` (cabecera) | Del identificador único del cargo o nota en tu sistema. |
| `affected_document_id` | Del campo `id` (UUID) de la factura o boleta original (`status: "accepted"` u `"observed"`). |
| `series` | Del endpoint `GET /v1/series`, con la misma letra inicial que el comprobante afectado (`FD01` para facturas, `BD01` para boletas). |
| `reason_code` | Del catálogo 10 de SUNAT incluido en esta skill (`01` intereses por mora, `02` aumento en el valor, `03` penalidades). |
| `items` | Obligatorios en toda nota de débito: las líneas con el interés, aumento de valor o penalidad que se cobra. |

## Endpoint

| Ambiente | Petición |
| --- | --- |
| Pruebas | `POST https://faktura-test.cgallardo.me/v1/debit-notes` |
| Producción | `POST https://faktura.cgallardo.me/v1/debit-notes` |

## Autenticación y cabeceras

- `Authorization: Bearer <api key>`. En pruebas, una clave `sk_test_` (SUNAT beta, sin valor tributario); en producción, la `sk_live_`. El ambiente lo decide la clave.
- `Content-Type: application/json` en las peticiones con cuerpo.
- `Idempotency-Key` (recomendada al emitir): repetir la petición con la misma clave y el mismo cuerpo devuelve el mismo comprobante, sin duplicarlo.
- Errores: JSON `{ "reason": "<código>", "details": [...] }`. `401` clave inválida o vencida, `403` alcance insuficiente, `422` datos inválidos, `429` límite de 120 peticiones por minuto (respeta `Retry-After`), `500` solo con `traceId`.

## Cuerpo

| 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`.

## Motivos admitidos (catálogo 10)

| `reason_code` | Motivo |
| --- | --- |
| `01` | Intereses por mora |
| `02` | Aumento en el valor |
| `03` | Penalidades / otros conceptos |

## Ejemplo: nota de débito por intereses

```bash
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 } ]
  }'
```

## Respuesta `201 Created`

Devuelve el [comprobante](https://faktura-doc.cgallardo.me/endpoints/comprobantes/ver/#el-objeto-comprobante) con `document_type: "08"` y el bloque `note`:

```json
{
  "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"
    }
  }
}
```

## Flujo recomendado

1. **Comprueba** que el comprobante original esté `accepted` u `observed` con [`GET /v1/documents/{id}`](https://faktura-doc.cgallardo.me/endpoints/comprobantes/ver/).
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](https://faktura-doc.cgallardo.me/webhooks/) o [`GET /v1/documents/{id}`](https://faktura-doc.cgallardo.me/endpoints/comprobantes/ver/).

Otro caso, una penalidad contractual, está en los [ejemplos de notas y anulaciones](https://faktura-doc.cgallardo.me/ejemplos/notas-y-anulaciones/#nota-de-débito-por-penalidad).

## Respuestas y errores

| 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](https://faktura-doc.cgallardo.me/errores/#errores-de-notas). |
| `429` | `TooManyRequests` | Superaste las 120 peticiones por minuto. |

## Anexo: El objeto comprobante (de «Ver un comprobante»)

| Campo | Tipo | Descripción |
| --- | --- | --- |
| `id` | UUID | Identificador del comprobante en Faktura. |
| `document_type` | texto | `01` factura, `03` boleta, `07` nota de crédito, `08` nota de débito. |
| `series`, `number`, `full_number` | texto, entero, texto | Serie, correlativo y ambos unidos (`B001-1`). |
| `issue_date` | fecha | Fecha de emisión (hora de Perú). |
| `currency` | texto | `PEN` o `USD`. |
| `igv_percent` | texto | Tasa de IGV aplicada al comprobante (`"18"`). |
| `status` | texto | Estado del envío a SUNAT ([Estados](https://faktura-doc.cgallardo.me/estados-y-envio/)). |
| `customer` | objeto | `doc_type` ([Catálogos](https://faktura-doc.cgallardo.me/catalogos/)), `doc_number` (`-` si es anónimo) y `name`. |
| `totals` | objeto | Montos como texto decimal ([Cálculo de impuestos](https://faktura-doc.cgallardo.me/calculo-de-impuestos/#totales-del-comprobante)). |
| `totals.discounts` | texto | Suma de descuentos sobre la base (por ítem y global). |
| `net_payable` | texto | Neto pendiente de pago: total menos detracción y retención. |
| `service_charge` | objeto o null | `base_amount` y `amount` cuando hay recargo al consumo. |
| `global_discount` | objeto o null | `base_amount` (gravado antes del descuento) y `amount` (descuento sobre la base). |
| `detraction` | objeto o null | `code`, `percent`, `amount` (en soles), `amount_in_document_currency`, `bank_account`, `payment_method`, `exchange_rate`. |
| `retention` | objeto o null | `percent` (`3`), `base_amount` y `amount`. |
| `purchase_order`, `despatch_references`, `observations`, `due_date` | varios | Datos comerciales enviados al emitir. |
| `amount_in_words` | texto | Total en letras (leyenda 1000 de SUNAT). |
| `payment` | objeto | `type` (`contado` o `credito`) e `installments` (`amount`, `due_date`). |
| `items[]` | lista | Por ítem: `product_code`, `sunat_product_code`, `description`, `unit_code`, `quantity`, `unit_value` (sin IGV, antes del descuento), `unit_price` (con IGV, después del descuento), `igv_type`, `discount` (sobre la base), `line_value` (base, ya descontada), `igv`, `icbper`. |
| `sunat.code` | texto o null | Código de respuesta de SUNAT (`0` aceptado). |
| `sunat.description` | texto o null | Descripción de SUNAT. |
| `sunat.notes` | lista | Observaciones de SUNAT (estado `observed`). |
| `sunat.hash` | texto o null | Valor resumen (`DigestValue`) de la firma, para la representación impresa. |
| `sunat.send_attempts` | entero | Intentos de envío realizados. |
| `note` | objeto o null | En notas: `reason_code`, `reason_description` y `affected_document` (`id`, `document_type`, `full_number`). |
| `void` | objeto o null | Si se pidió la anulación: `status` (`requested`, `voided`, `rejected`) y `reason`. Ver [Anulación](https://faktura-doc.cgallardo.me/endpoints/anulacion/). |
| `links.self` | texto | Ruta de este comprobante (`/v1/documents/{id}`). |
| `links.xml`, `links.cdr` | texto o null | Rutas de descarga de [XML](https://faktura-doc.cgallardo.me/endpoints/comprobantes/xml/) y [CDR](https://faktura-doc.cgallardo.me/endpoints/comprobantes/cdr/) cuando ya existen. |
| `links.pdf` | texto | [Representación impresa](https://faktura-doc.cgallardo.me/endpoints/pdf/) con API key (`?format=a4`, `ticket` o `ticket58`). |
| `links.public_pdf`, `links.public_ticket`, `links.public_ticket_58` | texto | Enlaces firmados (A4, ticket 80 mm y ticket 58 mm), sin API key, que vencen a los 7 días ([ver detalles](https://faktura-doc.cgallardo.me/endpoints/pdf/#enlace-público-para-el-cliente-final)). |

## Anexo: Nota de débito por penalidad (de «Ejemplos de notas y anulaciones»)

La nota de débito aumenta el monto del comprobante. Sus `items` son obligatorios.

```bash
curl -X POST https://faktura-test.cgallardo.me/v1/debit-notes \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: erp-penalidad-0001" \
  -d '{
    "affected_document_id": "<id-de-la-factura>",
    "series": "FD01",
    "reason_code": "03",
    "reason_description": "Penalidad por entrega tardía",
    "items": [ { "description": "Penalidad por entrega tardía", "quantity": 1, "unit_price": 59 } ]
  }'
```

```json
{
  "totals": {
    "taxed": "50.00", "exempt": "0.00", "unaffected": "0.00", "free": "0.00",
    "igv": "9.00", "icbper": "0.00", "total_taxes": "9.00", "discounts": "0.00", "charges": "0.00", "total": "59.00"
  }
}
```

## Anexo: Errores de notas (de «Errores»)

Además de los de emisión:

| Estado | `reason` | Causa |
| --- | --- | --- |
| `422` | `AffectedDocumentNotFound` | `affected_document_id` no existe en tu empresa y entorno. |
| `422` | `InvalidAffectedDocument` | El comprobante afectado es una nota; solo se modifican facturas y boletas. |
| `409` | `AffectedDocumentNotAccepted` | El comprobante afectado aún no fue aceptado por SUNAT. |
| `409` | `AffectedDocumentVoided` | El comprobante afectado está anulado o tiene una anulación en curso. |
| `422` | `InvalidNoteReason` | `reason_code` no existe o no está soportado para ese tipo de nota. |
| `422` | `InvalidNoteDescription` | `reason_description` de más de 250 caracteres. |
| `422` | `NoteSeriesMismatch` | La serie de la nota no empieza con la misma letra que la del comprobante (`F` o `B`). |
| `422` | `NoteIssuedBeforeAffected` | `issue_date` de la nota es anterior a la fecha de emisión del comprobante afectado. |
| `422` | `NoteItemsRequired` | El motivo exige enviar `items`. |
| `422` | `NoteItemsNotAllowed` | El motivo `13` (ajuste de montos y/o fechas de pago) no admite `items`. |
| `422` | `CreditNoteExceedsAffectedTotal` | La nota de crédito supera el total del comprobante. |
| `422` | `CreditNotesExceedAffectedTotal` | Con esta nota, las notas de crédito acumuladas superarían el total del comprobante afectado. |
| `422` | `PaymentAdjustmentRequiresCreditInvoice` | El motivo `13` exige que el comprobante afectado sea una factura al crédito. |
| `422` | `PaymentAdjustmentRequiresInstallments` | El motivo `13` exige enviar el nuevo cronograma en `payment.installments`. |
| `422` | `InstallmentsExceedPendingAmount` | En el motivo `13`, las cuotas suman más que el neto pendiente (`net_payable`) de la factura afectada. |
| `422` | `PaymentOnlyForAdjustmentNotes` | Se envió `payment` en una nota cuyo motivo no es el `13`. |

## Reglas generales de la API

- Montos en las respuestas como texto decimal (`"16.00"`); en las peticiones, número o texto.
- Fechas `YYYY-MM-DD` en hora de Perú (`America/Lima`); identificadores UUID.
- Un comprobante emitido responde `201` con `status: "pending"`: el número ya es tuyo. El resultado de SUNAT llega después (webhook o `GET /v1/documents/{id}`).
- Documentación completa: https://faktura-doc.cgallardo.me/ · Toda la API en una skill: https://faktura-doc.cgallardo.me/skills/faktura-api.md
