---
name: faktura-descuentos-detraccion-y-retencion
description: "Descuentos, detracción y retención con la API de Faktura (facturación electrónica SUNAT, Perú). Ejemplos listos para copiar y validados ante SUNAT: solo cambia la API key, la serie y los datos del cliente por los tuyos. Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Descuentos, detracción y retención — Faktura API

## Propósito

Le da a tu asistente el contexto para **descuentos, detracción y retención** con la API de Faktura: Ejemplos listos para copiar y validados ante SUNAT: solo cambia la API key, la serie y los datos del cliente por los tuyos.

Instalación en Claude Code: guarda este archivo como `.claude/skills/faktura-descuentos-detraccion-y-retencion/SKILL.md` en tu proyecto. Fuente: https://faktura-doc.cgallardo.me/guias/descuentos-detraccion-retencion/

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

## Descuento por ítem y descuento global

Con `price_includes_tax: true` (por defecto), los montos de descuento son **con IGV**: lo que deja de pagar el cliente. Faktura calcula la rebaja de la base imponible que exige SUNAT (catálogo 53: `00` por ítem, `02` global).

```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-9101" \
  -d '{
    "series": "F001",
    "customer": { "doc_type": "RUC", "doc_number": "20100070970", "name": "CLIENTE S.A.C." },
    "items": [
      { "description": "Laptop", "quantity": 1, "unit_price": 118, "discount": { "amount": 18 } },
      { "description": "Mouse", "quantity": 2, "unit_price": 50, "discount": { "percent": 10 } },
      { "description": "Libro", "quantity": 1, "unit_price": 20, "igv_type": "exonerado" }
    ],
    "discount": { "amount": 11.8 }
  }'
```

Respuesta (resumida):

```json
{
  "totals": {
    "taxed": "151.02", "exempt": "20.00", "unaffected": "0.00", "free": "0.00",
    "igv": "27.18", "icbper": "0.00", "total_taxes": "27.18", "discounts": "33.73", "charges": "0.00", "total": "198.20"
  },
  "global_discount": { "base_amount": "161.02", "amount": "10.00" }
}
```

| Ítem | Precio de lista | Descuento con IGV | Paga | Base (`line_value`) | `discount` (base) |
| --- | --- | --- | --- | --- | --- |
| Laptop | 118.00 | 18.00 | 100.00 | 84.75 | 15.25 |
| Mouse | 100.00 | 10.00 | 90.00 | 76.27 | 8.48 |
| Libro | 20.00 | — | 20.00 | 20.00 | 0.00 |

El descuento global de S/ 11.80 se aplica solo sobre los ítems gravados: su total con IGV pasa de 190.00 a 178.20. Así, la base gravada queda en 151.02, el IGV en 27.18 y el total en **198.20**. La respuesta lo detalla en `global_discount` y en `totals.discounts` (33.73 sobre la base).

Reglas:

- Cada descuento es `amount` **o** `percent`, nunca ambos (`details: ["discount:AmountOrPercent"]`).
- No se admiten descuentos en ítems gratuitos.
- El descuento global exige al menos un ítem gravado.
- Una nota de crédito que anula un comprobante con descuentos copia sus líneas **ya netas**, con el mismo total.
- Las notas con ítems propios no admiten descuentos.

## Detracción (SPOT)

Para servicios o bienes sujetos al Sistema de Pago de Obligaciones Tributarias. El porcentaje lo eliges según el código del bien o servicio (catálogo 54).

```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-9102" \
  -d '{
    "series": "F001",
    "customer": { "doc_type": "RUC", "doc_number": "20100070970", "name": "CLIENTE S.A.C." },
    "items": [{ "description": "Mantenimiento de equipos", "quantity": 1, "unit_price": 1180 }],
    "detraction": { "code": "020", "percent": 12, "bank_account": "00-000-123456" },
    "payment": { "type": "credito", "installments": [{ "amount": 1038.40, "due_date": "2026-12-15" }] }
  }'
```

Respuesta (resumida):

