---
name: faktura-catalogos
description: "Catálogos con la API de Faktura (facturación electrónica SUNAT, Perú). La API usa nombres legibles y los traduce a los catálogos oficiales de SUNAT (Anexo N.° 8 de la RS N.° 097-2012/SUNAT y modificatorias). Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Catálogos — Faktura API

## Propósito

Le da a tu asistente el contexto para **catálogos** con la API de Faktura: La API usa nombres legibles y los traduce a los catálogos oficiales de SUNAT (Anexo N.° 8 de la RS N.° 097-2012/SUNAT y modificatorias).

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

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

## Tipo de documento del cliente (`customer.doc_type`)

| Valor | Catálogo 06 | Formato de `doc_number` | Permitido en |
| --- | --- | --- | --- |
| `RUC` | `6` | 11 dígitos con dígito verificador válido | Facturas y boletas |
| `DNI` | `1` | 8 dígitos | Boletas |
| `CE` | `4` | 4 a 12 letras o números (carné de extranjería) | Boletas |
| `PASAPORTE` | `7` | 4 a 12 letras o números | Boletas |
| `NONE` | `-` | Se omite; el cliente figura como «CLIENTES VARIOS» | Boletas en soles de hasta S/ 700 |

## Tipo de comprobante (`document_type` en las respuestas)

