---
name: faktura-versiones
description: "Versiones con la API de Faktura (facturación electrónica SUNAT, Perú). Funcionalidades previstas en la hoja de ruta de v1 (sin cambios incompatibles): Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Versiones — Faktura API

## Propósito

Le da a tu asistente el contexto para **versiones** con la API de Faktura: Funcionalidades previstas en la hoja de ruta de v1 (sin cambios incompatibles):

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

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

## Política

- La versión actual es **v1**. Dentro de v1 solo se agregan campos, endpoints y códigos de `reason` nuevos. Tu integración debe ignorar los campos que no conoce.
- Un cambio incompatible (quitar o renombrar un campo, cambiar un tipo) saldría en `/v2`, con al menos 6 meses de convivencia.

## Historial

| Fecha | Cambio |
| --- | --- |
| 2026-11-15 | `GET /v1/lookup/dni/{dni}`: consulta de DNI para personas naturales con negocio (RUC 10 en el padrón de SUNAT). `GET /v1/me` incorpora `api_key.scope` y `api_key.expires_at`. |
| 2026-11-14 | Firma inmediata al emitir (`sunat.hash` y `links.xml` desde la respuesta `201`), claves de alcance `lookup`, reenvío de comprobantes fallidos (`POST /v1/documents/{id}/retry`), formato `ticket58` (`links.public_ticket_58`) y `company.certificate_valid_until` en `/v1/me`. |
| 2026-11-14 | Emisión con `issue_date` (hasta 3 días atrás), tasa reducida de IGV (10.5 % para restaurantes y hoteles MYPE), recargo al consumo (`service_charge`), afectaciones `gratuito_exonerado` y `gratuito_inafecto`, motivos de nota de crédito 03, 04, 05, 08 y 13, descuentos por ítem y globales, detracción, retención del IGV, orden de compra, guías de remisión, listado `GET /v1/documents` y envío por correo (`POST /v1/documents/{id}/email`). |
| 2026-11-13 | Lanzamiento de **API v1**: facturas (`01`), boletas (`03`), notas de crédito (`07`), notas de débito (`08`), anulaciones (`RA` y `RC`), descargas de PDF (`a4` y `ticket`), XML y CDR, consultas de RUC individual y por lotes (`POST /v1/lookup/ruc`), webhooks firmados (`/v1/webhooks`), series (`/v1/series`), verificación de API key (`/v1/me`) e idempotencia. |

## Próximamente

Funcionalidades previstas en la hoja de ruta de **v1** (sin cambios incompatibles):

- Guía de remisión electrónica — remitente (`09`) y transportista (`31`).
- Facturas de exportación y operaciones con anticipos (incluidas notas de crédito de motivo `11`).
- Consulta de DNI para personas naturales sin RUC.
- Impuesto Selectivo al Consumo (ISC) e Impuesto a la Venta de Arroz Pilado (IVAP).
- Comprobantes de retención (`20`), percepción (`40`) y liquidación de compra (`04`).

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