---
name: faktura-ejemplos-de-boletas
description: "Ejemplos de boletas con la API de Faktura (facturación electrónica SUNAT, Perú). Recetas listas para copiar y validadas ante SUNAT, igual que las de facturas. Los campos están explicados en Emitir una boleta. Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Ejemplos de boletas — Faktura API

## Propósito

Le da a tu asistente el contexto para **ejemplos de boletas** con la API de Faktura: Recetas listas para copiar y validadas ante SUNAT, igual que las de facturas. Los campos están explicados en Emitir una boleta.

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

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

La boleta más simple, sin datos del cliente, está en la [guía de la primera boleta](https://faktura-doc.cgallardo.me/guias/primera-boleta/); la boleta con bolsa plástica (ICBPER), en el [ejemplo de boletas](https://faktura-doc.cgallardo.me/endpoints/boletas/#ejemplo).

## Venta de más de S/ 700: cliente identificado

Una boleta sin documento del cliente (`NONE`) solo se admite hasta S/ 700.00. Por encima, identifica al cliente con DNI, CE, pasaporte o RUC; si no, la API responde `422 ReceiptRequiresCustomerDocument`.

```bash
curl -X POST https://faktura-test.cgallardo.me/v1/receipts \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pos-0042-000301" \
  -d '{
    "series": "B001",
    "customer": { "doc_type": "DNI", "doc_number": "45678912", "name": "MARIA PEREZ" },
    "items": [ { "description": "Refrigeradora 300 L", "quantity": 1, "unit_price": 1899 } ]
  }'
```

```json
{
  "totals": {
    "taxed": "1609.32", "exempt": "0.00", "unaffected": "0.00", "free": "0.00",
    "igv": "289.68", "icbper": "0.00", "total_taxes": "289.68", "discounts": "0.00", "charges": "0.00", "total": "1899.00"
  },
  "amount_in_words": "SON MIL OCHOCIENTOS NOVENTA Y NUEVE CON 00/100 SOLES"
}
```

## Restaurante: recargo al consumo

`service_charge` agrega el recargo al consumo (por ejemplo, 10 %). Se calcula sobre el valor de venta sin IGV, no forma parte de la base del IGV y se suma al total ([Cálculo de impuestos](https://faktura-doc.cgallardo.me/calculo-de-impuestos/#recargo-al-consumo)).

```bash
curl -X POST https://faktura-test.cgallardo.me/v1/receipts \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pos-0042-000302" \
  -d '{
    "series": "B001",
    "customer": { "doc_type": "NONE" },
    "items": [
      { "description": "Lomo saltado", "quantity": 2, "unit_price": 38 },
      { "description": "Chicha morada (jarra)", "quantity": 1, "unit_price": 18 }
    ],
    "service_charge": { "percent": 10 }
  }'
```

El recargo es el 10 % de la base sin IGV (79.66), va en `totals.charges` y en `service_charge`, y se suma al total:

```json
{
  "totals": {
    "taxed": "79.66", "exempt": "0.00", "unaffected": "0.00", "free": "0.00",
    "igv": "14.34", "icbper": "0.00", "total_taxes": "14.34", "discounts": "0.00", "charges": "7.97", "total": "101.97"
  },
  "service_charge": { "base_amount": "79.66", "amount": "7.97" }
}
```

## Boleta en dólares

En dólares el cliente debe estar identificado siempre, aunque el monto sea bajo.

```bash
curl -X POST https://faktura-test.cgallardo.me/v1/receipts \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pos-0042-000303" \
  -d '{
    "series": "B001",
    "currency": "USD",
    "customer": { "doc_type": "PASAPORTE", "doc_number": "X1234567", "name": "JOHN SMITH" },
    "items": [ { "description": "Tour Valle Sagrado", "quantity": 2, "unit_price": 45 } ]
  }'
```

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

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

```bash
curl -X POST https://faktura-test.cgallardo.me/v1/receipts \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pos-0042-000187" \
  -d '{
    "series": "B001",
    "customer": { "doc_type": "DNI", "doc_number": "45678912", "name": "MARIA PEREZ" },
    "items": [
      { "product_code": "CAF-01", "description": "Cafe americano", "quantity": 2, "unit_price": 8.00 },
      { "description": "Bolsa plastica", "quantity": 1, "unit_price": 0.10, "icbper": true }
    ]
  }'
```

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

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