01 — Inicio rápido

Esta guía te lleva de cero a recibir tu primer evento de webhook, en cuatro pasos.

1. Crea una clave de API

Desde el panel administrativo (Integraciones → Claves de API, requiere rol ADMIN o superior), o vía la propia API si ya tienes una sesión de panel:

curl -X POST https://api.yallego.app/v1/api-keys \
  -H "Authorization: Bearer <tu_token_de_panel>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Integración POS",
    "scopes": ["transactions:read", "webhooks:write"]
  }'

{
  "id": "9f8c2a1e-4b7d-3f6a-8c2e-1b5d7f9a3c6e",
  "label": "Integración POS",
  "key": "yk_live_9f8c2a1e4b7d3f6a8c2e1b5d7f9a3c6e",
  "key_prefix": "yk_live_9f8c2a1e",
  "scopes": ["transactions:read", "webhooks:write"],
  "created_at": "2026-05-14T18:45:00Z"
}

El campo key se muestra una única vez. Guárdalo en un gestor de secretos — Yallegó solo conserva el key_prefix para que puedas identificar la clave en el listado. Si la pierdes, revócala y crea otra.

La prueba gratuita y el plan Free no incluyen acceso a la API pública (rate_limit_per_minute: 0) — necesitas plan Negocio o superior para crear claves de API. Negocio permite 2 claves, Comercio 10 y Cadena sin límite, aparte de los webhooks (ver 02 — Autenticación).

Toda clave opera sobre datos reales. Hoy solo existen claves yk_live_: lo que confirmes o reportes con ella cambia los cobros reales del comercio. Las claves de prueba yk_test_ llegarán con el modo de pruebas.

2. Haz tu primera solicitud

Empieza por verificar la clave: GET /v1/me dice a qué comercio pertenece, qué alcances tiene y cuál es su límite, sin consumir ese límite (ver 02 — Autenticación).

curl https://api.yallego.app/v1/me \
  -H "Authorization: Bearer yk_live_9f8c2a1e4b7d3f6a8c2e1b5d7f9a3c6e"

Luego consulta tus cobros:

curl https://api.yallego.app/v1/transactions?limit=5 \
  -H "Authorization: Bearer yk_live_9f8c2a1e4b7d3f6a8c2e1b5d7f9a3c6e"

{
  "data": [
    {
      "id": "...",
      "wallet": { "code": "YAPE", "display_name": "Yape" },
      "sender_name": "JUAN CARLOS PEREZ R.",
      "amount": "35.50",
      "currency": "PEN",
      "status": "CAPTURED",
      "occurred_at": "2026-05-14T18:32:07.412Z"
    }
  ],
  "pagination": { "has_more": false, "next_cursor": null, "limit": 5 }
}

Revisa las cabeceras de la respuesta — X-RateLimit-Remaining te dice cuántas solicitudes te quedan en la ventana actual (ver 09 — Límites de tasa).

3. Registra un webhook

Para recibir cobros en tiempo real sin hacer polling, registra un endpoint:

curl -X POST https://api.yallego.app/v1/webhooks \
  -H "Authorization: Bearer yk_live_9f8c2a1e4b7d3f6a8c2e1b5d7f9a3c6e" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://mi-sistema.pe/hooks/yallego",
    "subscribed_events": ["transaction.created"],
    "description": "Integración con sistema de ventas"
  }'

{
  "id": "...",
  "url": "https://mi-sistema.pe/hooks/yallego",
  "secret": "whsec_3f6a8c2e1b5d7f9a3c6e9f8c2a1e4b7d",
  "subscribed_events": ["transaction.created"],
  "is_enabled": true,
  "created_at": "2026-05-14T18:50:00Z"
}

Igual que la clave de API, el secret se muestra una única vez. Lo necesitas para verificar la firma de cada evento entrante — ver 07 — Verificación de firma.

La URL debe ser https:// y no puede apuntar a una red privada o interna (localhost, rangos 10.x/172.16-31.x/192.168.x, etc.) — la validación ocurre tanto al crear el endpoint como en cada intento de entrega.

4. Envía un evento de prueba

Antes de esperar un cobro real, confirma que tu endpoint responde correctamente:

curl -X POST https://api.yallego.app/v1/webhooks/{id}/test \
  -H "Authorization: Bearer yk_live_9f8c2a1e4b7d3f6a8c2e1b5d7f9a3c6e"

Esto envía un evento transaction.created con datos ficticios, firmado exactamente igual que un evento real. Verifica en tu servidor que:

Recibiste la solicitud POST.
La firma en X-Yallego-Signature es válida (ver guía 07).
Respondiste 2xx dentro de los 10 segundos de timeout.

Listo — ya puedes recibir cobros de Yape, Plin y BIM en tiempo real. Sigue con 02 — Autenticación para entender los alcances disponibles, o con 06 — Catálogo de eventos para ver qué otros eventos puedes suscribir.