```json
{
  "totals": {
    "taxed": "1000.00", "exempt": "0.00", "unaffected": "0.00", "free": "0.00",
    "igv": "180.00", "icbper": "0.00", "total_taxes": "180.00", "discounts": "0.00", "charges": "0.00", "total": "1180.00"
  },
  "net_payable": "1038.40",
  "detraction": { "code": "020", "percent": "12", "amount": "141.60", "amount_in_document_currency": "141.60", "bank_account": "00-000-123456", "payment_method": "001", "exchange_rate": null }
}
```

- La detracción es de 12 % sobre 1180.00, es decir S/ 141.60. Tu cliente la deposita en tu cuenta del Banco de la Nación.
- El neto pendiente de pago (`net_payable`) es 1038.40: las cuotas deben sumar exactamente eso.
- La factura va con tipo de operación `1001` y la leyenda "Operación sujeta a detracción".
- En dólares agrega `"exchange_rate": 3.75`. La detracción se informa en soles (1180 × 3.75 × 12 % = S/ 531.00) y en la moneda del comprobante (US$ 141.60).

## Retención del IGV

Si tu cliente es agente de retención, informa el 3 % que retendrá:

```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-9103" \
  -d '{
    "series": "F001",
    "customer": { "doc_type": "RUC", "doc_number": "20100070970", "name": "CLIENTE S.A.C." },
    "items": [{ "description": "Repuestos", "quantity": 1, "unit_price": 1180 }],
    "retention": true,
    "payment": { "type": "credito", "installments": [{ "amount": 1144.60, "due_date": "2026-12-15" }] }
  }'
```

Respuesta (resumida):

```json
{
  "totals": {
    "taxed": "1000.00", "exempt": "0.00", "unaffected": "0.00", "free": "0.00",
    "igv": "180.00", "icbper": "0.00", "total_taxes": "180.00", "discounts": "0.00", "charges": "0.00", "total": "1180.00"
  },
  "net_payable": "1144.60",
  "retention": { "percent": "3", "base_amount": "1180.00", "amount": "35.40" }
}
```

- La retención es de S/ 35.40 (catálogo 53, código `62`) y no cambia el total: reduce el neto pendiente de pago a 1144.60.
- Requiere soles y un total mayor a S/ 700. No se combina con detracción.

## Datos comerciales

Fragmento con los campos; el ejemplo completo está en el [recetario de facturas](https://faktura-doc.cgallardo.me/ejemplos/facturas/#con-orden-de-compra-guía-de-remisión-y-vencimiento).

```json
{
  "purchase_order": "OC-2026-001",
  "despatch_references": [{ "type": "09", "number": "T001-123" }],
  "observations": "Entrega en almacén central",
  "due_date": "2026-12-15"
}
```

Viajan en el XML (`OrderReference`, `DespatchDocumentReference`, `Note`, `DueDate`) y aparecen en el PDF.

## Anexo: Con orden de compra, guía de remisión y vencimiento (de «Ejemplos de facturas»)

La orden de compra del cliente, las guías de remisión, las observaciones y la fecha de vencimiento viajan en el XML y aparecen en el PDF.

```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-9005" \
  -d '{
    "series": "F001",
    "customer": { "doc_type": "RUC", "doc_number": "20100070970", "name": "CLIENTE S.A.C.", "address": "AV. LOS OLIVOS 123, LIMA" },
    "items": [ { "description": "Cemento Portland tipo I (bolsa 42.5 kg)", "quantity": 100, "unit_price": 29.50, "unit_code": "BG" } ],
    "purchase_order": "OC-2026-001",
    "despatch_references": [ { "type": "09", "number": "T001-123" } ],
    "observations": "Entrega en almacén central",
    "due_date": "2026-12-15"
  }'
```

```json
{
  "totals": {
    "taxed": "2500.00", "exempt": "0.00", "unaffected": "0.00", "free": "0.00",
    "igv": "450.00", "icbper": "0.00", "total_taxes": "450.00", "discounts": "0.00", "charges": "0.00", "total": "2950.00"
  },
  "purchase_order": "OC-2026-001",
  "due_date": "2026-12-15"
}
```

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