---
name: faktura-ejemplos-de-notas-y-anulaciones
description: "Ejemplos de notas y anulaciones con la API de Faktura (facturación electrónica SUNAT, Perú). Recetas listas para copiar cuando necesites corregir o anular un comprobante que SUNAT ya aceptó. Usan como referencia la factura F001-1 del ejemplo de factu… Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Ejemplos de notas y anulaciones — Faktura API

## Propósito

Le da a tu asistente el contexto para **ejemplos de notas y anulaciones** con la API de Faktura: Recetas listas para copiar cuando necesites corregir o anular un comprobante que SUNAT ya aceptó. Usan como referencia la factura F001-1 del ejemplo de factu…

Instalación en Claude Code: guarda este archivo como `.claude/skills/faktura-ejemplos-de-notas-y-anulaciones/SKILL.md` en tu proyecto. Fuente: https://faktura-doc.cgallardo.me/ejemplos/notas-y-anulaciones/

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

Las reglas de cada motivo están en [Emitir una nota de crédito](https://faktura-doc.cgallardo.me/endpoints/nota-de-credito/), [Emitir una nota de débito](https://faktura-doc.cgallardo.me/endpoints/nota-de-debito/) y [Anular un comprobante](https://faktura-doc.cgallardo.me/endpoints/anulacion/).

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

| Situación | Qué usar |
| --- | --- |
| El comprobante tiene un error y no debió existir | [Anulación](https://faktura-doc.cgallardo.me/ejemplos/notas-y-anulaciones/#anular-una-boleta) (comunicación de baja o resumen diario), o nota de crédito motivo `01` |
| El cliente devuelve parte de lo comprado | Nota de crédito motivo `07` (devolución por ítem) |
| Das un descuento después de emitir | Nota de crédito motivo `04` (descuento global) |
| Cobras intereses o una penalidad | Nota de débito |

## Devolver parte de una factura

El cliente devuelve los dos libros. La nota de crédito lleva solo los ítems devueltos, con su precio.

```bash
curl -X POST https://faktura-test.cgallardo.me/v1/credit-notes \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: erp-devolucion-0001" \
  -d '{
    "affected_document_id": "<id-de-la-factura>",
    "series": "FC01",
    "reason_code": "07",
    "reason_description": "Devolución de 2 libros",
    "items": [ { "description": "Libro", "quantity": 2, "unit_price": 5.5, "igv_type": "exonerado" } ]
  }'
```

Los libros son exonerados, así que la nota no lleva IGV:

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

## Descuento después de emitir

Un descuento por pronto pago de S/ 11.80 (IGV incluido) sobre la factura.

```bash
curl -X POST https://faktura-test.cgallardo.me/v1/credit-notes \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: erp-descuento-0001" \
  -d '{
    "affected_document_id": "<id-de-la-factura>",
    "series": "FC01",
    "reason_code": "04",
    "reason_description": "Descuento por pronto pago",
    "items": [ { "description": "Descuento por pronto pago", "quantity": 1, "unit_price": 11.80 } ]
  }'
```

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

## Nota de crédito a una boleta

Las notas de una boleta usan una serie que empieza con `B` (`BC01`). Aquí el cliente devuelve uno de los dos cafés.

```bash
curl -X POST https://faktura-test.cgallardo.me/v1/credit-notes \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pos-0042-devolucion-01" \
  -d '{
    "affected_document_id": "<id-de-la-boleta>",
    "series": "BC01",
    "reason_code": "07",
    "items": [ { "description": "Cafe americano", "quantity": 1, "unit_price": 8.00 } ]
  }'
```

```json
{
  "totals": {
    "taxed": "6.78", "exempt": "0.00", "unaffected": "0.00", "free": "0.00",
    "igv": "1.22", "icbper": "0.00", "total_taxes": "1.22", "discounts": "0.00", "charges": "0.00", "total": "8.00"
  }
}
```

## Nota de débito por penalidad

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

## Anular una boleta

La anulación de una boleta viaja en un resumen diario (RC). SUNAT responde con un ticket que Faktura consulta sola. El estado de la baja se ve en el bloque `void` del comprobante.

```bash
curl -X POST https://faktura-test.cgallardo.me/v1/documents/<id-de-la-boleta>/void \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Venta duplicada" }'
```

Una factura se anula igual, con su propio `id`: Faktura envía una comunicación de baja (RA) en lugar del resumen ([Anular un comprobante](https://faktura-doc.cgallardo.me/endpoints/anulacion/)).

## 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: Ejemplo (de «Emitir una boleta»)

```bash
curl -X POST https://faktura-test.cgallardo.me/v1/receipts \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pos-0042-000187" \
  -d '{
    "series": "B001",
    "customer": { "doc_type": "DNI", "doc_number": "45678912", "name": "MARIA PEREZ" },
    "items": [
      { "product_code": "CAF-01", "description": "Cafe americano", "quantity": 2, "unit_price": 8.00 },
      { "description": "Bolsa plastica", "quantity": 1, "unit_price": 0.10, "icbper": true }
    ]
  }'
```

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