---
name: faktura-idempotencia
description: "Idempotencia con la API de Faktura (facturación electrónica SUNAT, Perú). Una red inestable puede cortar la respuesta de una emisión que sí se registró. Si tu POS reintenta sin protección, emite el mismo ticket dos veces y consume… Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Idempotencia — Faktura API

## Propósito

Le da a tu asistente el contexto para **idempotencia** con la API de Faktura: Una red inestable puede cortar la respuesta de una emisión que sí se registró. Si tu POS reintenta sin protección, emite el mismo ticket dos veces y consume…

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

## 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
POST /v1/receipts HTTP/1.1
Authorization: Bearer sk_live_...
Idempotency-Key: pos-0042-20261113-000187
Content-Type: application/json
```

## Comportamiento

| Situación | Respuesta |
| --- | --- |
| Primera vez que usas la clave | `201 Created`: el comprobante nuevo. |
| Misma clave y **mismo cuerpo** | `200 OK` con cabecera `Idempotent-Replayed: true`: el **mismo** comprobante, sin emitir otro ni consumir otro número. |
| Misma clave y **otro cuerpo** | `409 Conflict` con `{"reason":"IdempotencyKeyReused"}`. |
| Dos peticiones simultáneas con la misma clave | Solo una emite; la otra recibe el mismo comprobante. |

## Reglas

- De 1 a 100 caracteres: letras, números, `_`, `-`, `.` y `:`. Otro formato responde `422 InvalidIdempotencyKey`.
- La clave es única por emisor y por entorno; no caduca.
- «Mismo cuerpo» significa el mismo JSON, sin importar el orden de las claves de los objetos.
- La cabecera es opcional, pero **muy recomendada** en todo sistema que reintente.

## Cómo construir la clave

Usa algo que identifique la venta en tu sistema y que no cambie entre reintentos:

```text
<caja>-<fecha>-<número de venta interno>   →   pos-0042-20261113-000187
<id de pedido>                              →   order_8f3a2c
```

No uses un valor aleatorio nuevo en cada reintento: eso anula la protección.

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