---
name: faktura-calculo-de-impuestos
description: "Cálculo de impuestos con la API de Faktura (facturación electrónica SUNAT, Perú). Tú envías cantidades y precios; la API calcula IGV, ICBPER y totales como los valida SUNAT. No necesitas calcular impuestos en tu sistema. Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Cálculo de impuestos — Faktura API

## Propósito

Le da a tu asistente el contexto para **cálculo de impuestos** con la API de Faktura: Tú envías cantidades y precios; la API calcula IGV, ICBPER y totales como los valida SUNAT. No necesitas calcular impuestos en tu sistema.

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

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

## Precio con IGV o sin IGV

`price_includes_tax` (a nivel de comprobante, por defecto `true`) indica cómo interpretar `unit_price`.

### Con IGV (`true`, lo habitual en un POS)

Se respeta lo que paga el cliente:

1. Total de la línea = `cantidad × precio`, redondeado a 2 decimales.
2. Valor de venta (base) = total ÷ 1.18, redondeado a 2 decimales.
3. IGV = total − base.

Ejemplo: 2 cafés a S/ 8.00 → total 16.00 → base 13.56 → IGV 2.44. La suma de las líneas coincide siempre con tu ticket.

### Sin IGV (`false`, habitual en facturación a empresas)

1. Valor de venta (base) = `cantidad × valor unitario`, redondeado a 2 decimales.
2. IGV = base × tasa del emisor (18 %, o la reducida de la sección siguiente), redondeado a 2 decimales.
3. Total de la línea = base + IGV.

Ejemplo: 3 × 10.555 → base 31.67 → IGV 5.70 → total 37.37.

Los redondeos son *half-up* (0.005 sube a 0.01). Los valores unitarios se guardan con hasta 10 decimales.

## Tipos de afectación (`igv_type`)

| `igv_type` | Código SUNAT | IGV | Uso típico |
| --- | --- | --- | --- |
| `gravado` (por defecto) | 10 | 18 % (o la tasa reducida del emisor) | La mayoría de bienes y servicios. |
| `exonerado` | 20 | 0 % | Bienes exonerados (por ejemplo, libros, algunos alimentos primarios). |
| `inafecto` | 30 | 0 % | Operaciones fuera del ámbito del IGV. |
| `gratuito` | 15 | Informativo | Bonificaciones gravadas: no se cobran, pero se declaran con su valor referencial y el IGV que habrían tenido. |
| `gratuito_exonerado` | 21 | 0 % | Entrega gratuita de un bien exonerado (por ejemplo, un libro de regalo). |
| `gratuito_inafecto` | 31 | 0 % | Bonificación o muestra inafecta. |

Para un ítem gratuito, `unit_price` es el **valor referencial** (en `gratuito`, con o sin IGV según `price_includes_tax`; en los otros dos, sin IGV). El ítem no suma al total a pagar; aparece en `totals.free`, y el comprobante lleva la leyenda «TRANSFERENCIA GRATUITA…».

## Tasa reducida para restaurantes y hoteles MYPE

Las micro y pequeñas empresas de restaurantes, hoteles y alojamientos turísticos tienen una tasa temporal reducida (Ley 32219): en 2026, **10.5 %** (8 % de IGV más 2.5 % de IPM). La tasa se configura en la ficha de tu empresa al darte de alta o solicitándolo a soporte; no se envía en cada comprobante. La respuesta la informa en `igv_percent` y las notas usan la tasa del comprobante que modifican.

## Recargo al consumo

`service_charge` (`{"percent": 10}` o `{"amount": 5}`) agrega el recargo al consumo de restaurantes (catálogo 53, código 46): se calcula sobre el valor de venta (sin IGV), **no** forma parte de la base del IGV y se suma al total. Aparece en `totals.charges` y en `service_charge`.

## Impuesto a las bolsas plásticas (ICBPER)

Marca el ítem con `"icbper": true`. Se agrega S/ 0.50 por unidad, aparte del IGV:

```json
{ "description": "Bolsa plástica", "quantity": 2, "unit_price": 0.10, "icbper": true }
```

Resultado: base 0.17, IGV 0.03, ICBPER 1.00 → la línea suma S/ 1.20 al total.

## Totales del comprobante

| Campo en `totals` | Contenido |
| --- | --- |
| `taxed` | Suma de bases gravadas. |
| `exempt` | Suma de líneas exoneradas. |
| `unaffected` | Suma de líneas inafectas. |
| `free` | Valor referencial de las líneas gratuitas (no se cobra). |
| `igv` | IGV cobrado. |
| `icbper` | Impuesto a las bolsas. |
| `total_taxes` | `igv + icbper`. |
| `discounts` | Descuentos sobre la base (informativo, ya restados). |
| `charges` | Recargo al consumo. |
| `total` | Importe a pagar: `taxed + exempt + unaffected + total_taxes + charges`. |

`amount_in_words` trae el total en letras, tal como SUNAT exige en la representación impresa: `SON DIECISÉIS CON 60/100 SOLES`. Descuentos, detracción y retención se detallan en su [guía](https://faktura-doc.cgallardo.me/guias/descuentos-detraccion-retencion/).

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