---
name: faktura-listar-comprobantes
description: "Listar comprobantes con la API de Faktura (facturación electrónica SUNAT, Perú). Comprobantes de tu empresa en el entorno de tu API key, del más reciente al más antiguo. Sirve para cuadrar la caja del día, conciliar estados o recuperar un… Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Listar comprobantes — Faktura API

## Propósito

Le da a tu asistente el contexto para **listar comprobantes** con la API de Faktura: Comprobantes de tu empresa en el entorno de tu API key, del más reciente al más antiguo. Sirve para cuadrar la caja del día, conciliar estados o recuperar un…

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

## Endpoint

| Ambiente | Petición |
| --- | --- |
| Pruebas | `GET https://faktura-test.cgallardo.me/v1/documents?document_type=03&from=2026-11-01&to=2026-11-30&page=1&page_size=50` |
| Producción | `GET https://faktura.cgallardo.me/v1/documents?document_type=03&from=2026-11-01&to=2026-11-30&page=1&page_size=50` |

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

## Parámetros

Todos son opcionales y se combinan entre sí.

| Parámetro | Descripción |
| --- | --- |
| `document_type` | `01`, `03`, `07` u `08`. |
| `series`, `number` | Serie (`B001`) y correlativo. |
| `status` | `pending`, `sending`, `uncertain`, `accepted`, `observed`, `rejected` o `failed`. |
| `from`, `to` | Rango de fechas de emisión `YYYY-MM-DD` (inclusive). |
| `customer_doc_number` | Documento del cliente. |
| `page`, `page_size` | Página (desde 1) y tamaño (1 a 100, 20 por defecto). |

## Ejemplo

```bash
curl "https://faktura-test.cgallardo.me/v1/documents?document_type=03&from=2026-11-01&to=2026-11-30&page=1&page_size=50" \
  -H "Authorization: Bearer sk_test_..."
```

### Buscar por serie y correlativo

```bash
curl "https://faktura-test.cgallardo.me/v1/documents?series=B001&number=1" \
  -H "Authorization: Bearer sk_test_..."
```

## Respuesta `200 OK`

```json
{
  "items": [
    {
      "id": "01a1d5fd-…", "document_type": "03", "series": "B001", "number": 2, "full_number": "B001-2",
      "issue_date": "2026-11-14", "currency": "PEN",
      "customer": { "doc_type": "DNI", "doc_number": "45678912", "name": "MARÍA PÉREZ" },
      "total": "9.00", "status": "accepted", "void": null,
      "links": { "self": "/v1/documents/01a1d5fd-…" }
    }
  ],
  "page": 1, "page_size": 50, "total_count": 1
}
```

| Campo | Tipo | Descripción |
| --- | --- | --- |
| `items[]` | lista | Resumen de cada comprobante de la página (`id`, `document_type`, `series`, `number`, `full_number`, `issue_date`, `currency`, `customer`, `total`, `status`, `void`, `links.self`). |
| `items[].total` | texto | Importe total del comprobante como texto decimal (`"9.00"`). El desglose completo de impuestos y líneas está en [Ver un comprobante](https://faktura-doc.cgallardo.me/endpoints/comprobantes/ver/). |
| `items[].void` | objeto o null | `null` si no se pidió anulación, o `{"status": "requested", "reason": "…"}` (donde `status` es `requested`, `voided` o `rejected`). |
| `page`, `page_size` | entero | Página devuelta y tamaño de página aplicado. |
| `total_count` | entero | Total de comprobantes que cumplen los filtros enviados. |

## Respuestas y errores

| Estado | `reason` | Causa |
| --- | --- | --- |
| `200` | — | Devuelve la página de comprobantes. |
| `401` | `Unauthenticated` | Falta la API key, es inválida o venció. |
| `403` | `ApiKeyScopeInsufficient` | La clave es de alcance `lookup`. |
| `422` | `ValidationFailed` | Un parámetro tiene un valor inválido (por ejemplo, `page_size` mayor a 100 o `to` anterior a `from`). |
| `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
