La API de StampyWallet
BetaAñade visitas, crea clientes y recibe los eventos de tu tarjeta de fidelidad desde tu TPV, tu web o una herramienta sin código.
La API conecta StampyWallet con el resto de tu comercio. Funciona en los dos sentidos:
- Hacia StampyWallet: tu TPV, tu web o tu software de reservas añade una visita, crea un cliente o entrega una recompensa, sin escanear en el mostrador.
- Desde StampyWallet: en cada visita, tarjeta nueva o recompensa, StampyWallet llama a una dirección que tú eliges (un webhook). Es lo que alimenta una hoja de cálculo, un CRM o un escenario de Zapier.
Antes de empezar : la API, las direcciones de entrada de los TPV (Conectar tu TPV) y los webhooks están incluidos en el plan Crecimiento (40 € sin IVA al mes) y abiertos durante la prueba gratuita. Con el plan Esencial, las llamadas responden 403 con el código formule_requise.
Atención : la API está en beta. Las rutas y los campos descritos aquí son los de la implementación; pueden aparecer campos nuevos antes de la versión estable: ignora los que no conozcas. Los cambios se anuncian en las novedades.
La dirección base
Todas las rutas se sirven en HTTPS, en formato JSON (campos en francés, en snake_case), bajo:
https://app.stampywallet.com/v1Los identificadores son UUID; los importes van en la moneda del comercio, en unidades (12.5 para 12,50 €).
Una primera llamada
Crea una clave en Ajustes › Integraciones (ver Autenticación) y luego lee la ficha de tu comercio:
curl https://app.stampywallet.com/v1/commerce \
-H "Authorization: Bearer sw_live_votre_cle"const reponse = await fetch('https://app.stampywallet.com/v1/commerce', {
headers: { Authorization: `Bearer ${process.env.STAMPY_CLE}` },
});
console.log(await reponse.json());import os, requests
reponse = requests.get(
"https://app.stampywallet.com/v1/commerce",
headers={"Authorization": f"Bearer {os.environ['STAMPY_CLE']}"},
)
print(reponse.json())Lo que sabe hacer la API
| Ruta | Función |
|---|---|
GET /v1/commerce | Leer la ficha del comercio y las reglas de la tarjeta |
POST /v1/clients | Crear un cliente y obtener el enlace de su tarjeta |
GET /v1/clients | Buscar un cliente por teléfono, correo o tarjeta |
GET /v1/clients/:id | Leer un cliente y el estado de su tarjeta |
POST /v1/passages | Añadir una visita: un sello, o puntos según el importe |
DELETE /v1/passages/:id | Anular una visita |
POST /v1/recompenses | Entregar una recompensa ganada |
POST /v1/entrants/:jeton | Recibir las ventas de tu TPV (Square, Shopify, SumUp, Zettle o el formato genérico) |
Y en el otro sentido, los webhooks salientes: nueve eventos, firmados.
Consejo : ¿no tienes un desarrollador a mano? La página Conectar tu TPV da los ajustes paso a paso para Square, Shopify, SumUp y Zettle, y para Zapier, Make y n8n.
¿Y el MCP?
La API está pensada para el software: un TPV, una web, un script. Para gestionar tu comercio conversando, desde Claude, ChatGPT o Cursor, usa mejor el servidor MCP: no pide ninguna clave, solo conectar tu cuenta.
Preguntas frecuentes
¿Cuánto cuesta la API?
La API, las direcciones de entrada de los TPV y los webhooks están incluidos en el plan Crecimiento, a 40 € sin IVA al mes, y abiertos durante la prueba gratuita de 30 días. Con el plan Esencial, las llamadas responden 403.
¿Necesito un desarrollador para conectar mi TPV?
No para Square, Shopify, SumUp, Zettle, Zapier, Make o n8n: la página Conectar tu TPV da los ajustes paso a paso. Llamar a la API desde tu propio programa, en cambio, requiere a alguien que escriba código.
¿Hay un límite de llamadas?
Sí: 120 peticiones por minuto y por clave. Por encima, la respuesta es 429 con la cabecera Retry-After.
¿Una clave sirve para varios locales?
No. Una clave da acceso solo al comercio en el que se creó: crea una clave en cada local.
¿Cómo evito un sello doble cuando mi TPV reintenta?
Da una reference a cada visita, por ejemplo el número del ticket, y envía una cabecera Idempotency-Key en cada POST: un nuevo intento no sella dos veces.
Actualizado el