---
name: faktura-guia-tu-primera-boleta-en-10-minutos
description: "Guía: tu primera boleta en 10 minutos con la API de Faktura (facturación electrónica SUNAT, Perú). Necesitas la API key de prueba (sktest…) que te entregó Faktura. Todo lo de esta guía va a SUNAT beta y no tiene validez tributaria. Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Guía: tu primera boleta en 10 minutos — Faktura API

## Propósito

Le da a tu asistente el contexto para **guía: tu primera boleta en 10 minutos** con la API de Faktura: Necesitas la API key de prueba (sktest…) que te entregó Faktura. Todo lo de esta guía va a SUNAT beta y no tiene validez tributaria.

Instalación en Claude Code: guarda este archivo como `.claude/skills/faktura-guia-tu-primera-boleta-en-10-minutos/SKILL.md` en tu proyecto. Fuente: https://faktura-doc.cgallardo.me/guias/primera-boleta/

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

## 1. Verifica tu clave

```bash
export FAKTURA_KEY="sk_test_..."
curl https://faktura-test.cgallardo.me/v1/me -H "Authorization: Bearer $FAKTURA_KEY"
```

Debes ver tu RUC y `"sunat_environment": "beta"`. Si recibes `401`, revisa que copiaste la clave completa ([Autenticación](https://faktura-doc.cgallardo.me/autenticacion/)).

## 2. Mira tus series

```bash
curl https://faktura-test.cgallardo.me/v1/series -H "Authorization: Bearer $FAKTURA_KEY"
```

Anota el `code` de la serie con `document_type: "03"` (por ejemplo `B001`).

## 3. Emite la boleta

```bash
curl -X POST https://faktura-test.cgallardo.me/v1/receipts \
  -H "Authorization: Bearer $FAKTURA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: mi-primera-boleta-001" \
  -d '{
    "series": "B001",
    "customer": { "doc_type": "NONE" },
    "items": [ { "description": "Café americano", "quantity": 2, "unit_price": 8.00 } ]
  }'
```

La respuesta `201` trae el número asignado (`full_number`), los totales calculados (S/ 16.00, de los cuales S/ 2.44 son IGV), el total en letras y `status: "pending"`. Guarda el `id`.

## 4. Espera la respuesta de SUNAT

```bash
curl https://faktura-test.cgallardo.me/v1/documents/<id> -H "Authorization: Bearer $FAKTURA_KEY"
```

En uno o dos segundos verás `"status": "accepted"` y `"sunat": {"code": "0", "description": "La Boleta numero B001-1, ha sido aceptada", …}`.

## 5. Descarga el XML y el CDR

```bash
curl -OJ https://faktura-test.cgallardo.me/v1/documents/<id>/xml -H "Authorization: Bearer $FAKTURA_KEY"
curl -OJ https://faktura-test.cgallardo.me/v1/documents/<id>/cdr -H "Authorization: Bearer $FAKTURA_KEY"
```

## 6. Prueba los casos que tu POS va a encontrar

| Caso | Qué enviar | Qué esperar |
| --- | --- | --- |
| Cliente con DNI | `"customer": {"doc_type": "DNI", "doc_number": "45678912", "name": "MARIA PEREZ"}` | `201` |
| Venta de más de S/ 700 sin cliente | `"customer": {"doc_type": "NONE"}` con un total mayor | `422 ReceiptRequiresCustomerDocument` |
| Bolsa plástica | ítem con `"icbper": true` | S/ 0.50 más por bolsa en `totals.icbper` |
| Producto exonerado | ítem con `"igv_type": "exonerado"` | IGV 0 en esa línea |
| Reintento por corte de red | la misma petición con la misma `Idempotency-Key` | `200` con el mismo comprobante |

## 7. Pasa a producción

Cuando Faktura confirme que tu empresa tiene certificado digital y usuario SOL (`GET /v1/me` muestra `has_certificate` y `has_sol_credentials` en `true`) y tus series de producción, cambia la clave por la `sk_live_…`. El código no cambia.

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