L'API StampyWallet
BêtaAjoutez des passages, créez des clients et recevez les événements de votre carte de fidélité depuis votre caisse, votre site ou un outil sans code.
L'API relie StampyWallet au reste de votre commerce. Elle sert dans les deux sens :
- Vers StampyWallet : votre caisse, votre site ou votre logiciel de réservation ajoute un passage, crée un client ou offre une récompense, sans scanner au comptoir.
- Depuis StampyWallet : à chaque passage, nouvelle carte ou récompense, StampyWallet appelle une adresse de votre choix (un webhook). C'est ce qui alimente un tableur, un CRM ou un scénario Zapier.
Avant de commencer : l'API, les adresses d'entrée des caisses (Relier votre caisse) et les webhooks sont compris dans la formule Croissance (40 € HT par mois), et ouverts pendant l'essai gratuit. Avec la formule Essentiel, les appels répondent 403 avec le code formule_requise.
Attention : l'API est en bêta. Les routes et les champs décrits ici sont ceux de l'implémentation ; de nouveaux champs peuvent apparaître avant la version stable : ignorez ceux que vous ne connaissez pas. Les changements sont annoncés dans les nouveautés.
L'adresse de base
Toutes les routes sont servies en HTTPS, au format JSON (champs en français, en snake_case), sous :
https://app.stampywallet.com/v1Les identifiants sont des UUID ; les montants sont dans la devise du commerce, en unités (12.5 pour 12,50 €).
Un premier appel
Créez une clé dans Réglages › Intégrations (voir Authentification), puis lisez la fiche de votre commerce :
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())Ce que l'API sait faire
| Route | Rôle |
|---|---|
GET /v1/commerce | Lire la fiche du commerce et les règles de la carte |
POST /v1/clients | Créer un client et obtenir le lien de sa carte |
GET /v1/clients | Retrouver un client par téléphone, e-mail ou carte |
GET /v1/clients/:id | Lire un client et l'état de sa carte |
POST /v1/passages | Ajouter un passage : un tampon, ou des points selon le montant |
DELETE /v1/passages/:id | Annuler un passage |
POST /v1/recompenses | Offrir une récompense gagnée |
POST /v1/entrants/:jeton | Recevoir les ventes de votre caisse (Square, Shopify, SumUp, Zettle, ou le format générique) |
Et dans l'autre sens, les webhooks sortants : neuf événements, signés.
Astuce : pas de développeur sous la main ? La page Relier votre caisse donne les réglages pas à pas pour Square, Shopify, SumUp et Zettle, et pour Zapier, Make et n8n.
Et le MCP ?
L'API est faite pour les logiciels : une caisse, un site, un script. Pour piloter votre commerce en conversation, depuis Claude, ChatGPT ou Cursor, utilisez plutôt le serveur MCP : il ne demande aucune clé, seulement de connecter votre compte.
Questions fréquentes
Combien coûte l'API ?
L'API, les adresses d'entrée des caisses et les webhooks sont compris dans la formule Croissance, à 40 € HT par mois, et ouverts pendant l'essai gratuit de 30 jours. Avec la formule Essentiel, les appels répondent 403.
Faut-il un développeur pour relier ma caisse ?
Pas pour Square, Shopify, SumUp, Zettle, Zapier, Make ou n8n : la page Relier votre caisse donne les réglages pas à pas. Appeler l'API depuis votre propre logiciel demande en revanche quelqu'un qui écrit du code.
Y a-t-il une limite d'appels ?
Oui : 120 requêtes par minute et par clé. Au-delà, la réponse est 429 avec l'en-tête Retry-After.
Une clé sert-elle pour plusieurs établissements ?
Non. Une clé donne accès au seul commerce dans lequel elle a été créée : créez une clé dans chaque établissement.
Comment éviter un double tampon quand ma caisse réessaie ?
Donnez une reference à chaque passage, le numéro du ticket par exemple, et un en-tête Idempotency-Key sur chaque POST : un nouvel essai ne tamponne pas deux fois.
Mis à jour le