---
name: faktura-como-funcionan-los-webhooks
description: "Cómo funcionan los webhooks con la API de Faktura (facturación electrónica SUNAT, Perú). En lugar de consultar GET /v1/documents/{id} hasta que SUNAT responda, registra una URL y Faktura te avisa con un POST firmado cada vez que un comprobante ll… Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Cómo funcionan los webhooks — Faktura API

## Propósito

Le da a tu asistente el contexto para **cómo funcionan los webhooks** con la API de Faktura: En lugar de consultar GET /v1/documents/{id} hasta que SUNAT responda, registra una URL y Faktura te avisa con un POST firmado cada vez que un comprobante ll…

Instalación en Claude Code: guarda este archivo como `.claude/skills/faktura-como-funcionan-los-webhooks/SKILL.md` en tu proyecto. Fuente: https://faktura-doc.cgallardo.me/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`.

## Eventos

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

## Cómo empezar

1. [Registra tu endpoint](https://faktura-doc.cgallardo.me/webhooks/registrar/) y guarda el `secret`.
2. Verifica la firma de cada aviso (abajo) y responde `2xx` en menos de 10 segundos.
3. [Lista](https://faktura-doc.cgallardo.me/webhooks/listar/) o [elimina](https://faktura-doc.cgallardo.me/webhooks/eliminar/) endpoints cuando lo necesites (hasta 10 por empresa).

## La petición que recibes

```http
POST /faktura/webhook HTTP/1.1
Content-Type: application/json
User-Agent: Faktura-Webhooks/1
Faktura-Event: document.accepted
Faktura-Event-Id: 01a1d6b3-0b7a-7d11-8e40-3a2f1c9d8e77
Faktura-Delivery: 01a1d6b3-0c11-72c5-a0f4-6b1e2d3c4f55
Faktura-Signature: t=1794600000,v1=5d41402abc4b2a76b9719d911017c592…

{
  "id": "01a1d6b3-0b7a-7d11-8e40-3a2f1c9d8e77",
  "type": "document.accepted",
  "created_at": "2026-11-13T22:00:01+00:00",
  "data": {
    "document_id": "01a1d5fc-899b-720e-a6ea-03d37a346f81",
    "document_type": "03",
    "full_number": "B001-1",
    "environment": "beta",
    "status": "accepted",
    "sunat_code": "0",
    "sunat_description": "La Boleta numero B001-1, ha sido aceptada",
    "void_status": null
  }
}
```

Responde con cualquier `2xx` en menos de 10 segundos. Haz el trabajo pesado después: guarda el evento y procésalo en segundo plano.

## Verificar la firma

`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
});
```

## Reintentos y duplicados

- Si tu endpoint no responde `2xx` (error, timeout o redirección, que no se sigue), Faktura reintenta con espera creciente: 5 s, 10 s, 20 s… hasta 15 minutos entre intentos, durante unas 4 horas.
- La entrega es **al menos una vez**: puedes recibir el mismo evento más de una vez. Usa `id` (igual a `Faktura-Event-Id`) para ignorar duplicados.
- El orden de llegada no está garantizado. Si dudas, consulta `GET /v1/documents/{id}`, que siempre tiene el estado 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
