---
name: faktura-estados-y-envio-a-sunat
description: "Estados y envío a SUNAT con la API de Faktura (facturación electrónica SUNAT, Perú). La emisión responde de inmediato con el número asignado y status: \"pending\". El envío a SUNAT ocurre en segundo plano, con reintentos automáticos, así que tu… Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Estados y envío a SUNAT — Faktura API

## Propósito

Le da a tu asistente el contexto para **estados y envío a SUNAT** con la API de Faktura: La emisión responde de inmediato con el número asignado y status: "pending". El envío a SUNAT ocurre en segundo plano, con reintentos automáticos, así que tu…

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

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

## Estados

| `status` | Significado | ¿Final? |
| --- | --- | --- |
| `pending` | Numerado, **ya firmado** (la respuesta de la emisión trae `sunat.hash` y `links.xml`, para imprimir el ticket de inmediato) y en cola para enviar. También vuelve aquí si SUNAT no estaba disponible y se reintentará. | No |
| `sending` | Se está enviando en este momento. | No |
| `uncertain` | Se perdió la comunicación durante el envío y no se sabe si SUNAT lo recibió. El próximo intento verifica en SUNAT antes de reenviar. | No |
| `accepted` | SUNAT lo aceptó (CDR código `0`). | Sí |
| `observed` | SUNAT lo aceptó con observaciones (CDR código 4000 o mayor). Es válido; revisa `sunat.notes` para corregir en próximas emisiones. | Sí |
| `rejected` | SUNAT lo rechazó (código 2000–3999). **No es válido**: corrige los datos y emite un comprobante nuevo con otro número. | Sí |
| `failed` | No se pudo procesar por una causa que no se resuelve reintentando, como credenciales SOL inválidas o falta de perfil. Contacta a soporte con el `sunat.code`. | Sí |

```text
pending ──► sending ──► accepted | observed | rejected | failed
   ▲           │
   └───────────┤  SUNAT no disponible (reintento con espera creciente)
               ▼
           uncertain ──► (verifica en SUNAT) ──► sending …
```

## Reintentos automáticos

- Ante caídas de SUNAT, la API reintenta con espera creciente: 5 s, 10 s, 20 s… hasta 15 minutos entre intentos, durante varias horas.
- `sunat.send_attempts` cuenta los intentos realizados.
- Un comprobante `uncertain` nunca se reenvía a ciegas: en producción primero se consulta su CDR en SUNAT, para no duplicar ni perder la constancia original.

## Cómo saber cuándo terminó

Registra un [webhook](https://faktura-doc.cgallardo.me/webhooks/) para recibir `document.accepted`, `document.rejected` y los demás desenlaces apenas ocurran, o consulta [`GET /v1/documents/{id}`](https://faktura-doc.cgallardo.me/endpoints/comprobantes/ver/) con espera progresiva:

1. Primera consulta 1 segundo después de emitir. Lo normal es que ya esté en `accepted`.
2. Si sigue en `pending`, `sending` o `uncertain`, espera 2 s, 5 s, 10 s, 30 s y luego cada minuto.
3. No consultes en un bucle sin espera: cuenta para tu [límite de peticiones](https://faktura-doc.cgallardo.me/autenticacion/#límite-de-peticiones).

## ¿Puedo entregar el comprobante antes de que SUNAT lo acepte?

Sí. La normativa permite entregar la representación impresa al cliente en el momento de la venta, y enviar el comprobante a SUNAT dentro del plazo legal. La API se encarga del envío. Lo que sí debes vigilar son los comprobantes que terminen en `rejected` o `failed`.

## Anexo: Límite de peticiones (de «Autenticación»)

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.

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