| Valor | Comprobante | Serie | Endpoint |
| --- | --- | --- | --- |
| `01` | Factura electrónica | `F` + 3 letras o números (`F001`) | [`POST /v1/invoices`](https://faktura-doc.cgallardo.me/endpoints/facturas/) |
| `03` | Boleta de venta electrónica | `B` + 3 letras o números (`B001`) | [`POST /v1/receipts`](https://faktura-doc.cgallardo.me/endpoints/boletas/) |
| `07` | Nota de crédito electrónica | Misma letra que el comprobante afectado (`FC01`, `BC01`) | [`POST /v1/credit-notes`](https://faktura-doc.cgallardo.me/endpoints/nota-de-credito/) |
| `08` | Nota de débito electrónica | Misma letra que el comprobante afectado (`FD01`, `BD01`) | [`POST /v1/debit-notes`](https://faktura-doc.cgallardo.me/endpoints/nota-de-debito/) |

## Afectación del IGV (`items[].igv_type`)

| Valor en la API | Catálogo 07 | Tributos en UBL 2.1 | Cuándo usarlo |
| --- | --- | --- | --- |
| `gravado` (por defecto) | `10` | `1000` (IGV 18 %) | Operación onerosa gravada con el IGV. |
| `exonerado` | `20` | `9997` (EXO 0 %) | Operación exonerada del IGV por ley (p. ej. libros o productos agrarios del Apéndice I). |
| `inafecto` | `30` | `9998` (INA 0 %) | Operación fuera del ámbito de aplicación del IGV. |
| `gratuito` | `15` | `9996` (GRA, IGV referencial 18 %) | Bonificación, muestra comercial o retiro de bienes gravados. |
| `gratuito_exonerado` | `21` | `9996` (GRA 0 %) | Entrega gratuita de un bien exonerado. |
| `gratuito_inafecto` | `31` | `9996` (GRA 0 %) | Entrega gratuita de un bien o servicio inafecto. |

Detalle de fórmulas y redondeo en [Cálculo de impuestos](https://faktura-doc.cgallardo.me/calculo-de-impuestos/#tipos-de-afectación-igv_type).

## Unidad de medida (`items[].unit_code`)

Código del catálogo 03 de SUNAT (UN/ECE Rec. 20). Por defecto `NIU`. Los más usados:

| Código | Unidad |
| --- | --- |
| `NIU` | Unidad (bienes) |
| `ZZ` | Unidad (servicios) |
| `KGM` | Kilogramo |
| `GRM` | Gramo |
| `LTR` | Litro |
| `MTR` | Metro |
| `MTK` | Metro cuadrado |
| `MTQ` | Metro cúbico |
| `BX` | Caja |
| `PK` | Paquete |
| `BG` | Bolsa |
| `BO` | Botella |
| `DZN` | Docena |
| `HUR` | Hora |
| `DAY` | Día |
| `MON` | Mes |

La API acepta de 1 a 3 letras mayúsculas o números; SUNAT rechaza un código que no exista en su catálogo.

## Moneda (`currency`)

| Valor | Moneda (ISO 4217) | Leyenda en letras |
| --- | --- | --- |
| `PEN` (por defecto) | Sol | `… SOLES` |
| `USD` | Dólar estadounidense | `… DÓLARES AMERICANOS` |

## Forma de pago (`payment.type`)

| Valor | Significado |
| --- | --- |
| `contado` (por defecto) | Pago al contado. |
| `credito` | Pago al crédito con cronograma de cuotas (`installments`). Solo facturas. |

## Motivos de nota de crédito (`reason_code` — Catálogo 09)

| Código | Motivo | `items` |
| --- | --- | --- |
| `01` | Anulación de la operación | Opcional (copia el comprobante) |
| `02` | Anulación por error en el RUC | Opcional (copia el comprobante) |
| `03` | Corrección por error en la descripción | Opcional (copia el comprobante) |
| `04` | Descuento global | Obligatorio |
| `05` | Descuento por ítem | Obligatorio |
| `06` | Devolución total | Opcional (copia el comprobante) |
| `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 `items`; usa `payment` |

Detalle y reglas en [Emitir una nota de crédito](https://faktura-doc.cgallardo.me/endpoints/nota-de-credito/#motivos-admitidos-catálogo-09).

## Motivos de nota de débito (`reason_code` — Catálogo 10)

| Código | Motivo | `items` |
| --- | --- | --- |
| `01` | Intereses por mora | Obligatorio |
| `02` | Aumento en el valor | Obligatorio |
| `03` | Penalidades / otros conceptos | Obligatorio |

Detalle en [Emitir una nota de débito](https://faktura-doc.cgallardo.me/endpoints/nota-de-debito/#motivos-admitidos-catálogo-10).

## Bienes y servicios sujetos a detracción (Catálogo 54)

En `detraction.code` se envía el código de 3 dígitos del catálogo 54 de SUNAT y en `detraction.percent` la tasa vigente que corresponde a la operación. Códigos frecuentes en servicios y comercio:

| Código | Bien o servicio | Tasa habitual |
| --- | --- | --- |
| `012` | Intermediación laboral y tercerización | `12` |
| `019` | Arrendamiento de bienes muebles o inmuebles | `10` |
| `020` | Mantenimiento y reparación de bienes muebles | `12` |
| `021` | Movimiento de carga | `10` |
| `022` | Otros servicios empresariales (consultoría, sistemas, contabilidad, legal, publicidad) | `12` |
| `024` | Comisión mercantil | `10` |
| `025` | Fabricación de bienes por encargo | `10` |
| `026` | Servicio de transporte de personas | `10` |
| `027` | Servicio de transporte de carga | `4` |
| `030` | Contratos de construcción | `4` |
| `037` | Demás servicios gravados con el IGV | `12` |

Ejemplo completo en la [guía de descuentos, detracción y retención](https://faktura-doc.cgallardo.me/guias/descuentos-detraccion-retencion/#detracción-spot).

## Medio de pago de la detracción (Catálogo 59)

En `detraction.payment_method` se envía un código de 3 dígitos del catálogo 59 de SUNAT (`001` por defecto):

| Código | Medio de pago |
| --- | --- |
| `001` (por defecto) | Depósito en cuenta |
| `002` | Giro |
| `003` | Transferencia de fondos |
| `004` | Orden de pago |
| `005` | Tarjeta de débito |
| `006` | Tarjeta de crédito emitida en el país por una empresa del sistema financiero |
| `999` | Otros medios de pago |

## Guías de remisión relacionadas (`despatch_references`)

Cada elemento de `despatch_references` indica el tipo de guía (Catálogo 01) y su número en formato `SERIE-NÚMERO` (4 caracteres alfanuméricos de serie, guion y de 1 a 8 dígitos):

| `type` | Tipo de guía | Ejemplo de `number` |
| --- | --- | --- |
| `09` | Guía de remisión remitente | `T001-123` o `EG07-45` |
| `31` | Guía de remisión transportista | `V001-88` |

## Anexo: Tipos de afectación (igv_type) (de «Cálculo de impuestos»)

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

## Anexo: Motivos admitidos (catálogo 09) (de «Emitir una nota de crédito»)

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

## Anexo: Motivos admitidos (catálogo 10) (de «Emitir una nota de débito»)

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

## Anexo: Detracción (SPOT) (de «Descuentos, detracción y retención»)

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

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