---
name: faktura-ejemplos-de-facturas
description: "Ejemplos de facturas con la API de Faktura (facturación electrónica SUNAT, Perú). Recetas listas para copiar y validadas ante SUNAT: solo cambia la API key, la serie y los datos del cliente por los tuyos. Los campos están explicados en Emi… Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Ejemplos de facturas — Faktura API

## Propósito

Le da a tu asistente el contexto para **ejemplos de facturas** con la API de Faktura: Recetas listas para copiar y validadas ante SUNAT: solo cambia la API key, la serie y los datos del cliente por los tuyos. Los campos están explicados en Emi…

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

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

Descuentos, detracción y retención tienen su propia [guía](https://faktura-doc.cgallardo.me/guias/descuentos-detraccion-retencion/), y la factura al crédito con cuotas también ([guía](https://faktura-doc.cgallardo.me/guias/factura-al-credito/)).

## Factura en dólares

Envía `"currency": "USD"` y los precios en dólares. Faktura calcula el IGV y los totales en esa moneda, y el importe en letras dice «DÓLARES AMERICANOS». No necesitas tipo de cambio, salvo que la factura lleve detracción.

```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-9001" \
  -d '{
    "series": "F001",
    "currency": "USD",
    "customer": { "doc_type": "RUC", "doc_number": "20100070970", "name": "CLIENTE S.A.C." },
    "items": [ { "description": "Licencia de software (anual)", "quantity": 1, "unit_price": 590 } ]
  }'
```

Respuesta `201 Created` (resumida):

```json
{
  "currency": "USD",
  "totals": {
    "taxed": "500.00", "exempt": "0.00", "unaffected": "0.00", "free": "0.00",
    "igv": "90.00", "icbper": "0.00", "total_taxes": "90.00", "discounts": "0.00", "charges": "0.00", "total": "590.00"
  },
  "amount_in_words": "SON QUINIENTOS NOVENTA CON 00/100 DÓLARES AMERICANOS"
}
```

## Precios sin IGV

Si tu sistema guarda los precios sin IGV, envía `"price_includes_tax": false`: Faktura suma el 18 % encima. Con `true` (por defecto), `unit_price` ya incluye el IGV.

```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-9002" \
  -d '{
    "series": "F001",
    "price_includes_tax": false,
    "customer": { "doc_type": "RUC", "doc_number": "20100070970", "name": "CLIENTE S.A.C." },
    "items": [ { "description": "Servicio de consultoría", "quantity": 10, "unit_price": 100, "unit_code": "HUR" } ]
  }'
```

Diez horas de S/ 100.00 sin IGV dan una base de S/ 1000.00 y un total de S/ 1180.00:

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

## Ítems gravados, exonerados e inafectos en la misma factura

Cada ítem lleva su `igv_type`. Sin él, el ítem es `gravado`. El IGV solo se calcula sobre los gravados. Qué productos están exonerados o inafectos lo decide la ley, no Faktura: consúltalo con tu contador.

```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-9003" \
  -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": 30, "igv_type": "exonerado" },
      { "description": "Producto inafecto", "quantity": 1, "unit_price": 50, "igv_type": "inafecto" }
    ]
  }'
```

Cada tipo va en su propio total y el IGV sale solo de la laptop:

```json
{
  "totals": {
    "taxed": "100.00", "exempt": "60.00", "unaffected": "50.00", "free": "0.00",
    "igv": "18.00", "icbper": "0.00", "total_taxes": "18.00", "discounts": "0.00", "charges": "0.00", "total": "228.00"
  }
}
```

## Entregas gratuitas (muestras o regalos)

Un ítem `gratuito` no se cobra: `unit_price` es su **valor referencial** (con IGV, salvo que envíes `price_includes_tax: false`). Su valor sin IGV aparece en `totals.free`, pero no suma al total. Usa `gratuito_exonerado` o `gratuito_inafecto` si el bien regalado está exonerado o inafecto. Los ítems gratuitos no admiten descuentos.

```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-9004" \
  -d '{
    "series": "F001",
    "customer": { "doc_type": "RUC", "doc_number": "20100070970", "name": "CLIENTE S.A.C." },
    "items": [
      { "description": "Caja de café 1 kg", "quantity": 5, "unit_price": 59 },
      { "description": "Taza de regalo", "quantity": 1, "unit_price": 23.60, "igv_type": "gratuito" }
    ]
  }'
```

La taza aparece en `free` por su valor sin IGV (23.60 / 1.18 = 20.00) y el cliente paga solo el café:

```json
{
  "totals": {
    "taxed": "250.00", "exempt": "0.00", "unaffected": "0.00", "free": "20.00",
    "igv": "45.00", "icbper": "0.00", "total_taxes": "45.00", "discounts": "0.00", "charges": "0.00", "total": "295.00"
  }
}
```

## Con orden de compra, guía de remisión y vencimiento

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

## Con fecha de emisión anterior (contingencia)

Si vendiste sin conexión, emite después con la fecha real de la venta en `issue_date`: hasta **3 días atrás**, nunca una fecha futura. En este ejemplo la venta fue el 11 de noviembre y se emite el 13; usa siempre una fecha dentro de ese plazo.

```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-9006" \
  -d '{
    "series": "F001",
    "issue_date": "2026-11-11",
    "customer": { "doc_type": "RUC", "doc_number": "20100070970", "name": "CLIENTE S.A.C." },
    "items": [ { "description": "Laptop", "quantity": 1, "unit_price": 118 } ]
  }'
```

```json
{
  "issue_date": "2026-11-11",
  "totals": {
    "taxed": "100.00", "exempt": "0.00", "unaffected": "0.00", "free": "0.00",
    "igv": "18.00", "icbper": "0.00", "total_taxes": "18.00", "discounts": "0.00", "charges": "0.00", "total": "118.00"
  }
}
```

## Anexo: Cuerpo (de «Emitir una boleta»)

#### Datos generales y del cliente

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `series` | texto | Sí | Serie de boleta creada para tu empresa en el entorno de la clave, p. ej. `B001`. |
| `currency` | texto | No | `PEN` (por defecto) o `USD`. En dólares el cliente debe identificarse siempre. |
| `price_includes_tax` | booleano | No | `true` por defecto: `unit_price` incluye IGV ([Cálculo de impuestos](https://faktura-doc.cgallardo.me/calculo-de-impuestos/)). |
| `issue_date` | fecha | No | Fecha de emisión `YYYY-MM-DD`: hoy (por defecto) o hasta 3 días atrás, para ventas registradas sin conexión o en contingencia. Nunca futura (`InvalidIssueDate`). |
| `due_date` | fecha | No | Fecha de vencimiento `YYYY-MM-DD`, igual o posterior a la emisión. |
| `customer.doc_type` | texto | Sí | `DNI`, `CE`, `PASAPORTE`, `RUC` o `NONE` ([Catálogos](https://faktura-doc.cgallardo.me/catalogos/)). |
| `customer.doc_number` | texto | Si no es `NONE` | Número de documento. |
| `customer.name` | texto | Si no es `NONE` | Nombre o razón social, hasta 200 caracteres. |
| `customer.address` | texto | No | Dirección, hasta 250 caracteres. |

#### Ítems (`items`)

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `items` | lista | Sí | Entre 1 y 500 ítems. |
| `items[].description` | texto | Sí | Hasta 500 caracteres. |
| `items[].quantity` | número o texto | Sí | Mayor que 0, hasta 10 decimales. |
| `items[].unit_price` | número o texto | Sí | Mayor que 0, hasta 10 decimales. En ítems gratuitos es el valor referencial. |
| `items[].igv_type` | texto | No | `gravado` (por defecto), `exonerado`, `inafecto`, `gratuito`, `gratuito_exonerado` o `gratuito_inafecto`. |
| `items[].icbper` | booleano | No | `true` para bolsas plásticas: agrega S/ 0.50 por unidad. |
| `items[].unit_code` | texto | No | Unidad de medida, `NIU` por defecto ([Catálogos](https://faktura-doc.cgallardo.me/catalogos/#unidad-de-medida-itemsunit_code)). |
| `items[].product_code` | texto | No | Tu código interno, hasta 30 caracteres. |
| `items[].sunat_product_code` | texto | No | Código de producto SUNAT (catálogo 25, UNSPSC) de 8 dígitos. |
| `items[].discount` | objeto | No | Descuento del ítem: `{"amount": 5}` o `{"percent": 10}`, nunca ambos. El monto va en los mismos términos que `unit_price` (con o sin IGV). No se admite en ítems gratuitos. |

#### Descuentos, recargo y datos comerciales

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `discount` | objeto | No | Descuento global, `{"amount": 10}` o `{"percent": 5}`. Rebaja la base de los ítems **gravados**: con precios con IGV, el total baja exactamente ese monto. |
| `service_charge` | objeto | No | Recargo al consumo `{"percent": 10}` o `{"amount": 5}` ([Cálculo de impuestos](https://faktura-doc.cgallardo.me/calculo-de-impuestos/#recargo-al-consumo)). |
| `purchase_order` | texto | No | Orden de compra del cliente, hasta 20 caracteres (letras, números y `-/._`). |
| `despatch_references` | lista | No | Hasta 10 guías de remisión relacionadas: `{"type": "09", "number": "T001-123"}` (o `"type": "31"`). Ver [Catálogos](https://faktura-doc.cgallardo.me/catalogos/#guías-de-remisión-relacionadas-despatch_references). |
| `observations` | texto | No | Hasta 500 caracteres; aparece en el XML y en el PDF. |

Sin `issue_date`, la fecha de emisión es el día actual en hora de Perú.

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