---
name: faktura-introduccion
description: "Introducción con la API de Faktura (facturación electrónica SUNAT, Perú). Todas las rutas de negocio llevan el prefijo de versión /v1. Dentro de v1 solo se agregan campos o endpoints nuevos; un cambio incompatible saldría en /v2 co… Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Introducción — Faktura API

## Propósito

Le da a tu asistente el contexto para **introducción** con la API de Faktura: Todas las rutas de negocio llevan el prefijo de versión /v1. Dentro de v1 solo se agregan campos o endpoints nuevos; un cambio incompatible saldría en /v2 co…

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

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

## URL base y versionado

| Entorno | URL base | Clave |
| --- | --- | --- |
| Pruebas | `https://faktura-test.cgallardo.me` | `sk_test_…` (SUNAT beta) |
| Producción | `https://faktura.cgallardo.me` | `sk_live_…` (SUNAT producción) |

Todas las rutas de negocio llevan el prefijo de versión `/v1`. Dentro de `v1` solo se agregan campos o endpoints nuevos; un cambio incompatible saldría en `/v2` con aviso previo (ver [Versiones](https://faktura-doc.cgallardo.me/versiones/)).

## Entornos: prueba y producció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.

## Formato

- Peticiones y respuestas en JSON UTF-8 (`Content-Type: application/json`).
- Nombres de campos en `snake_case`.
- **Montos en las respuestas como texto decimal** (`"16.00"`), para que ningún cliente pierda exactitud al leerlos como `float`. En las peticiones puedes enviarlos como número (`8.5`) o como texto (`"8.50"`).
- Fechas `YYYY-MM-DD` en hora de Perú (`America/Lima`).
- Identificadores UUID (`01a1d5fc-899b-720e-a6ea-03d37a346f81`).

## Cómo funciona una emisión

1. Envías `POST /v1/invoices` o `POST /v1/receipts`.
2. La API valida, calcula impuestos y totales, asigna el siguiente correlativo de la serie y responde de inmediato con `201` y `status: "pending"`. El número ya es tuyo y puedes imprimir el ticket.
3. En segundo plano, la API firma el XML, lo envía a SUNAT y guarda el CDR. Si SUNAT no responde, reintenta sola.
4. Consultas `GET /v1/documents/{id}` hasta ver un estado final (`accepted`, `observed`, `rejected` o `failed`).

El detalle de cada estado y la estrategia recomendada de consulta están en [Estados y envío a SUNAT](https://faktura-doc.cgallardo.me/estados-y-envio/).

## Correlación y soporte

Cada respuesta incluye la cabecera `X-Request-Id`. Puedes enviar tu propio identificador en esa cabecera (8 a 64 caracteres: letras, números y guiones) y la API lo reutiliza. Incluye ese valor cuando reportes un problema a soporte.

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