---
name: faktura-glosario
description: "Glosario con la API de Faktura (facturación electrónica SUNAT, Perú). Términos fiscales de la facturación electrónica en el Perú (SUNAT) y conceptos técnicos de la API de Faktura, ordenados alfabéticamente. Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Glosario — Faktura API

## Propósito

Le da a tu asistente el contexto para **glosario** con la API de Faktura: Términos fiscales de la facturación electrónica en el Perú (SUNAT) y conceptos técnicos de la API de Faktura, ordenados alfabéticamente.

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

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

## A

### Ambiente de pruebas (`test` / SUNAT beta)
Entorno en el que toda petición autenticada con una clave `sk_test_` firma el XML y lo envía a los servidores de homologación y pruebas de SUNAT (**SUNAT beta**). No tiene validez tributaria y su numeración es independiente de la de producción. Ver [Introducción](https://faktura-doc.cgallardo.me/introduccion/#entornos-prueba-y-producción).

### API key
Credencial secreta que identifica a tu empresa emisora y define el ambiente al que van las llamadas: `sk_test_…` apunta a SUNAT beta y `sk_live_…` a SUNAT producción. Se envía en la cabecera `Authorization: Bearer <api key>`. Puede tener alcance `full` (emitir y consultar) o `lookup` (solo consultas de RUC y DNI). Ver [Autenticación](https://faktura-doc.cgallardo.me/autenticacion/).

## B

### Boleta de venta electrónica (`03`)
Comprobante de pago emitido a consumidores finales ([`POST /v1/receipts`](https://faktura-doc.cgallardo.me/endpoints/boletas/)). Usa series que empiezan con `B` (`B001`). En soles y hasta S/ 700.00 admite cliente sin documento (`customer.doc_type: "NONE"`).

## C

### CDR (Constancia de Recepción)
Archivo ZIP firmado digitalmente por SUNAT (p. ej. `R-20000000001-01-F001-1.zip`) que contiene el XML `ApplicationResponse` con el veredicto oficial sobre un comprobante (`0` aceptado, con o sin observaciones, o código de rechazo). Es el sustento legal de aceptación y se descarga en [`GET /v1/documents/{id}/cdr`](https://faktura-doc.cgallardo.me/endpoints/comprobantes/cdr/).

### Certificado digital
Certificado X.509 (archivo `.pfx` o `.p12`) emitido por una entidad de certificación acreditada ante INDECOPI a nombre del RUC del emisor. Faktura lo usa para firmar digitalmente (XMLDSig) cada comprobante antes de enviarlo a SUNAT.

### Comunicación de baja (`RA`)
Resumen firmado (`RA-YYYYMMDD-#####`) mediante el cual se comunica a SUNAT la anulación de facturas y notas electrónicas con serie `F` dentro de los 7 días calendario desde su emisión. Faktura lo genera y consulta su ticket automáticamente cuando llamas a [`POST /v1/documents/{id}/void`](https://faktura-doc.cgallardo.me/endpoints/anulacion/).

### Correlativo (`number`)
Número entero secuencial asignado por Faktura dentro de una serie (`1`, `2`, `3`…) en la misma transacción en que se registra el comprobante. Junto con la serie forma `full_number` (`F001-1`).

## D

### Detracción (SPOT)
Sistema de Pago de Obligaciones Tributarias (leyenda `2006`, tipo de operación `1001`). En facturas de bienes o servicios afectos ([Catálogo 54](https://faktura-doc.cgallardo.me/catalogos/#bienes-y-servicios-sujetos-a-detracción-catálogo-54)), el comprador deposita un porcentaje del total en la cuenta del Banco de la Nación del emisor y paga el resto (`net_payable`). Ver la [guía de detracción](https://faktura-doc.cgallardo.me/guias/descuentos-detraccion-retencion/#detracción-spot).

## E

### Estados del comprobante (`status`)
Ciclo de vida del envío a SUNAT:
- `pending`: creado, numerado y firmado; en cola para enviarse a SUNAT.
- `sending`: envío en curso.
- `uncertain`: la conexión se cortó sin saber si SUNAT recibió el envío; Faktura consulta el estado antes de reenviar.
- `accepted`: aceptado por SUNAT (`sunat.code: "0"`).
- `observed`: aceptado por SUNAT con advertencias en `sunat.notes`.
- `rejected`: rechazado por SUNAT (código `2000`–`3999`); no tiene validez tributaria.
- `failed`: no pudo enviarse por una causa de configuración del emisor (credenciales SOL o certificado); se reenvía con [`POST /v1/documents/{id}/retry`](https://faktura-doc.cgallardo.me/endpoints/comprobantes/reintentar/).

Detalle completo en [Estados y envío a SUNAT](https://faktura-doc.cgallardo.me/estados-y-envio/).

## F

### Factura electrónica (`01`)
Comprobante de pago emitido a clientes con RUC ([`POST /v1/invoices`](https://faktura-doc.cgallardo.me/endpoints/facturas/)) que sustenta costo, gasto y crédito fiscal del IGV. Usa series que empiezan con `F` (`F001`) y admite pago al contado o al crédito con cuotas.

## G

### Guía de remisión relacionada (`despatch_references`)
Referencia a una guía de remisión remitente (`09`) o transportista (`31`) vinculada con el traslado de los bienes facturados ([Catálogos](https://faktura-doc.cgallardo.me/catalogos/#guías-de-remisión-relacionadas-despatch_references)).

## I

### ICBPER (Impuesto al Consumo de las Bolsas de Plástico)
Tributo de monto fijo por unidad (S/ 0.50 por bolsa) que se activa enviando `"icbper": true` en el ítem. Ver [Cálculo de impuestos](https://faktura-doc.cgallardo.me/calculo-de-impuestos/#impuesto-a-las-bolsas-plásticas-icbper).

### Idempotencia (`Idempotency-Key`)
Mecanismo por el cual repetir una petición de emisión con la misma cabecera `Idempotency-Key` y el mismo cuerpo dentro de las 24 horas devuelve exactamente el mismo comprobante (`200 OK`, `Idempotent-Replayed: true`) sin crear un duplicado ni consumir otro correlativo. Ver [Idempotencia](https://faktura-doc.cgallardo.me/idempotencia/).

### IGV (Impuesto General a las Ventas)
Impuesto al valor agregado en el Perú (18 % general: 16 % de IGV + 2 % de IPM). Cada ítem indica su afectación en `igv_type`: `gravado`, `exonerado`, `inafecto`, `gratuito`, `gratuito_exonerado` o `gratuito_inafecto`. Ver [Cálculo de impuestos](https://faktura-doc.cgallardo.me/calculo-de-impuestos/).

## N

### Neto pendiente de pago (`net_payable`)
Monto efectivo que el cliente debe abonar al emisor tras descontar del `totals.total` la detracción o la retención del IGV. En una factura al crédito, la suma de las cuotas (`payment.installments`) debe coincidir exactamente con `net_payable`.

### Nota de crédito electrónica (`07`)
Comprobante que disminuye o anula el valor de una factura o boleta aceptada por SUNAT, o reprograma sus cuotas con el motivo `13` ([`POST /v1/credit-notes`](https://faktura-doc.cgallardo.me/endpoints/nota-de-credito/)).

### Nota de débito electrónica (`08`)
Comprobante que incrementa el valor de una factura o boleta aceptada por SUNAT por intereses moratorios, aumento de valor o penalidades ([`POST /v1/debit-notes`](https://faktura-doc.cgallardo.me/endpoints/nota-de-debito/)).

## P

### Padrón reducido de RUC
Archivo oficial publicado diariamente por SUNAT con el estado, condición de domicilio, ubigeo y dirección de millones de contribuyentes. Faktura lo actualiza diariamente para responder en milisegundos en [Consultar un RUC](https://faktura-doc.cgallardo.me/endpoints/consultas/ruc/), [Consultar varios RUC](https://faktura-doc.cgallardo.me/endpoints/consultas/ruc-lote/) y [Consultar un DNI](https://faktura-doc.cgallardo.me/endpoints/consultas/dni/).

## R

### Recargo al consumo (`service_charge`)
Cargo adicional (en porcentaje o monto fijo) que aplican establecimientos de hospedaje o restaurantes sobre el valor de venta. No forma parte de la base imponible del IGV. Ver [Cálculo de impuestos](https://faktura-doc.cgallardo.me/calculo-de-impuestos/#recargo-al-consumo).

### Representación impresa (PDF)
Versión legible del comprobante electrónico en formato A4 o ticket térmico (80 mm y 58 mm) con código QR, valor resumen (`hash`), importe en letras y leyendas de SUNAT ([`GET /v1/documents/{id}/pdf`](https://faktura-doc.cgallardo.me/endpoints/pdf/)).

### Resumen diario de boletas (`RC`)
Resumen firmado (`RC-YYYYMMDD-#####`) que SUNAT exige para comunicar la anulación (estado `3`) de boletas y notas con serie `B`. Faktura lo envía y consulta su ticket automáticamente al llamar a [`POST /v1/documents/{id}/void`](https://faktura-doc.cgallardo.me/endpoints/anulacion/).

### Retención del IGV (`retention`)
Régimen aplicable cuando el comprador ha sido designado por SUNAT como Agente de Retención: retiene el 3 % del importe total de la operación (en soles y cuando supera S/ 700.00). Ver la [guía de retención](https://faktura-doc.cgallardo.me/guias/descuentos-detraccion-retencion/#retención-del-igv).

### RUC y RUC 10
El Registro Único de Contribuyentes (11 dígitos) identifica a empresas (`20…`) y personas naturales con negocio (`10` + 8 dígitos del DNI + 1 dígito verificador).

## S

### SEE del contribuyente
Sistema de Emisión Electrónica desde los sistemas del contribuyente: modalidad de SUNAT en la que los comprobantes se firman con el certificado digital de la empresa emisora y se transmiten con su usuario SOL secundario.

### Serie (`series`)
Código de 4 caracteres alfanuméricos que identifica el punto de emisión y el tipo de documento: `F###` para facturas (`F001`), `B###` para boletas (`B001`), `FC##`/`BC##` para notas de crédito y `FD##`/`BD##` para notas de débito. Se consultan en [`GET /v1/series`](https://faktura-doc.cgallardo.me/endpoints/series/).

## U

### UBL 2.1 (Universal Business Language)
Estándar XML internacional exigido por SUNAT para todos los comprobantes electrónicos. Faktura lo genera y firma automáticamente a partir del JSON que envías.

### Usuario SOL secundario
Credencial creada dentro de SUNAT Operaciones en Línea con permisos acotados exclusivamente al envío de comprobantes electrónicos, sin acceso a declaraciones ni clave SOL principal.

## V

### Valor resumen (`sunat.hash` / `DigestValue`)
Resumen criptográfico SHA-256 en Base64 generado al firmar el XML del comprobante. Aparece impreso en el PDF y forma parte del código QR oficial de SUNAT.

## W

### Webhook
Notificación HTTP `POST` firmada con HMAC-SHA256 (`Faktura-Signature`) que Faktura envía a tu servidor apenas SUNAT acepta, observa, rechaza o anula un comprobante. Ver [Cómo funcionan los webhooks](https://faktura-doc.cgallardo.me/webhooks/).

## Anexo: Entornos: prueba y producción (de «Introducción»)

El entorno ante SUNAT lo decide **la API key**: el mismo código de integración sirve para ambos.

| API key | Envía a | Uso |
| --- | --- | --- |
| `sk_test_…` | SUNAT **beta** | Desarrollo y pruebas. Los comprobantes no tienen validez tributaria. |
| `sk_live_…` | SUNAT **producción** | Comprobantes reales. Requiere que tu empresa tenga certificado digital y usuario SOL configurados. Una clave de **solo consultas** (RUC y DNI) no los necesita. |

El entorno de **pruebas** (`https://faktura-test.cgallardo.me`) recibe cada versión antes de que llegue a producción y **solo acepta claves `sk_test_`**: una `sk_live_` responde `401`. Los ejemplos de esta documentación usan la URL de pruebas y una clave `sk_test_`. Para pasar a producción cambias dos cosas: la URL base por `https://faktura.cgallardo.me` y la clave por la `sk_live_`.

Una clave puede tener **fecha de vencimiento** (los accesos de prueba la tienen): al vencer responde `401` igual que una revocada, y hay que pedir otra.

Las series y la numeración son independientes por entorno: emitir en prueba nunca consume números de producción. Un comprobante emitido con una clave de prueba no es visible con una clave de producción, y viceversa.

## Anexo: Bienes y servicios sujetos a detracción (Catálogo 54) (de «Catálogos»)

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

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

## Anexo: Guías de remisión relacionadas (despatch_references) (de «Catálogos»)

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: Impuesto a las bolsas plásticas (ICBPER) (de «Cálculo de impuestos»)

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.

## Anexo: Recargo al consumo (de «Cálculo de impuestos»)

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

## Anexo: Retención del IGV (de «Descuentos, detracción y retención»)

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.

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