---
name: faktura-emitir-una-nota-de-credito
description: "Emitir una nota de crédito con la API de Faktura (facturación electrónica SUNAT, Perú). Una nota modifica un comprobante ya aceptado por SUNAT. La nota de crédito disminuye o anula el monto (devoluciones, anulaciones, rebajas) o reprograma el cr… Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Emitir una nota de crédito — Faktura API

## Propósito

Le da a tu asistente el contexto para **emitir una nota de crédito** con la API de Faktura: Una nota modifica un comprobante ya aceptado por SUNAT. La nota de crédito disminuye o anula el monto (devoluciones, anulaciones, rebajas) o reprograma el cr…

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

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

| Bloque / cabecera | De dónde sale |
| --- | --- |
| `Idempotency-Key` (cabecera) | Del identificador único de la devolución o anulación en tu sistema. |
| `affected_document_id` | Del campo `id` (UUID) de la factura o boleta original guardada al emitirla (o consultada con `GET /v1/documents`). Debe estar en `status: "accepted"` u `"observed"`. |
| `series` | Del endpoint `GET /v1/series`, con la misma letra inicial que el comprobante afectado (`FC01` para facturas, `BC01` para boletas). |
| `reason_code` | Del catálogo 09 de SUNAT incluido en esta skill (`01` anulación de la operación, `07` devolución por ítem, `13` ajuste de cuotas…). |
| `items` / `payment` | En los motivos que cubren todo el comprobante (`01`, `02`, `03`, `06`) puedes omitir `items` y Faktura copia las líneas del comprobante original; en el motivo `13` envías `payment.installments`; en los demás motivos envías las líneas que se devuelven o descuentan. |

## Endpoint

| Ambiente | Petición |
| --- | --- |
| Pruebas | `POST https://faktura-test.cgallardo.me/v1/credit-notes` |
| Producción | `POST https://faktura.cgallardo.me/v1/credit-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 creada para tu empresa. Debe empezar con la misma letra que el comprobante: `F` para facturas (`FC01`) y `B` para boletas (`BC01`). |
| `reason_code` | texto | Sí | Motivo SUNAT, de 2 dígitos (catálogo 09; 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. |
| `issue_date` | fecha | No | Igual que al emitir: hasta 3 días atrás y nunca antes de la fecha del comprobante afectado (`NoteIssuedBeforeAffected`). |
| `items` | lista | Según el motivo | En los motivos `01`, `02`, `03` y `06` puedes omitirlos y se copian los del comprobante; en `04`, `05`, `07`, `08`, `09` y `10` son obligatorios; en `13` no se admiten. |
| `items[].description` | texto | Sí (en ítems) | Descripción del ítem, hasta 500 caracteres. |
| `items[].quantity` | número o texto | Sí (en ítems) | Cantidad mayor que 0, hasta 10 decimales. |
| `items[].unit_price` | número o texto | Sí (en ítems) | 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 devuelto corresponde a una bolsa plástica. |
| `items[].unit_code` | texto | No | Unidad de medida (`NIU` por defecto). |
| `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. |
| `payment` | objeto | Solo motivo `13` | Nuevo cronograma: `{"type": "credito", "installments": [{"amount": 100, "due_date": "2026-12-15"}]}`. |

## Motivos admitidos (catálogo 09)

| `reason_code` | Motivo | `items` |
| --- | --- | --- |
| `01` | Anulación de la operación | Opcional: sin ítems copia el comprobante completo |
| `02` | Anulación por error en el RUC | Opcional: sin ítems copia el comprobante completo |
| `03` | Corrección por error en la descripción | Opcional: sin ítems copia el comprobante completo |
| `04` | Descuento global | Obligatorio |
| `05` | Descuento por ítem | Obligatorio |
| `06` | Devolución total | Opcional: sin ítems copia el comprobante completo |
| `07` | Devolución por ítem | Obligatorio |
| `08` | Bonificación | Obligatorio |
| `09` | Disminución en el valor | Obligatorio |
| `10` | Otros conceptos | Obligatorio |
| `13` | Ajustes: montos y/o fechas de pago | No admite ítems: va con `payment` |

Una nota de crédito no puede superar el total del comprobante (`CreditNoteExceedsAffectedTotal`), y las notas que rebajan el monto (todas menos la 03 y la 13) no pueden sumar, entre todas, más que el comprobante (`CreditNotesExceedAffectedTotal`): por ejemplo, no se anula dos veces la misma factura. No se admiten los motivos de exportación (11) ni IVAP (12).

## Motivo 13: cambiar el cronograma de una factura al crédito

