---
name: faktura-registrar-un-webhook
description: "Registrar un webhook con la API de Faktura (facturación electrónica SUNAT, Perú). Guarda el secret: solo se muestra esta vez. Sirve para verificar la firma de cada aviso. Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Registrar un webhook — Faktura API

## Propósito

Le da a tu asistente el contexto para **registrar un webhook** con la API de Faktura: Guarda el secret: solo se muestra esta vez. Sirve para verificar la firma de cada aviso.

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

## Endpoint

| Ambiente | Petición |
| --- | --- |
| Pruebas | `POST https://faktura-test.cgallardo.me/v1/webhooks` |
| Producción | `POST 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 -X POST https://faktura-test.cgallardo.me/v1/webhooks \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://erp.miempresa.pe/faktura/webhook", "events": ["document.accepted", "document.rejected"] }'
```

## Cuerpo

| Campo | Obligatorio | Descripción |
| --- | --- | --- |
| `url` | Sí | HTTPS, accesible desde internet, sin usuario ni contraseña en la URL. |
| `events` | No | Lista de eventos; si se omite, recibe todos. |

## Respuesta `201 Created`

```json
{
  "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",
  "secret": "whsec_3f9c…"
}
```

**Guarda el `secret`: solo se muestra esta vez.** Sirve para [verificar la firma](https://faktura-doc.cgallardo.me/webhooks/#verificar-la-firma) de cada aviso.

## Errores

| Estado | `reason` | Causa |
| --- | --- | --- |
| `409` | `TooManyWebhooks` | Tu empresa ya tiene 10 endpoints, el máximo. Elimina uno antes de registrar otro. |
| `422` | `InvalidWebhookUrl` | La URL no es HTTPS, lleva usuario o contraseña, o apunta a una red privada. |
| `422` | `ValidationFailed` | Falta `url` o `events` trae un evento desconocido. |

Los eventos y el formato del aviso están en [Cómo funcionan los webhooks](https://faktura-doc.cgallardo.me/webhooks/).

## Anexo: Verificar la firma (de «Cómo funcionan los webhooks»)

`Faktura-Signature` contiene `t` (marca de tiempo Unix) y `v1` (HMAC-SHA256 en hexadecimal de `"<t>.<cuerpo>"` con tu `secret`). Verifica siempre sobre el **cuerpo crudo**, antes de convertirlo a JSON, y rechaza marcas de tiempo de más de 5 minutos para impedir repeticiones.

PHP:

```php
$body = file_get_contents('php://input');
preg_match('/^t=(\d+),v1=([0-9a-f]{64})$/', $_SERVER['HTTP_FAKTURA_SIGNATURE'] ?? '', $m);
$valid = $m
    && abs(time() - (int) $m[1]) <= 300
    && hash_equals(hash_hmac('sha256', $m[1].'.'.$body, getenv('FAKTURA_WEBHOOK_SECRET')), $m[2]);
if (! $valid) { http_response_code(400); exit; }
```

Node.js (Express):

```js
import crypto from 'node:crypto';

app.post('/faktura/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const [, t, v1] = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(req.get('Faktura-Signature') ?? '') ?? [];
  const expected = crypto.createHmac('sha256', process.env.FAKTURA_WEBHOOK_SECRET)
    .update(`${t}.${req.body}`).digest('hex');
  const valid = t && Math.abs(Date.now() / 1000 - Number(t)) <= 300
    && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
  if (!valid) return res.sendStatus(400);
  res.sendStatus(204);
  // procesar JSON.parse(req.body) en segundo plano
});
```

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