---
name: faktura-series
description: "Series con la API de Faktura (facturación electrónica SUNAT, Perú). Lista las series activas de tu empresa en el entorno de tu API key, con el siguiente correlativo que se asignará. Las series las crea el equipo de Faktura al… Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Series — Faktura API

## Propósito

Le da a tu asistente el contexto para **series** con la API de Faktura: Lista las series activas de tu empresa en el entorno de tu API key, con el siguiente correlativo que se asignará. Las series las crea el equipo de Faktura al…

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

## Endpoint

| Ambiente | Petición |
| --- | --- |
| Pruebas | `GET https://faktura-test.cgallardo.me/v1/series` |
| Producción | `GET https://faktura.cgallardo.me/v1/series` |

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

```bash
curl https://faktura-test.cgallardo.me/v1/series -H "Authorization: Bearer sk_test_..."
```

## Respuesta `200 OK`

```json
{
  "items": [
    { "id": "01a1d52b-92d5-701b-9ee2-275218fd6f62", "document_type": "01", "code": "F001", "branch_code": "0000", "next_number": 1 },
    { "id": "01a1d52b-936e-707a-ae38-2a5f8d661979", "document_type": "03", "code": "B001", "branch_code": "0000", "next_number": 2 }
  ]
}
```

| Campo | Descripción |
| --- | --- |
| `document_type` | `01` factura, `03` boleta, `07` nota de crédito, `08` nota de débito. |
| `code` | Serie que envías en `series` al emitir (`F001`, `B001`, `FC01`, `BC01`, `FD01`, `BD01`). |
| `branch_code` | Código del establecimiento anexo ante SUNAT (`0000` es el domicilio fiscal). |
| `next_number` | Correlativo que recibirá la próxima emisión exitosa. Es informativo: con emisiones concurrentes puede avanzar entre la consulta y tu emisión. |

## Respuestas y errores

| Estado | `reason` | Significado |
| --- | --- | --- |
| `200` | — | Devuelve las series activas del emisor en el entorno de la clave. |
| `401` | `Unauthenticated` | Falta la API key, es inválida o venció. |
| `403` | `ApiKeyScopeInsufficient` | La clave es de alcance `lookup`. |
| `429` | `TooManyRequests` | Superaste las 120 peticiones por minuto. |

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