Yapo para desarrolladores
Conecta tu tarjeta de lealtad con el resto de tu negocio. La API es de solo lectura: ningún sistema externo puede sumar sellos ni cambiar datos. Los avisos en tiempo real llegan por webhooks firmados.
Autenticación
El dueño del negocio crea un token en su panel, sección Integraciones, y elige qué puede leer: clientes, tarjetas, movimientos, programas, sedes u opiniones. El token se muestra una sola vez; guárdalo como una contraseña.
Envíalo en cada petición en la cabecera `Authorization: Bearer yapo_ext_…`. Un token revocado deja de funcionar al instante.
Rutas
Todas son GET y responden JSON. Las listas paginan con un cursor opaco: pide la siguiente página con `?cursor=` y el valor de `nextCursor`; cuando es null, terminaste. `limit` acepta hasta 100. Las listas muestran lo registrado hasta hace un minuto: así una sincronización incremental nunca se salta un movimiento que se confirmó tarde.
- /v1/ext/customers y /v1/ext/customers/{id}: nombre, correo, teléfono, segmento, nivel, consentimiento de promociones y respuestas del formulario de alta (permiso: clientes).
- /v1/ext/cards?customerId=: saldo, nivel y estado del pase (permiso: tarjetas).
- /v1/ext/ledger?since=&cardId=: movimientos en orden de registro, ideal para sincronizar (permiso: movimientos).
- /v1/ext/programs: programas y sus reglas vigentes (permiso: programas).
- /v1/ext/locations: sedes (permiso: sedes).
- /v1/ext/feedback: opiniones NPS (permiso: opiniones).
curl https://yapowallet.com/v1/ext/customers?limit=50 \
-H "Authorization: Bearer yapo_ext_…"
# Siguiente página: ?cursor=<nextCursor>
# Movimientos nuevos desde una fecha: /v1/ext/ledger?since=2026-10-01T00:00:00ZLímites y errores
Se permiten 120 peticiones por minuto desde cada IP; si te pasas, recibes 429. Los errores siguen el formato problem+json, con un `code` legible: `missing_scope` (falta el permiso), `invalid_token`, `invalid_cursor` o `not_found`.
Webhooks
En Integraciones, agrega la URL https de tu sistema y elige los eventos. Te enviamos un POST con JSON por cada evento, casi al instante. Si tu sistema no responde 2xx en 10 segundos, reintentamos con espera creciente durante 24 horas. Guardamos los eventos 7 días. Si un destino falla 3 días seguidos, lo desactivamos y avisamos al dueño por correo.
Eventos: customer.created, card.installed, card.removed, stamp.added, points.added, reward.unlocked, reward.redeemed, tier.changed, feedback.received, ledger.reversed (un reverso o reembolso) y balance.expired (saldo vencido). El botón «Enviar prueba» manda un evento ping.
Usa el `id` del evento para descartar duplicados: un reintento puede llegar dos veces.
{
"id": "0192f0c4-…",
"type": "stamp.added",
"createdAt": "2026-10-21T15:04:05.123Z",
"businessId": "0192e1aa-…",
"data": { "cardId": "…", "customerId": "…", "stamps": 1, "reason": "accrual", "locationId": "…", "occurredAt": "…" }
}Verificar la firma
Cada aviso trae la cabecera `Yapo-Signature: t=<segundos unix>,v1=<hex>`. El valor v1 es HMAC-SHA256 con tu secreto de firma sobre el texto `<t>.<cuerpo>`. Verifica sobre el cuerpo EXACTO que recibiste (antes de parsearlo) y rechaza los avisos con más de 5 minutos.
import { createHmac, timingSafeEqual } from 'node:crypto';
// header = req.headers['yapo-signature'] → "t=1767225600,v1=5f3c…"
export function verifyYapo(header, rawBody, secret, toleranceSec = 300) {
const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header ?? '');
if (!m) return false;
if (Math.abs(Date.now() / 1000 - Number(m[1])) > toleranceSec) return false;
const expected = createHmac('sha256', secret).update(`${m[1]}.${rawBody}`).digest();
const given = Buffer.from(m[2], 'hex');
return given.length === expected.length && timingSafeEqual(given, expected);
}Datos personales
La API entrega datos personales de los clientes del negocio. Úsalos solo para lo que el negocio te encargó, guárdalos de forma segura y borra lo que ya no necesites. El dueño puede revocar el token en cualquier momento.
¿Tienes un sistema de caja?
Estamos preparando conectores directos con Contífico, Loyverse, Odoo, Square y Shopify. Escríbenos si quieres probarlos primero.
Crear mi tarjeta gratis