---
name: faktura-listar-webhooks
description: "Listar webhooks con la API de Faktura (facturación electrónica SUNAT, Perú). Devuelve los endpoints activos de tu empresa. El secret nunca vuelve a mostrarse: si lo perdiste, elimina el endpoint y regístralo de nuevo. Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Listar webhooks — Faktura API

## Propósito

Le da a tu asistente el contexto para **listar webhooks** con la API de Faktura: Devuelve los endpoints activos de tu empresa. El secret nunca vuelve a mostrarse: si lo perdiste, elimina el endpoint y regístralo de nuevo.

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

## Endpoint

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

## 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/webhooks -H "Authorization: Bearer sk_test_..."
```

## Respuesta `200 OK`

```json
{
  "items": [
    {
      "id": "01a1d6b2-4c1e-7f30-9a2b-5d8e7c6b1a00",
      "url": "https://erp.miempresa.pe/faktura/webhook",
      "events": ["document.accepted", "document.rejected"],
      "is_active": true,
      "created_at": "2026-11-13T22:00:00+00:00"
    }
  ]
}
```

| Campo | Descripción |
| --- | --- |
| `id` | Identificador del endpoint, para [eliminarlo](https://faktura-doc.cgallardo.me/webhooks/eliminar/). |
| `url` | URL que recibe los avisos. |
| `events` | Eventos suscritos ([lista de eventos](https://faktura-doc.cgallardo.me/webhooks/#eventos)). |
| `is_active` | `true` mientras recibe avisos. |
| `created_at` | Fecha de registro (UTC, ISO 8601). |

## Respuestas y errores

| Estado | `reason` | Significado |
| --- | --- | --- |
| `200` | — | Devuelve la lista de webhooks activos de tu empresa. |
| `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. |

## Anexo: Eventos (de «Cómo funcionan los webhooks»)

| Evento | Cuándo |
| --- | --- |
| `document.accepted` | SUNAT aceptó el comprobante. |
| `document.observed` | SUNAT lo aceptó con observaciones. |
| `document.rejected` | SUNAT lo rechazó. |
| `document.failed` | No se pudo procesar (credenciales, perfil SOL…). |
| `document.voided` | SUNAT aceptó la anulación. |
| `document.void_rejected` | SUNAT rechazó la anulación; el comprobante sigue vigente. |

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