Corrige el monto neto pendiente, las fechas o las cuotas de una factura al crédito. La nota va en **cero** (una línea informativa «AJUSTE DE MONTOS Y/O FECHAS DE PAGO») y lleva el nuevo cronograma; las cuotas no pueden sumar más que el neto pendiente del comprobante.

```json
{
  "affected_document_id": "01a1d5fd-…",
  "series": "FC01",
  "reason_code": "13",
  "payment": { "type": "credito", "installments": [
    { "amount": 590, "due_date": "2026-12-15" },
    { "amount": 590, "due_date": "2027-01-15" }
  ] }
}
```

Errores propios: `PaymentAdjustmentRequiresCreditInvoice` (la factura no es al crédito), `PaymentAdjustmentRequiresInstallments`, `NoteItemsNotAllowed`, `InstallmentsExceedPendingAmount` y `PaymentOnlyForAdjustmentNotes` (cronograma en otro motivo).

## Flujo recomendado

1. **Comprueba** que el comprobante esté `accepted` u `observed` con [`GET /v1/documents/{id}`](https://faktura-doc.cgallardo.me/endpoints/comprobantes/ver/).
2. **Elige el motivo**: `01` para anular toda la operación, `07` para una devolución parcial, `04` para un descuento posterior.
3. **Elige la serie** de nota de la misma letra que el comprobante: `FC01` para facturas, `BC01` para boletas.
4. **Emite** `POST /v1/credit-notes` con una `Idempotency-Key` y guarda el `id` de la nota.
5. **Confirma** con SUNAT igual que una factura: [webhook](https://faktura-doc.cgallardo.me/webhooks/) o [`GET /v1/documents/{id}`](https://faktura-doc.cgallardo.me/endpoints/comprobantes/ver/) de la nota.

## Ejemplo: anular una factura con nota de crédito

Anula por completo la factura `F001-1` del [ejemplo de facturas](https://faktura-doc.cgallardo.me/endpoints/facturas/#ejemplo-factura-al-contado), de S/ 129.00:

```bash
curl -X POST https://faktura-test.cgallardo.me/v1/credit-notes \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "affected_document_id": "01a1d60a-7aa5-735b-9cf0-94b9d58a67ac",
    "series": "FC01",
    "reason_code": "01"
  }'
```

Respuesta `201 Created`: un [comprobante](https://faktura-doc.cgallardo.me/endpoints/comprobantes/ver/#el-objeto-comprobante) con `document_type: "07"` y el bloque `note`:

```json
{
  "document_type": "07",
  "full_number": "FC01-1",
  "status": "pending",
  "totals": {
    "taxed": "100.00", "exempt": "11.00", "unaffected": "0.00", "free": "0.00",
    "igv": "18.00", "icbper": "0.00", "total_taxes": "18.00", "discounts": "0.00", "charges": "0.00", "total": "129.00"
  },
  "note": {
    "reason_code": "01",
    "reason_description": "ANULACION DE LA OPERACION",
    "affected_document": {
      "id": "01a1d60a-7aa5-735b-9cf0-94b9d58a67ac",
      "document_type": "01",
      "full_number": "F001-1"
    }
  }
}
```

## ¿Nota de crédito o anulación?

| Situación | Usa |
| --- | --- |
| El comprobante tiene un error y está dentro del plazo de anulación | [Anulación](https://faktura-doc.cgallardo.me/endpoints/anulacion/) |
| Pasó el plazo de anulación, o el cliente devuelve todo o parte | Nota de crédito |
| Hay que cobrar algo adicional sobre una venta ya emitida | Nota de débito |

Más casos (devolución parcial, descuento posterior, nota a una boleta) en los [ejemplos de notas y anulaciones](https://faktura-doc.cgallardo.me/ejemplos/notas-y-anulaciones/).

## Respuestas y errores

| Estado | `reason` | Significado |
| --- | --- | --- |
| `201` | — | Nota de crédito 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`, `CreditNoteExceedsAffectedTotal`, `CreditNotesExceedAffectedTotal` | 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: Ejemplo: factura al contado (de «Emitir una factura»)

```bash
curl -X POST https://faktura-test.cgallardo.me/v1/invoices \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: erp-pedido-8841" \
  -d '{
    "series": "F001",
    "customer": { "doc_type": "RUC", "doc_number": "20100070970", "name": "CLIENTE S.A.C." },
    "items": [
      { "description": "Laptop", "quantity": 1, "unit_price": 118 },
      { "description": "Libro", "quantity": 2, "unit_price": 5.5, "igv_type": "exonerado" }
    ]
  }'
```

## 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: 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
