---
name: faktura-autenticacion
description: "Autenticación con la API de Faktura (facturación electrónica SUNAT, Perú). Cada petición a /v1 lleva tu API key como token Bearer: Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Autenticación — Faktura API

## Propósito

Le da a tu asistente el contexto para **autenticación** con la API de Faktura: Cada petición a /v1 lleva tu API key como token Bearer:

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

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

```http
GET /v1/me HTTP/1.1
Host: faktura-test.cgallardo.me
Authorization: Bearer sk_test_ec829766c02e_bb1f99a4b8069b5657d82bff324df39b08430f47c5b730fa98cc44ec8d991cd8
```

## Formato de la API key

```text
sk_test_ec829766c02e_bb1f99a4…cd8
└─┬───┘ └────┬─────┘ └────┬─────┘
 entorno  prefijo      secreto
```

- **Entorno**: `test` (SUNAT beta) o `live` (SUNAT producción). Ver [Introducción](https://faktura-doc.cgallardo.me/introduccion/#entornos-prueba-y-producción).
- **Prefijo** (`sk_test_ec829766c02e`): identifica la clave sin revelarla. Es lo que verás en los registros y lo que usas para pedir su revocación.
- **Secreto**: solo se muestra una vez, al emitir la clave. Faktura guarda únicamente un hash; si lo pierdes, se emite una clave nueva.

## Buenas prácticas

- Guarda la clave en tu servidor (variable de entorno o gestor de secretos). **Nunca** la pongas en una app móvil, en JavaScript del navegador ni en un repositorio.
- Usa una clave por sistema o por tienda (`POS tienda 1`, `ERP central`): así puedes revocar una sin afectar a las demás.
- Si un sistema solo consulta RUC o DNI, pide una clave de **alcance `lookup`**: llega a `/v1/me` y `/v1/lookup/*` y nada más (no emite, no anula ni lee comprobantes). Una clave `lookup` que intenta otra cosa recibe `403` `ApiKeyScopeInsufficient`. `/v1/me` informa el alcance en `api_key.scope`.
- Una clave revocada deja de funcionar en la siguiente petición.

## Respuestas de autenticación

| Situación | Estado | Cuerpo |
| --- | --- | --- |
| Falta la cabecera, el esquema no es `Bearer`, la clave está mal formada, no existe, fue revocada o la empresa está desactivada | `401` | `{"reason":"Unauthenticated"}` + cabecera `WWW-Authenticate: Bearer` |
| La clave es de alcance `lookup` y la ruta exige alcance completo | `403` | `{"reason":"ApiKeyScopeInsufficient"}` |
| Superaste el límite de peticiones | `429` | `{"reason":"TooManyRequests"}` + cabecera `Retry-After` (segundos) |

Todas las causas de rechazo devuelven el mismo `401` a propósito: así nadie puede averiguar si una clave existe o fue revocada.

## Límite de peticiones

Por defecto, **120 peticiones por minuto por API key**. Al superarlo recibes `429` con `Retry-After`; espera esos segundos antes de reintentar. Si tu operación necesita más, pide que se amplíe el límite de tu clave.

## Verificar tu clave

[`GET /v1/me`](https://faktura-doc.cgallardo.me/endpoints/me/) responde con tu empresa, el entorno de la clave y si ya tienes certificado y usuario SOL configurados. Es la forma más simple de probar la integración.

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

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