# Documentation StampyWallet

> La documentation de StampyWallet, la carte de fidélité dans Apple Wallet et Google Wallet pour les commerces de proximité : le guide du commerçant, le serveur MCP et ses outils, l'API et les webhooks, et le skill « belles cartes ».

Ce fichier rassemble toutes les pages de https://stampywallet.com/docs/ en texte. En cas de doute, la page en ligne fait foi.

---

# Bienvenue dans la documentation StampyWallet

StampyWallet est une carte de fidélité dans Apple Wallet et Google Wallet, sans application. Ici, tout ce qu'il faut pour la créer, la faire scanner au comptoir, et la piloter depuis un assistant IA ou votre caisse.

- [Guide du commerçant](https://stampywallet.com/docs/guide/creer-sa-carte/) : Créer sa carte, la scanner, faire revenir ses clients.
- [MCP et assistants IA](https://stampywallet.com/docs/mcp/brancher/) : Claude, ChatGPT, Cursor : brancher et utiliser chaque outil.
- [API et webhooks](https://stampywallet.com/docs/api/) : Relier StampyWallet à votre caisse, votre site ou Zapier.
- [skill.md](https://stampywallet.com/docs/skill/) : Apprendre à votre assistant à dessiner de belles cartes.

## Démarrage rapide

1. **Créez votre carte.** Le nom de votre commerce, votre type de carte, vos récompenses : quelques minutes sur [stampywallet.com](site:#inscription), 30 jours d'essai.
2. **Posez l'affichette au comptoir.** Vos clients scannent le QR et la carte arrive dans leur Wallet, sans application.
3. **Scannez à chaque passage.** Avec votre téléphone : la carte du client se met à jour toute seule.

## Par où commencer

- Vous ouvrez votre compte : [Créer sa carte en 5 minutes](https://stampywallet.com/docs/guide/creer-sa-carte/), puis [Les types de carte](https://stampywallet.com/docs/guide/types-de-carte/).
- Vous êtes au comptoir : [Scanner une carte](https://stampywallet.com/docs/guide/scanner/) et [Votre équipe](https://stampywallet.com/docs/guide/equipe/).
- Vous voulez faire revenir vos clients : [Messages et notifications](https://stampywallet.com/docs/guide/messages/), [Cartes cadeaux et forfaits](https://stampywallet.com/docs/guide/cartes-cadeaux-et-forfaits/), [Avis Google](https://stampywallet.com/docs/guide/avis-google/).
- Vous travaillez avec une IA : [brancher Claude, ChatGPT ou Cursor](https://stampywallet.com/docs/mcp/brancher/), et le [skill « belles cartes »](https://stampywallet.com/docs/skill/).
- Vous reliez une caisse ou un outil : [l'API et les webhooks](https://stampywallet.com/docs/api/).

> **Astuce :** cette documentation existe aussi en texte brut pour les assistants IA, à [/llms.txt](llms.txt) et [/docs/llms-full.txt](llms-full.txt).

## Questions fréquentes

**Mes clients doivent-ils installer une application ?**
Non. La carte s'ajoute à Apple Wallet ou à Google Wallet, déjà présents sur leur téléphone, en scannant le QR de votre affichette. Sans Wallet, le client reçoit sa carte par e-mail, avec un lien vers une carte web.

**Quel est le prix de StampyWallet ?**
La formule Essentiel coûte 20 € HT par mois pour un établissement, la formule Croissance 40 € HT par mois (messages automatiques, SMS, avis Google, API, caisses et webhooks), et la formule Réseau à partir de 90 € HT par mois. Les 30 premiers jours sont gratuits, avec toutes les fonctions Croissance et sans engagement.

**Faut-il un développeur ?**
Non. La carte, le scan au comptoir et les messages se règlent dans votre espace StampyWallet, sans code. L'API ne sert qu'à relier une caisse ou un logiciel, et pour Square, Shopify, SumUp, Zettle, Zapier, Make et n8n, la page [Relier votre caisse](https://stampywallet.com/docs/api/relier-votre-caisse/) donne les réglages pas à pas.

**Faut-il une tablette ou un lecteur au comptoir ?**
Non. Le scan se fait depuis le téléphone du commerce, un iPhone ou un Android, et chaque membre de l'équipe a son propre accès.

Source : https://stampywallet.com/docs/

---

# Créer sa carte en 5 minutes

Ouvrir son compte, choisir son type de carte, la personnaliser, l'essayer sur son téléphone et imprimer l'affichette du comptoir.

## 1. Ouvrir votre compte

Sur [stampywallet.com](site:#inscription), saisissez votre e-mail : un code à six chiffres vous arrive, sans mot de passe à inventer. Vous pouvez aussi continuer avec Google ou avec Apple.

L'essai dure **30 jours**, avec toutes les fonctions de la formule Croissance. Une carte bancaire est demandée pour le démarrer, et rien n'est débité pendant l'essai ; l'annulation se fait en un clic.

## 2. Votre commerce

Trois questions :

- **Le nom du commerce**, imprimé en haut de la carte.
- **Vous êtes** : café, boulangerie, restaurant, ongles et cils, institut, barbier, boutique ou autre. Ce choix propose des récompenses, un tampon et des couleurs adaptés.
- **Votre logo**, facultatif (PNG ou JPEG).

## 3. Choisir le type de carte

Trois types, chacun montré dans deux designs, déjà à votre nom et à vos couleurs :

| Type | Le client gagne | Idéal pour |
|---|---|---|
| **Tampons** | Une récompense au bout de N passages | Cafés, boulangeries, barbiers |
| **Plusieurs récompenses** | Des récompenses de plus en plus belles sur la même carte | Instituts, ongles, restaurants |
| **Points** | Des points à chaque passage, selon ce qu'il dépense | Paniers qui varient beaucoup |

Le détail de chaque type : [Les types de carte](https://stampywallet.com/docs/guide/types-de-carte/).

## 4. La personnaliser

L'écran suivant montre la carte en direct pendant que vous la réglez :

- **Vos récompenses** : jusqu'à huit, chacune avec une photo ou une icône.
- **La forme** de la carte, **la couleur** et **le logo**.
- **Proposer à vos clients de laisser leur numéro**, pour les SMS et les avis Google.

Tout se change ensuite à tout moment dans **Votre carte** : chaque changement s'enregistre tout seul et arrive sur les téléphones de vos clients.

## 5. L'essayer sur votre téléphone

« Votre carte est prête » : ajoutez la carte d'essai à votre propre téléphone, puis touchez **Tamponner**. Un vrai tampon arrive, avec sa notification, comme chez un client.

## 6. Imprimer l'affichette

Dans **Affichette**, téléchargez le QR code d'inscription :

- **Chevalet de comptoir (A5)** ou **petit format (A6)**, en PDF prêt à imprimer ;
- **le QR seul**, en PNG ou en SVG, pour un menu, une vitrine ou Canva ;
- **Me l'envoyer par e-mail**, pour l'imprimer depuis un autre appareil.

L'affichette mène à la page publique de votre carte, `stampywallet.com/rejoindre/<votre-lien>`. Ce lien peut devenir lisible (`/rejoindre/le-fournil`) dans **Votre carte › Le lien**, pour une bio Instagram ou un flyer. En changer ne casse rien : les affichettes déjà imprimées continuent de marcher.

## Ce que voit votre client

Il scanne l'affichette avec l'appareil photo de son téléphone, et une page s'ouvre avec sa carte :

- **Ajouter à Apple Wallet** ou **Ajouter à Google Wallet** : son téléphone propose le bon d'abord ;
- ou **recevoir sa carte par e-mail**, avec un lien vers une carte web.

Pas d'application, pas de compte à créer. Par défaut, seul son prénom est demandé.

> **Ce que vous demandez au client :** dans **Votre carte › Inscription des clients**, chaque champ est « non demandé », « facultatif » ou « obligatoire » : prénom, nom, anniversaire (le jour et le mois, jamais l'année), e-mail, téléphone. Demandez seulement ce qui vous sert : l'anniversaire pour le message d'anniversaire, l'e-mail ou le téléphone pour les avis Google et les SMS.

> **Astuce :** vous voulez qu'une IA dessine la carte pour vous, avec les photos de votre commerce ? Voyez le [skill « belles cartes »](https://stampywallet.com/docs/skill/) et l'outil [`concevoir_carte`](https://stampywallet.com/docs/mcp/outils/concevoir_carte/).

## Questions fréquentes

**Faut-il une carte bancaire pour l'essai ?**
Oui, une carte bancaire est demandée pour démarrer l'essai de 30 jours. Rien n'est débité pendant l'essai, et l'annulation se fait en un clic.

**La carte marche-t-elle sur iPhone et sur Android ?**
Oui. Sur iPhone, elle va dans Apple Wallet ; sur Android, dans Google Wallet : la page d'inscription propose le bon d'abord. Un client sans Wallet peut recevoir sa carte par e-mail, avec un lien vers une carte web.

**Puis-je modifier ma carte une fois lancée ?**
Oui, à tout moment dans **Votre carte**. Chaque changement s'enregistre tout seul et arrive sur les téléphones de vos clients.

**Quelles informations sont demandées à mes clients ?**
Par défaut, seulement leur prénom. Dans **Votre carte › Inscription des clients**, le nom, l'anniversaire (jour et mois, jamais l'année), l'e-mail et le téléphone peuvent être non demandés, facultatifs ou obligatoires.

**Mes affichettes imprimées marchent-elles si je change le lien ?**
Oui. Rendre le lien lisible dans **Votre carte › Le lien** ne casse rien : les affichettes déjà imprimées continuent de marcher.

Source : https://stampywallet.com/docs/guide/creer-sa-carte/

---

# Les types de carte

Une carte StampyWallet fonctionne selon l'un de trois modes, tampons, plusieurs récompenses (paliers) ou points, et chaque mode se décline en plusieurs formes.

## Quel mode choisir ?

| Mode | Le client gagne | Idéal pour |
|---|---|---|
| `tampons` | Un tampon par passage, une récompense au bout | Cafés, boulangeries, barbiers |
| `paliers` | Plusieurs récompenses de plus en plus belles, sur le même compteur | Instituts, ongles, fleuristes, restaurants |
| `points` | Des points à chaque passage, selon le montant ou la prestation | Épiceries, cavistes, paniers variables |

> **Note :** vous pouvez changer de mode plus tard, dans **Votre carte › Changer de type**. Aucun client ne perd sa progression : ses tampons restent sur sa carte (en points, ils comptent comme des points). Votre design et vos couleurs restent aussi.

## Tampons

Le classique de la carte en carton : un tampon par passage, une récompense au bout, puis la carte recommence. Le nombre de cases va de 2 à 50.

![Une carte de café à tampons, rendue par StampyWallet](https://stampywallet.com/assets/img/blog/cartes/cafe-tampons-fr.webp "Une carte à tampons, telle qu'elle apparaît dans le Wallet du client.")

Quatre formes : **cases** (la grille), **sans cases** (tampons semés), **objets** (de gros objets ombrés, idéal avec la photo de votre produit) et **cercles**.

## Plusieurs récompenses (paliers)

Jusqu'à huit récompenses sur le même compteur, par exemple un café à 5 passages, un croissant à 10, un petit-déjeuner à 20. Chaque palier a son seuil, son libellé et sa photo ou son icône.

![Une carte de boulangerie à plusieurs récompenses](https://stampywallet.com/assets/img/blog/cartes/boulangerie-paliers-fr.webp "Une carte à paliers : chaque récompense à son seuil, avec sa photo.")

Cinq formes en plus des tampons : **chemin** (une route où chaque passage fait avancer le client), **vitrine** (les récompenses côte à côte), **médailles**, **remplissage** (la prochaine récompense en grand, qui se colore) et **anneau**.

```text title="Demander à l'IA"
Dessine la carte de la Boulangerie Lemaire en paliers :
- 5 passages : un croissant
- 10 passages : une baguette tradition
- 20 passages : une galette des rois
```
```json title="JSON (concevoir_carte)"
{
  "nom": "Boulangerie Lemaire",
  "mode": "paliers",
  "paliers": [
    { "a": 5, "recompense": "Un croissant" },
    { "a": 10, "recompense": "Une baguette tradition" },
    { "a": 20, "recompense": "Une galette des rois" }
  ]
}
```

## Points

Des points à chaque passage, quand le panier varie beaucoup d'un client à l'autre. Les récompenses s'obtiennent à des seuils de points, avec les mêmes cinq formes que les paliers.

![Une carte à points d'un salon de thé](https://stampywallet.com/assets/img/blog/cartes/the-points-fr.webp "Une carte à points : la jauge avance selon ce que le client dépense.")

Dans **Votre carte › Plus de réglages › Les points** :

- **Points par visite** : la valeur proposée par défaut au scanner.
- **Valeurs rapides** : jusqu'à six raccourcis, posés d'un geste au comptoir.
- **Nom de vos points** : « points », « graines », « étoiles »…
- **Au montant du ticket** : un nombre de points par euro ; vous tapez le total du ticket au comptoir et le calcul se fait seul.

> **Attention :** en mode points, la valeur se choisit au comptoir à chaque scan, ou arrive toute seule depuis votre caisse avec l'[API](https://stampywallet.com/docs/api/ajouter-passage/).

## Les styles

Six collections habillent la carte : **Essentiel**, **Café classique**, **Botanique**, **Trattoria**, **Atelier** et **Pass** (comme un pass Apple Wallet : logo en grand, fond franc). Chacune propose plusieurs palettes, et la couleur peut aussi être libre.

## Les règles

Dans **Votre carte › Plus de réglages › Règles** :

- **Tampons offerts à l'inscription** : de 0 à 5. Une carte déjà entamée donne envie d'être finie.
- **Validité d'une récompense** : jamais, ou 1, 2, 3, 6 ou 12 mois après l'avoir gagnée.
- **Un tampon tous les…** : un montant (par exemple un tampon par tranche de 10 €). Vous tapez le total du ticket au comptoir.
- **Deux compteurs** : une gamme premium avec son propre objectif et sa récompense ; vous choisissez « normal » ou « premium » au scanner.

## Questions fréquentes

**Quelle différence entre tampons, paliers et points ?**
Avec les tampons, chaque passage donne un tampon et la carte pleine donne une récompense, puis elle recommence. Avec les paliers, jusqu'à huit récompenses de plus en plus belles s'échelonnent sur le même compteur. Avec les points, le client gagne des points selon le montant ou la prestation, et les récompenses s'obtiennent à des seuils de points.

**Puis-je changer de type de carte plus tard ?**
Oui, dans **Votre carte › Changer de type**. Aucun client ne perd sa progression : ses tampons restent sur sa carte, et comptent comme des points en mode points. Votre design et vos couleurs restent aussi.

**Combien de cases peut avoir une carte à tampons ?**
De 2 à 50 cases.

**Peut-on donner un tampon selon le montant du ticket ?**
Oui. La règle **Un tampon tous les…** donne par exemple un tampon par tranche de 10 € : vous tapez le total du ticket au comptoir. En mode points, **Au montant du ticket** donne un nombre de points par euro.

**Les trois types sont-ils compris dans la formule Essentiel ?**
Oui. Tampons, points et récompenses à paliers sont compris dans toutes les formules, dès Essentiel.

Source : https://stampywallet.com/docs/guide/types-de-carte/

---

# Scanner une carte au comptoir

Poser un tampon ou des points, offrir une récompense, annuler une erreur, retrouver un client sans caméra et continuer sans réseau.

Le scan se fait depuis le téléphone du commerce, un iPhone ou un Android, sans lecteur ni tablette. Chaque membre de l'équipe a son propre accès ([Votre équipe](https://stampywallet.com/docs/guide/equipe/)).

## Poser un tampon

1. **Ouvrez Scanner.** La caméra s'ouvre tout de suite.
2. **Visez la carte du client**, sur son téléphone (pas l'affichette).
3. **Vérifiez l'écran « Carte lue »** : le prénom et la progression, par exemple 7 → 8 sur 10.
4. **Touchez « Poser le tampon ».** La carte du client se met à jour dans son Wallet. « Ce n'est pas lui » annule la lecture.

![Le scan d'une carte au comptoir](https://stampywallet.com/assets/img/step-scan.webp "Le téléphone du commerce lit la carte dans le Wallet du client.")

**Plusieurs tampons d'un coup** : avant de viser, réglez le nombre avec − et +, jusqu'à 50. Si votre carte compte au montant (« un tampon tous les 10 € »), tapez plutôt le total du ticket. La valeur revient à 1 après chaque scan.

## Poser des points

Sur une carte à points, choisissez la valeur avant de viser : la valeur par défaut, une valeur rapide, ou « … » pour une autre. Avec la règle « au montant du ticket », basculez sur **Montant** et tapez le total : les points se calculent seuls.

## Offrir une récompense

Quand un passage fait gagner une récompense, l'écran affiche **Récompense atteinte** :

- **Offert** : vous la remettez maintenant ;
- **Plus tard** : elle reste sur la carte du client, prête pour son prochain passage.

S'il y a plusieurs récompenses à offrir, la suivante est proposée aussitôt.

## Annuler une erreur

Juste après un scan, la barre du bas propose **Annuler**.

- Le propriétaire et les responsables peuvent annuler à tout moment le dernier tampon d'un client, ou une récompense offerte.
- Un employé peut annuler sa propre action pendant **5 minutes**.
- Seul le dernier passage s'annule. Un tampon dont la récompense a déjà été offerte s'annule après la récompense.
- Une raison peut être donnée (mauvaise carte, scanné deux fois, mauvaise quantité, offerte par erreur). L'annulation est notée à votre nom.

## Le double scan

Par défaut, deux passages du même client à moins d'une minute et demie ne comptent qu'une fois : « Déjà tamponné il y a un instant ». Réglez ce délai dans **Réglages › Le comptoir › Deux passages du même client** : toujours compter, un par minute, par cinq minutes, par heure ou par demi-journée.

## Sans caméra : chercher un client

**Chercher un client** retrouve une carte par le prénom, le nom, l'e-mail, le téléphone ou le code imprimé sous le QR. La même recherche trouve aussi les cartes cadeaux (par leur code) et les forfaits. Le tampon passe ensuite par le même écran de confirmation.

## Sans réseau

Si le réseau ne répond pas, le tampon est gardé sur le téléphone (« Tampon enregistré, sera confirmé ») et part dès que la connexion revient, sans doublon. Le scanner s'ouvre même hors ligne, et la recherche de clients marche sur la liste gardée dans le téléphone.

> **Attention :** offrir une récompense et annuler un passage demandent du réseau.

> **Astuce :** installez le scanner comme une application : le navigateur le propose (« Installer l'app »), et il s'ouvre ensuite d'un geste, en plein écran.

## L'anniversaire au comptoir

Quand c'est l'anniversaire du client, l'écran le dit toujours. Si un cadeau d'anniversaire est ouvert sur sa carte, il s'affiche avec le bouton **Offre utilisée** (ou deux boutons quand le client choisit son cadeau). Voir [Messages et notifications](https://stampywallet.com/docs/guide/messages/#anniversaire).

Source : https://stampywallet.com/docs/guide/scanner/

---

# Votre équipe

Inviter vos employés et responsables, ce que chaque rôle peut faire, et suivre les tampons posés par chacun. Équipe illimitée dans toutes les formules.

Autant de comptes que de personnes au comptoir, sans supplément, dans toutes les formules. Chacun scanne depuis son propre téléphone, avec son propre accès.

## Les rôles

| Action | Propriétaire | Responsable | Employé |
|---|---|---|---|
| Tamponner une carte, offrir une récompense | Oui | Oui | Oui |
| Voir les chiffres et les clients | Oui | Oui | Non |
| Écrire aux clients | Oui | Oui | Non |
| Changer la carte et les réglages | Oui | Oui | Non |
| Inviter, retirer, gérer l'abonnement | Oui | Non | Non |

Un employé ne voit que le **Scanner** et son compte, plus les cartes cadeaux et les forfaits quand le commerce en vend. Un commerce garde toujours au moins un propriétaire.

## Inviter quelqu'un

1. **Ouvrez Votre équipe › Inviter quelqu'un** (propriétaire seulement).
2. **Choisissez le rôle** : employé ou responsable. Ajoutez un repère si vous voulez (« Julie, le matin »).
3. **Envoyez** : avec son e-mail, l'invitation part par e-mail ; sans e-mail, **Créer le lien** puis **Copier le lien**, à envoyer comme vous voulez.

Une invitation est valable **quatorze jours**. Vous pouvez la renvoyer ou la retirer tant qu'elle n'est pas utilisée. Une invitation de responsable envoyée à un e-mail ne s'accepte qu'avec cet e-mail.

## Changer un rôle, retirer quelqu'un

Dans **Votre équipe**, changez le rôle d'un membre ou retirez son accès : ses sessions se ferment aussitôt.

## Le suivi par personne

**Voir le suivi par personne** montre, sur 7 ou 30 jours, les tampons posés, les récompenses offertes et les annulations de chaque membre.

> **Astuce :** depuis un assistant IA connecté, l'outil [`equipe`](https://stampywallet.com/docs/mcp/outils/equipe/) liste l'équipe, invite et change les rôles, toujours après votre accord.

Source : https://stampywallet.com/docs/guide/equipe/

---

# Messages et notifications

Écrire à vos clients sur l'écran verrouillé de leur téléphone, cibler un groupe, programmer un envoi, et laisser partir seuls les rappels, la relance et l'anniversaire.

Une carte dans le Wallet peut afficher une notification sur l'écran verrouillé du client. C'est gratuit, dans toutes les formules, et c'est ce qui fait revenir.

## Envoyer un message

Dans **Notifications › Envoyer un message** :

- **180 caractères** au plus, avec un aperçu de ce que verra le client. Trois modèles pour démarrer.
- **Un message par jour** et par commerce, pour ne pas lasser vos clients.
- Avant l'envoi, l'écran dit combien de clients le recevront : ceux qui ont la carte dans un Wallet. Une carte web (reçue par e-mail) ne reçoit pas de notification.

**À qui** : tous vos clients, dans toutes les formules. Avec la formule Croissance, un groupe : pas venus depuis 30, 60 ou 90 jours, proches de la récompense, anniversaire ce mois-ci, meilleurs clients (les 20 % qui viennent le plus), nouveaux.

**Programmer** (Croissance) : choisissez le jour et l'heure de l'envoi, jusqu'à 60 jours à l'avance, entre 7 h et 22 h, à l'heure du commerce. Un message programmé se modifie, s'annule ou part tout de suite.

## Les messages automatiques

Formule Croissance, dans **Réglages** :

| Message | Quand il part | Par défaut |
|---|---|---|
| Plus qu'un tampon | Il ne manque qu'un passage pour la récompense | Activé |
| Votre récompense est là | Le client vient de gagner une récompense | Activé |
| La relance | Un habitué ne vient plus | Activée |
| L'anniversaire | Le jour de l'anniversaire du client | Activé |

Les deux rappels partent après le passage, au délai choisi : tout de suite, 30 minutes, 1 heure (par défaut), 3 heures ou le lendemain.

### La relance des clients perdus de vue

Un habitué est « perdu de vue » quand son absence dépasse son propre rythme de visite, ou, sans assez d'historique, le délai de votre commerce (proposé selon votre métier, réglable). Seuls les jours d'ouverture comptent : déclarez vos congés et jours de fermeture dans **Réglages › Vos fermetures** pour que personne ne soit relancé à votre retour. Une relance par absence ; son texte (180 caractères) est modifiable.

### L'anniversaire

Pour l'activer, demandez l'anniversaire à l'inscription ([ce que vous demandez au client](https://stampywallet.com/docs/guide/creer-sa-carte/)). Le jour venu, le client reçoit un message et son cadeau, valable 30 jours :

- **un message seulement** ;
- **une réduction** de 1 à 90 % sur chaque achat pendant 30 jours ;
- **1 acheté, 1 offert**, une fois ;
- **au choix du client**, entre la réduction et « 1 acheté, 1 offert », choisi au comptoir.

Un message par personne et par an, si le client s'est inscrit avant son anniversaire. Au comptoir, le scanner montre le cadeau avec le bouton **Offre utilisée**.

## Les heures calmes

Aucun message automatique n'arrive entre 21 h et 9 h par défaut. Un envoi tombé dans ce créneau est reporté, pas perdu.

## Notification, SMS, e-mail

- **La notification Wallet** est gratuite et illimitée, dans toutes les formules.
- **Le SMS** (Croissance) prend le relais quand la carte n'est pas dans un Wallet, pour les clients qui ont laissé leur numéro : 200 SMS par mois sont compris, étalés sur le mois, avec une réserve pour les messages importants. Pas de SMS le dimanche, les jours fériés ni hors de 8 h à 20 h, jamais plus de trois par semaine au même numéro, et jamais de promotion à qui l'a refusée.
- **L'e-mail** sert de secours pour les avis Google et l'anniversaire.

Le canal se règle par sorte de message dans **Réglages › Messages et SMS** : automatique (recommandé), notification seulement, SMS en secours, SMS d'abord, ou e-mail en secours.

## Ce que vos messages ont ramené

Avec la formule Croissance, un client sur dix, tiré au sort, ne reçoit ni les promotions ni la relance. Sept jours après chaque message, le **rapport** compare qui est revenu dans chaque groupe : l'écart est ce que le message a vraiment rapporté.

## Le bilan du lundi

Chaque lundi matin, le propriétaire reçoit par e-mail le bilan de la semaine : tampons, nouveaux clients, récompenses, et les clients perdus de vue. Pas de bilan pour une semaine sans activité.

> **Astuce :** depuis un assistant IA connecté : [`envoyer_message`](https://stampywallet.com/docs/mcp/outils/envoyer_message/) pour un message, [`regler_automatismes`](https://stampywallet.com/docs/mcp/outils/regler_automatismes/) pour les automatiques, [`fermetures`](https://stampywallet.com/docs/mcp/outils/fermetures/) pour les congés.

Source : https://stampywallet.com/docs/guide/messages/

---

# Cartes cadeaux et forfaits

Vendre des cartes cadeaux et des forfaits prépayés au comptoir, les envoyer dans le Wallet, puis les débiter au scan.

Deux produits de la formule Croissance, qui vivent dans le Wallet comme la carte de fidélité. Dans les deux cas, **vous encaissez à votre caisse, comme d'habitude** : StampyWallet ne prend pas le paiement et ne vend rien en ligne.

## Les cartes cadeaux

![Deux cartes cadeaux StampyWallet](https://stampywallet.com/assets/img/blog/cartes/cadeaux-duo-fr.webp "Une carte cadeau produit et une carte cadeau montant, aux couleurs du commerce.")

### Préparer la vente

Dans **Cartes cadeaux › Réglages** :

- **des produits**, avec leur prix et leur photo (jusqu'à 24) ;
- **des montants** (jusqu'à 8), et si vous voulez un montant libre ;
- **la validité** : 3, 6 ou 12 mois après la vente.

Puis **Mettre en vente**. La carte cadeau prend le logo et les couleurs de votre carte de fidélité.

### Vendre

1. **Encaissez** à votre caisse.
2. **Vendre une carte cadeau** : le produit ou le montant, « Pour », « De la part de », un petit mot. Un employé peut vendre aussi.
3. **Remettez-la** : un QR à scanner, un lien à partager (WhatsApp, SMS), ou StampyWallet l'envoie par SMS ou par e-mail.

Celui qui la reçoit l'ajoute à Apple Wallet ou Google Wallet, ou la garde sur sa page web.

### Utiliser au comptoir

Scannez la carte cadeau, ou cherchez son code à 8 caractères :

- une carte **produit** : **Offrir**, et elle est utilisée ;
- une carte **montant** : **Débiter** le montant voulu ; le solde avant et après s'affiche, et le solde se met à jour dans le Wallet.

Une carte déjà vendue reste honorée dans toutes les formules, même si vous arrêtez de vendre.

## Les forfaits prépayés

Dix séances, dix cafés, cinq soins : le client paie d'avance, et chaque passage décompte une unité.

- De 1 à 100 unités, avec le mot de votre choix (séance, soin, café…).
- Jusqu'à 12 modèles de forfaits, valables 1, 2, 3, 6 ou 12 mois, ou sans limite.
- Vente : encaissez, puis **J'ai encaissé, créer le forfait**. Le client reçoit son forfait dans son Wallet.
- Au comptoir : **Décompter 1 séance** (ou votre unité). Le dernier décompte s'annule pendant 24 heures.
- Le Wallet rappelle au client une semaine avant l'échéance, et quand il reste peu d'unités.

Source : https://stampywallet.com/docs/guide/cartes-cadeaux-et-forfaits/

---

# Avis Google

Demander un avis Google à chaque client au bon moment, avec un lien direct vers votre fiche, sans tri ni récompense, dans les règles de Google.

Avec la formule Croissance, StampyWallet demande un avis Google à vos clients, au moment où ils sont le plus contents : à leur première récompense, ou après quelques passages.

## Comment ça marche

- **Le même message pour tous**, avec le lien direct vers votre fiche Google.
- **Pas de note intermédiaire**, pas de tri des clients selon leur avis, **aucune récompense** contre un avis : ce sont les règles de Google, et StampyWallet les suit.
- **Une demande par client**, une seule fois.

## L'activer

1. **Collez votre lien d'avis Google** dans **Avis Google**. Sans lui, rien ne part. Vous le trouvez dans votre fiche Google, bouton « Demander des avis ».
2. **Demandez l'e-mail ou le téléphone** à l'inscription ([Créer sa carte](https://stampywallet.com/docs/guide/creer-sa-carte/)) : la demande part par SMS ou par e-mail.
3. **Choisissez le moment** : à la première récompense (par défaut) ou après un nombre de passages (3 par défaut).
4. **Choisissez le délai** après le passage : tout de suite, 30 minutes, 1 heure, 3 heures (par défaut) ou le lendemain. Les heures calmes s'appliquent.

> **Note :** la notification Wallet ne porte pas de lien. La demande part donc d'abord par SMS (dans votre budget de 200 SMS par mois), ou par e-mail selon votre réglage dans **Réglages › Messages et SMS**. Le lien est aussi au dos de la carte du client.

## Les chiffres

L'écran **Avis Google** montre les demandes envoyées et les clics vers Google sur les 30 derniers jours.

> **Astuce :** depuis un assistant IA connecté, l'outil [`avis_google`](https://stampywallet.com/docs/mcp/outils/avis_google/) lit ces chiffres et règle la demande.

Source : https://stampywallet.com/docs/guide/avis-google/

---

# Brancher un assistant IA

Le serveur MCP de StampyWallet relie Claude, ChatGPT, Cursor ou un agent à votre carte de fidélité. Une adresse, aucune clé, et rien ne change sans votre accord.

StampyWallet parle le **Model Context Protocol** (MCP), le standard qui permet à un assistant IA d'utiliser des outils. Une fois branché, vous pouvez demander en conversation : « dessine-moi une carte de fidélité », « combien de clients sont venus ce mois-ci ? », « préviens mes habitués que je ferme lundi ».

## L'adresse du serveur

```text title="Serveur MCP"
https://app.stampywallet.com/mcp
```

HTTP « streamable », réponses JSON, sans état. C'est la seule chose à donner à votre assistant.

**Claude**
**Paramètres › Connecteurs › Ajouter un connecteur personnalisé**, collez l'adresse. Le pas à pas : [Claude](https://stampywallet.com/docs/mcp/claude/).
**ChatGPT**
**Paramètres › Applications et connecteurs**, mode développeur, **Créer**, collez l'adresse. Le pas à pas : [ChatGPT](https://stampywallet.com/docs/mcp/chatgpt/).
**Cursor et agents**
```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "stampywallet": { "url": "https://app.stampywallet.com/mcp" }
  }
}
```
Le pas à pas, et Claude Code : [Cursor et agents](https://stampywallet.com/docs/mcp/cursor/).

## Sans compte, puis avec votre compte

Le serveur sert deux familles d'outils sur la même adresse :

- **Sans compte** : [`concevoir_carte`](https://stampywallet.com/docs/mcp/outils/concevoir_carte/) dessine une carte à l'image d'un commerce, [`simuler_fidelite`](https://stampywallet.com/docs/mcp/outils/simuler_fidelite/) chiffre ce qu'elle coûte, et [`creer_commerce`](https://stampywallet.com/docs/mcp/outils/creer_commerce/) la met en service et rend un lien pour en devenir propriétaire. Aucune connexion n'est demandée.
- **Avec votre compte** : vos chiffres, vos clients, vos messages, les avis Google, les réglages de la carte, l'affichette, l'équipe. Au premier appel, l'assistant ouvre la page de connexion StampyWallet (OAuth) : vous vous connectez, choisissez le commerce, et autorisez l'accès.

À l'écran d'autorisation, vous pouvez cocher **lecture seule** : l'assistant lit vos chiffres et vos réglages, mais ne peut rien changer. Les accès se gèrent dans **Réglages › Vos données › Assistants connectés**, où chaque assistant se coupe d'un clic.

| Portée | Ce qu'elle permet |
|---|---|
| `stampy.lecture` | Lire vos chiffres, vos clients (prénoms), vos réglages et votre carte |
| `stampy.ecriture` | Agir pour vous : messages aux clients, réglages, carte, équipe, toujours après votre accord dans la conversation |

## Rien ne change sans votre accord

Les outils qui écrivent prennent un paramètre `confirmer`, `false` par défaut. Appelés ainsi, ils ne font rien : ils rendent un **aperçu** (le texte exact d'un message et le nombre de destinataires, l'avant et l'après d'un réglage). L'assistant vous le montre, et ne rappelle l'outil avec `confirmer: true` qu'après votre « oui ».

> **Attention :** deux choses ne se font qu'au comptoir, en scannant la carte du client : **poser des tampons** et **offrir des récompenses**. Aucun outil MCP ne le fait. Pour les poser depuis une caisse, il y a l'[API](https://stampywallet.com/docs/api/ajouter-passage/).

## Les outils

| Outil | Compte | Effet |
|---|---|---|
| [`concevoir_carte`](https://stampywallet.com/docs/mcp/outils/concevoir_carte/) | Sans | Lecture seule |
| [`simuler_fidelite`](https://stampywallet.com/docs/mcp/outils/simuler_fidelite/) | Sans | Lecture seule |
| [`creer_commerce`](https://stampywallet.com/docs/mcp/outils/creer_commerce/) | Sans | Écrit (confirmer) |
| [`tableau_de_bord`](https://stampywallet.com/docs/mcp/outils/tableau_de_bord/) | Avec | Lecture seule |
| [`rentabilite`](https://stampywallet.com/docs/mcp/outils/rentabilite/) | Avec | Lecture seule |
| [`meilleurs_moments`](https://stampywallet.com/docs/mcp/outils/meilleurs_moments/) | Avec | Lecture seule |
| [`chercher_clients`](https://stampywallet.com/docs/mcp/outils/chercher_clients/) | Avec | Lecture seule |
| [`fiche_client`](https://stampywallet.com/docs/mcp/outils/fiche_client/) | Avec | Lecture seule |
| [`envoyer_message`](https://stampywallet.com/docs/mcp/outils/envoyer_message/) | Avec | Écrit (confirmer) |
| [`historique_messages`](https://stampywallet.com/docs/mcp/outils/historique_messages/) | Avec | Lecture seule |
| [`regler_automatismes`](https://stampywallet.com/docs/mcp/outils/regler_automatismes/) | Avec | Écrit (confirmer) |
| [`fermetures`](https://stampywallet.com/docs/mcp/outils/fermetures/) | Avec | Écrit (confirmer) |
| [`avis_google`](https://stampywallet.com/docs/mcp/outils/avis_google/) | Avec | Écrit (confirmer) |
| [`voir_carte`](https://stampywallet.com/docs/mcp/outils/voir_carte/) | Avec | Lecture seule |
| [`modifier_carte`](https://stampywallet.com/docs/mcp/outils/modifier_carte/) | Avec | Écrit (confirmer) |
| [`fiche_commerce`](https://stampywallet.com/docs/mcp/outils/fiche_commerce/) | Avec | Écrit (confirmer) |
| [`affichette`](https://stampywallet.com/docs/mcp/outils/affichette/) | Avec | Lecture seule |
| [`envoyer_affichette`](https://stampywallet.com/docs/mcp/outils/envoyer_affichette/) | Avec | Écrit (confirmer) |
| [`equipe`](https://stampywallet.com/docs/mcp/outils/equipe/) | Avec | Écrit (confirmer) |

Les outils qui demandent un compte suivent aussi votre rôle (un employé n'a accès à aucun ; [`equipe`](https://stampywallet.com/docs/mcp/outils/equipe/) est réservé au propriétaire) et votre formule (certains chiffres et les avis Google demandent Croissance).

## Essayer à la main

Le serveur répond à n'importe quel client MCP, ou à `curl` :

```bash title="curl"
curl https://app.stampywallet.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

Sans compte, les appels sont limités par adresse IP : au-delà, le serveur demande d'attendre quelques minutes.

## Questions fréquentes

**Faut-il une clé pour brancher le serveur MCP ?**
Non, aucune clé. Les outils sans compte marchent tout de suite ; pour vos chiffres et vos clients, l'assistant vous fait connecter votre compte StampyWallet au premier appel.

**Est-ce que ça marche avec ChatGPT gratuit ?**
Côté StampyWallet, rien n'est à payer pour brancher le serveur, et les outils sans compte sont ouverts à tous. Côté ChatGPT, le connecteur se crée en mode développeur, dont l'accès dépend de votre offre ChatGPT. Si la vôtre ne le propose pas, Claude, Cursor ou tout autre client MCP se branchent à la même adresse.

**L'assistant peut-il changer quelque chose sans mon accord ?**
Non. Les outils qui écrivent rendent d'abord un aperçu, et l'assistant ne les rappelle avec `confirmer: true` qu'après votre « oui ». Vous pouvez aussi n'autoriser que la lecture seule.

**L'assistant peut-il poser des tampons ?**
Non. Poser des tampons et offrir des récompenses se fait uniquement au comptoir, en scannant la carte du client. Depuis une caisse, c'est la route [Ajouter un passage](https://stampywallet.com/docs/api/ajouter-passage/) de l'API qui le fait.

**Comment couper l'accès d'un assistant ?**
Dans **Réglages › Vos données › Assistants connectés** : chaque assistant se coupe d'un clic.

Source : https://stampywallet.com/docs/mcp/brancher/

---

# Brancher Claude

Ajouter StampyWallet comme connecteur personnalisé dans Claude (web, ordinateur et mobile), puis connecter votre compte.

1. **Ouvrez Claude** (claude.ai ou l'application de bureau), puis **Paramètres › Connecteurs**.
2. **Ajouter un connecteur personnalisé.** Nom : `StampyWallet`. Adresse : `https://app.stampywallet.com/mcp`.
3. **Activez-le dans une conversation**, depuis le menu des outils sous la zone de saisie.
4. **Demandez** : « Dessine la carte de fidélité de mon café, Le Petit Zinc, 8 cafés achetés, le 9e offert. » Claude appelle [`concevoir_carte`](https://stampywallet.com/docs/mcp/outils/concevoir_carte/) et vous montre la carte.
5. **Pour vos chiffres et vos clients**, Claude vous propose de vous connecter : la page StampyWallet s'ouvre, vous choisissez le commerce et autorisez l'accès.

Sur une offre d'équipe, l'ajout d'un connecteur personnalisé peut être réservé aux administrateurs de l'organisation.

## Avec le skill

Ajoutez aussi le [skill « belles cartes »](https://stampywallet.com/docs/skill/) : Claude ira chercher les vraies photos du commerce et proposera au moins douze versions de la carte, tous types confondus.

## Exemples de demandes

- « Combien de clients sont venus ce mois-ci, et c'est mieux que le mois dernier ? » ([`tableau_de_bord`](https://stampywallet.com/docs/mcp/outils/tableau_de_bord/))
- « Qui sont mes habitués qui ne viennent plus ? » ([`chercher_clients`](https://stampywallet.com/docs/mcp/outils/chercher_clients/))
- « Préviens tous mes clients que je ferme du 24 au 31 décembre. » ([`fermetures`](https://stampywallet.com/docs/mcp/outils/fermetures/))
- « Passe ma carte en paliers : un café à 5, un croissant à 10. » ([`modifier_carte`](https://stampywallet.com/docs/mcp/outils/modifier_carte/))

Source : https://stampywallet.com/docs/mcp/claude/

---

# Brancher ChatGPT

Ajouter le serveur MCP de StampyWallet comme connecteur dans ChatGPT, puis connecter votre compte StampyWallet.

1. **Ouvrez ChatGPT sur le web**, puis **Paramètres › Applications et connecteurs**.
2. **Activez le mode développeur** dans les réglages avancés (selon votre offre, il peut être réservé aux administrateurs de l'espace).
3. **Créez un connecteur.** Nom : `StampyWallet`. Adresse du serveur MCP : `https://app.stampywallet.com/mcp`. Authentification : OAuth.
4. **Dans une conversation**, ajoutez StampyWallet depuis le menu « + », puis demandez : « Dessine la carte de fidélité de ma boulangerie. »
5. **Pour vos chiffres et vos clients**, ChatGPT affiche **Se connecter** : la page StampyWallet s'ouvre, vous choisissez le commerce et autorisez l'accès.

> **Note :** dans ChatGPT, certains outils s'affichent avec un écran à eux (la carte rendue, les chiffres). Les mêmes outils marchent partout ailleurs en texte et en données.

## Dans un Projet ChatGPT

Collez le contenu du [skill.md](https://stampywallet.com/docs/skill/) dans les instructions d'un Projet : chaque conversation du projet suivra la méthode des belles cartes.

Source : https://stampywallet.com/docs/mcp/chatgpt/

---

# Brancher Cursor et les agents

Déclarer le serveur MCP de StampyWallet dans Cursor, Claude Code, VS Code ou tout agent compatible MCP.

Tout client MCP qui parle HTTP « streamable » se branche avec la même adresse : `https://app.stampywallet.com/mcp`. La connexion au compte passe par OAuth (enregistrement dynamique, PKCE) : le client ouvre la page StampyWallet dans votre navigateur au premier outil qui en a besoin.

**Cursor**
Dans **Cursor Settings › MCP › Add new MCP server**, ou dans le fichier du projet :
```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "stampywallet": { "url": "https://app.stampywallet.com/mcp" }
  }
}
```
**Claude Code**
```bash title="Terminal"
claude mcp add --transport http stampywallet https://app.stampywallet.com/mcp
```
Puis `/mcp` dans Claude Code pour vous connecter à votre compte.
**VS Code**
```json title=".vscode/mcp.json"
{
  "servers": {
    "stampywallet": { "type": "http", "url": "https://app.stampywallet.com/mcp" }
  }
}
```
**Autre agent**
Déclarez un serveur MCP distant de type HTTP à l'adresse `https://app.stampywallet.com/mcp`. Les métadonnées OAuth sont publiées à `https://app.stampywallet.com/.well-known/oauth-protected-resource`.

## Un agent qui dessine des cartes

Donnez à l'agent l'adresse brute du skill, `https://stampywallet.com/docs/skill.md`, et demandez : « Lis ce skill, puis dessine les cartes de fidélité de ce commerce : [nom, ville, lien Instagram]. » Voir [skill.md](https://stampywallet.com/docs/skill/).

Source : https://stampywallet.com/docs/mcp/cursor/

---

# concevoir_carte

Sans compte · Lecture seule.

Dessine une carte de fidélité StampyWallet (Apple Wallet et Google Wallet) pour un commerce, sans compte et sans rien enregistrer. À utiliser quand quelqu’un veut une carte de fidélité, fidéliser ses clients, ou voir à quoi ressemblerait sa carte. Tous les paramètres sont facultatifs : sans eux, une carte adaptée au métier est proposée. Le logo (logo_url) et la photo de chaque récompense (paliers[].image_url) se donnent par leur adresse https ; ils sont montrés sur l’aperçu, sans être enregistrés. Rappeler l’outil avec les réglages rendus, modifiés, pour affiner. Quand la personne est satisfaite, proposer creer_commerce avec les mêmes réglages.

## Paramètres

- `nom` (string, ≤ 80 caractères, facultatif) : Nom du commerce, imprimé en haut de la carte.
- `metier` (enum, facultatif) : Type de commerce. Choisit un style, un tampon et une récompense de départ adaptés quand ils ne sont pas précisés. « autre » : instituts, ongles, fleuristes, coiffeurs, épiceries… Valeurs : cafe, boulangerie, restaurant, autre.
- `mode` (enum, facultatif) : tampons : une récompense à un seuil (le plus simple). paliers : plusieurs récompenses sur la même carte (ex. 5 et 10). points : le commerçant saisit un nombre de points à chaque passage (paniers variables). Valeurs : tampons, paliers, points.
- `recompense` (string, ≤ 120 caractères, facultatif) : La récompense (mode tampons). Ignorée si « paliers » est donné.
- `tampons` (integer, 2…30, facultatif) : Nombre de passages pour obtenir la récompense (mode tampons), de 2 à 30.
- `paliers` (array<object>, ≤ 6, facultatif) : Les récompenses et leurs seuils (modes paliers et points). Du plus petit au plus grand.
- `paliers[].a` (integer, 1…1000000, requis) : Seuil : nombre de tampons (ou de points en mode points) pour obtenir ce palier.
- `paliers[].recompense` (string, ≤ 120 caractères, requis) : Ce que le client reçoit, tel qu’imprimé sur la carte. Ex. « Un café offert ».
- `paliers[].icone` (enum, facultatif) : Icône du palier (défaut : cadeau). Valeurs : etincelle, eclat, goutte, main, pinceau, oeil, ciseaux, sechoir, fleur, lotus, coeur, etoile, diamant, couronne, soleil, lune, talon, robe, sac, serviette, cafe, grain, the, cookie, gateau, pain, part, burger, glace, bol, plat, verre, biere, bulles, cocktail, cerises, orange, avocat, piment, oeuf, poisson, fromage, popcorn, feuille, flamme, eclair, sourire, patte, chien, chat, cadeau, haltere, velo, livre, note, appareil, palette, dent, parapluie, ballon, tshirt, basket, croissant.
- `paliers[].image_url` (string, ≤ 2000 caractères, facultatif) : Photo de la récompense, par son adresse https (PNG, JPEG ou WebP, 5 Mo au plus, 64 px de côté au moins). Détourée quand c’est possible, elle prend la place de l’icône sur la carte : en gris avant d’être gagnée, en couleur après. Dessinée en modes paliers et points.
- `collection` (enum, facultatif) : Style de la carte : original (sobre), cafe (cadre fin), botanique (italique, feuillages), trattoria (festonné), atelier (moderne), pass (comme un pass Apple Wallet : logo en grand, tampons en objets ombrés, fond franc). Valeurs : original, cafe, botanique, trattoria, atelier, pass.
- `palette` (integer, 0…3, facultatif) : Palette de la collection : 0, 1 ou 2 (chaque collection en propose trois ; pass en propose une quatrième, 3). Ignorée si « couleur » est donnée.
- `couleur` (string, facultatif) : Couleur de fond libre, en hexadécimal. L’encre (texte) est choisie automatiquement pour rester lisible.
- `tampon` (enum, facultatif) : Le signe posé à chaque passage. « rond » : le point simple. Beauté : etincelle, eclat, goutte, main, pinceau, oeil, ciseaux, sechoir, fleur, lotus, coeur, etoile, diamant, couronne, soleil, lune, talon, robe, sac, serviette. Food : cafe, grain, the, cookie, gateau, pain, part, burger, glace, bol, plat, verre, biere, bulles, cocktail, cerises, orange, avocat, piment, oeuf, poisson, fromage, popcorn. Divers : feuille, flamme, eclair, sourire, patte, chien, chat, cadeau, haltere, velo, livre, note, appareil, palette, dent, parapluie, ballon, tshirt, basket. Valeurs : rond, etincelle, eclat, goutte, main, pinceau, oeil, ciseaux, sechoir, fleur, lotus, coeur, etoile, diamant, couronne, soleil, lune, talon, robe, sac, serviette, cafe, grain, the, cookie, gateau, pain, part, burger, glace, bol, plat, verre, biere, bulles, cocktail, cerises, orange, avocat, piment, oeuf, poisson, fromage, popcorn, feuille, flamme, eclair, sourire, patte, chien, chat, cadeau, haltere, velo, livre, note, appareil, palette, dent, parapluie, ballon, tshirt, basket, croissant.
- `tampons_bienvenue` (integer, 0…5, facultatif) : Tampons offerts à l’inscription du client (0 à 5). 1 par défaut : une carte entamée donne envie d’être finie.
- `nom_des_points` (string, ≤ 20 caractères, facultatif) : Mode points : comment s’appellent les points (« points », « graines », « étoiles »…).
- `forme_paliers` (enum, facultatif) : Mode paliers : le dessin de la carte. tampons (défaut) : les tampons en grille, chaque récompense à la place du tampon de son seuil. Ou l’une des cinq formes des points, qui compte alors des tampons : medailles (une jauge et une médaille par récompense), vitrine (les récompenses côte à côte, chacune sa jauge), remplissage (la prochaine récompense en grand, qui se colore), chemin (une route en S où chaque tampon fait avancer le curseur), anneau (une jauge ronde autour de la prochaine récompense). Les photos des récompenses se déposent dans l’application, page Carte. Valeurs : tampons, medailles, vitrine, remplissage, chemin, anneau.
- `forme_points` (enum, facultatif) : Mode points : le dessin de la carte. medailles (défaut) : une jauge épaisse et une grande médaille par récompense. vitrine : les récompenses côte à côte, chacune sa petite jauge. remplissage : la prochaine récompense en grand, qui se colore à mesure. chemin : une route en S, les récompenses en étapes. anneau : une jauge ronde autour de la prochaine récompense, la liste à côté. Les photos des récompenses se déposent dans l’application, page Carte. Valeurs : medailles, vitrine, remplissage, chemin, anneau.
- `forme` (enum, facultatif) : Le dessin de la carte, en un mot (remplace forme_points et forme_paliers). Modes points et paliers : medailles (une jauge et une grande médaille par récompense), vitrine (les récompenses côte à côte, chacune sa jauge), remplissage (la prochaine récompense en grand, qui se colore), chemin (une route en S, chaque passage fait avancer le curseur), anneau (une jauge ronde autour de la prochaine récompense). Modes tampons et paliers : la disposition des tampons, grille (défaut), libre (semés), objets (gros objets ombrés, idéal avec une photo), cercles. En paliers, une disposition garde les tampons et pose chaque récompense à la place du tampon de son seuil. Une des cinq formes sans mode donné passe la carte en mode paliers. Valeurs : medailles, vitrine, remplissage, chemin, anneau, grille, libre, objets, cercles.
- `encre` (string, facultatif) : Couleur du texte de la carte, en hexadécimal (défaut : choisie pour rester lisible sur le fond).
- `accent` (string, facultatif) : Couleur d’accent : les tampons posés, les jauges, les étiquettes, en hexadécimal (défaut : tirée de la collection).
- `logo_url` (string, ≤ 2000 caractères, facultatif) : Logo du commerce, par son adresse https (PNG, JPEG ou WebP, 5 Mo au plus) : sa photo de profil Instagram fait l’affaire. Détouré quand c’est possible, posé en haut de la carte ; sans couleur, palette, encre ni accent donnés, la carte prend les couleurs du logo.
- `variantes` (boolean, facultatif) : true : rend aussi les trois palettes de la collection choisie, pour proposer un choix. Défaut : false.
- `tampons_poses` (integer, 0…1000000, facultatif) : Tampons déjà posés sur l’aperçu, pour montrer une carte en cours (défaut : tampons de bienvenue + 2).

## Exemple

Prompt : « Dessine la carte de fidélité de la Boulangerie Lemaire : 10 passages, la 10e baguette offerte, style pass, avec son logo. »

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "concevoir_carte",
    "arguments": {
      "nom": "Boulangerie Lemaire",
      "metier": "boulangerie",
      "mode": "tampons",
      "tampons": 10,
      "recompense": "La 10e baguette offerte",
      "collection": "pass",
      "logo_url": "https://example.com/logo-lemaire.png",
      "variantes": true
    }
  }
}
```

Source : https://stampywallet.com/docs/mcp/outils/concevoir_carte/

---

# simuler_fidelite

Sans compte · Lecture seule.

Estime ce que coûte une carte de fidélité à tampons (la récompense rapportée au panier) et combien de visites en plus la rentabilisent. À utiliser pour choisir une récompense et un nombre de passages, ou quand quelqu’un se demande si une carte vaut le coup. Sans compte.

## Paramètres

- `panier_moyen` (number, 0.5…10000, requis) : Dépense moyenne d’un client par passage, en euros.
- `cout_recompense` (number, 0…10000, requis) : Ce que coûte la récompense AU COMMERÇANT (prix de revient, pas prix de vente), en euros.
- `tampons` (integer, 2…30, requis) : Passages pour obtenir la récompense.
- `tampons_bienvenue` (integer, 0…5, facultatif) : Tampons offerts à l’inscription. Défaut : 1.
- `marge` (number, 1…100, facultatif) : Marge brute sur un panier, en pourcentage (défaut 65 %, typique en restauration et services). Défaut : 65.
- `clients_fideles` (integer, 1…100000, facultatif) : Clients qui prendraient la carte chaque mois (défaut 60). Défaut : 60.
- `visites_par_mois` (number, 0.1…60, facultatif) : Visites par mois d’un client fidèle aujourd’hui (défaut 2). Défaut : 2.
- `comparer` (array<integer>, ≤ 5, facultatif) : Autres nombres de passages à comparer (ex. [6, 10, 12]).

## Exemple

Prompt : « Mon panier moyen est de 6 €, un café me coûte 0,40 €. Combien coûte une carte à 10 passages, et est-ce mieux à 8 ou 12 ? »

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "simuler_fidelite",
    "arguments": {
      "panier_moyen": 6,
      "cout_recompense": 0.4,
      "tampons": 10,
      "comparer": [
        8,
        12
      ]
    }
  }
}
```

Source : https://stampywallet.com/docs/mcp/outils/simuler_fidelite/

---

# creer_commerce

Sans compte · Écrit (confirmer).

Crée le commerce sur StampyWallet avec la carte conçue (mêmes paramètres que concevoir_carte), et rend un lien personnel pour en devenir propriétaire : la personne clique, se connecte avec son e-mail, et retrouve tout en place (carte, QR à imprimer, essai gratuit). Le logo (logo_url) et la photo de chaque récompense (paliers[].image_url), donnés par leur adresse https, sont posés sur la carte. Sans compte. Appeler d’abord avec confirmer=false pour montrer le récapitulatif, puis avec confirmer=true une fois que la personne a dit oui.

## Paramètres

- `nom` (string, ≤ 80 caractères, requis) : Nom du commerce, imprimé en haut de la carte.
- `metier` (enum, facultatif) : Type de commerce. Choisit un style, un tampon et une récompense de départ adaptés quand ils ne sont pas précisés. « autre » : instituts, ongles, fleuristes, coiffeurs, épiceries… Valeurs : cafe, boulangerie, restaurant, autre.
- `mode` (enum, facultatif) : tampons : une récompense à un seuil (le plus simple). paliers : plusieurs récompenses sur la même carte (ex. 5 et 10). points : le commerçant saisit un nombre de points à chaque passage (paniers variables). Valeurs : tampons, paliers, points.
- `recompense` (string, ≤ 120 caractères, facultatif) : La récompense (mode tampons). Ignorée si « paliers » est donné.
- `tampons` (integer, 2…30, facultatif) : Nombre de passages pour obtenir la récompense (mode tampons), de 2 à 30.
- `paliers` (array<object>, ≤ 6, facultatif) : Les récompenses et leurs seuils (modes paliers et points). Du plus petit au plus grand.
- `paliers[].a` (integer, 1…1000000, requis) : Seuil : nombre de tampons (ou de points en mode points) pour obtenir ce palier.
- `paliers[].recompense` (string, ≤ 120 caractères, requis) : Ce que le client reçoit, tel qu’imprimé sur la carte. Ex. « Un café offert ».
- `paliers[].icone` (enum, facultatif) : Icône du palier (défaut : cadeau). Valeurs : etincelle, eclat, goutte, main, pinceau, oeil, ciseaux, sechoir, fleur, lotus, coeur, etoile, diamant, couronne, soleil, lune, talon, robe, sac, serviette, cafe, grain, the, cookie, gateau, pain, part, burger, glace, bol, plat, verre, biere, bulles, cocktail, cerises, orange, avocat, piment, oeuf, poisson, fromage, popcorn, feuille, flamme, eclair, sourire, patte, chien, chat, cadeau, haltere, velo, livre, note, appareil, palette, dent, parapluie, ballon, tshirt, basket, croissant.
- `paliers[].image_url` (string, ≤ 2000 caractères, facultatif) : Photo de la récompense, par son adresse https (PNG, JPEG ou WebP, 5 Mo au plus, 64 px de côté au moins). Détourée quand c’est possible, elle prend la place de l’icône sur la carte : en gris avant d’être gagnée, en couleur après. Dessinée en modes paliers et points.
- `collection` (enum, facultatif) : Style de la carte : original (sobre), cafe (cadre fin), botanique (italique, feuillages), trattoria (festonné), atelier (moderne), pass (comme un pass Apple Wallet : logo en grand, tampons en objets ombrés, fond franc). Valeurs : original, cafe, botanique, trattoria, atelier, pass.
- `palette` (integer, 0…3, facultatif) : Palette de la collection : 0, 1 ou 2 (chaque collection en propose trois ; pass en propose une quatrième, 3). Ignorée si « couleur » est donnée.
- `couleur` (string, facultatif) : Couleur de fond libre, en hexadécimal. L’encre (texte) est choisie automatiquement pour rester lisible.
- `tampon` (enum, facultatif) : Le signe posé à chaque passage. « rond » : le point simple. Beauté : etincelle, eclat, goutte, main, pinceau, oeil, ciseaux, sechoir, fleur, lotus, coeur, etoile, diamant, couronne, soleil, lune, talon, robe, sac, serviette. Food : cafe, grain, the, cookie, gateau, pain, part, burger, glace, bol, plat, verre, biere, bulles, cocktail, cerises, orange, avocat, piment, oeuf, poisson, fromage, popcorn. Divers : feuille, flamme, eclair, sourire, patte, chien, chat, cadeau, haltere, velo, livre, note, appareil, palette, dent, parapluie, ballon, tshirt, basket. Valeurs : rond, etincelle, eclat, goutte, main, pinceau, oeil, ciseaux, sechoir, fleur, lotus, coeur, etoile, diamant, couronne, soleil, lune, talon, robe, sac, serviette, cafe, grain, the, cookie, gateau, pain, part, burger, glace, bol, plat, verre, biere, bulles, cocktail, cerises, orange, avocat, piment, oeuf, poisson, fromage, popcorn, feuille, flamme, eclair, sourire, patte, chien, chat, cadeau, haltere, velo, livre, note, appareil, palette, dent, parapluie, ballon, tshirt, basket, croissant.
- `tampons_bienvenue` (integer, 0…5, facultatif) : Tampons offerts à l’inscription du client (0 à 5). 1 par défaut : une carte entamée donne envie d’être finie.
- `nom_des_points` (string, ≤ 20 caractères, facultatif) : Mode points : comment s’appellent les points (« points », « graines », « étoiles »…).
- `forme_paliers` (enum, facultatif) : Mode paliers : le dessin de la carte. tampons (défaut) : les tampons en grille, chaque récompense à la place du tampon de son seuil. Ou l’une des cinq formes des points, qui compte alors des tampons : medailles (une jauge et une médaille par récompense), vitrine (les récompenses côte à côte, chacune sa jauge), remplissage (la prochaine récompense en grand, qui se colore), chemin (une route en S où chaque tampon fait avancer le curseur), anneau (une jauge ronde autour de la prochaine récompense). Les photos des récompenses se déposent dans l’application, page Carte. Valeurs : tampons, medailles, vitrine, remplissage, chemin, anneau.
- `forme_points` (enum, facultatif) : Mode points : le dessin de la carte. medailles (défaut) : une jauge épaisse et une grande médaille par récompense. vitrine : les récompenses côte à côte, chacune sa petite jauge. remplissage : la prochaine récompense en grand, qui se colore à mesure. chemin : une route en S, les récompenses en étapes. anneau : une jauge ronde autour de la prochaine récompense, la liste à côté. Les photos des récompenses se déposent dans l’application, page Carte. Valeurs : medailles, vitrine, remplissage, chemin, anneau.
- `forme` (enum, facultatif) : Le dessin de la carte, en un mot (remplace forme_points et forme_paliers). Modes points et paliers : medailles (une jauge et une grande médaille par récompense), vitrine (les récompenses côte à côte, chacune sa jauge), remplissage (la prochaine récompense en grand, qui se colore), chemin (une route en S, chaque passage fait avancer le curseur), anneau (une jauge ronde autour de la prochaine récompense). Modes tampons et paliers : la disposition des tampons, grille (défaut), libre (semés), objets (gros objets ombrés, idéal avec une photo), cercles. En paliers, une disposition garde les tampons et pose chaque récompense à la place du tampon de son seuil. Une des cinq formes sans mode donné passe la carte en mode paliers. Valeurs : medailles, vitrine, remplissage, chemin, anneau, grille, libre, objets, cercles.
- `encre` (string, facultatif) : Couleur du texte de la carte, en hexadécimal (défaut : choisie pour rester lisible sur le fond).
- `accent` (string, facultatif) : Couleur d’accent : les tampons posés, les jauges, les étiquettes, en hexadécimal (défaut : tirée de la collection).
- `logo_url` (string, ≤ 2000 caractères, facultatif) : Logo du commerce, par son adresse https (PNG, JPEG ou WebP, 5 Mo au plus) : sa photo de profil Instagram fait l’affaire. Détouré quand c’est possible, posé en haut de la carte ; sans couleur, palette, encre ni accent donnés, la carte prend les couleurs du logo.
- `panier_moyen` (number, 0.5…10000, facultatif) : Dépense moyenne d’un client, en euros (sert aux estimations du tableau de bord).
- `langue` (enum, facultatif) : Langue des textes rendus. Par défaut, celle du commerce. Valeurs : fr, en, es.
- `confirmer` (boolean, facultatif) : false (défaut) : rend seulement un aperçu de ce qui serait fait, sans rien changer. true : exécute. Toujours montrer l’aperçu à la personne et attendre son accord avant de repasser avec true. Défaut : false.

## Exemple

Prompt : « C'est parfait, mets cette carte en service pour la Boulangerie Lemaire. »

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "creer_commerce",
    "arguments": {
      "nom": "Boulangerie Lemaire",
      "metier": "boulangerie",
      "mode": "tampons",
      "tampons": 10,
      "recompense": "La 10e baguette offerte",
      "collection": "pass",
      "confirmer": false
    }
  }
}
```

Source : https://stampywallet.com/docs/mcp/outils/creer_commerce/

---

# tableau_de_bord

Avec compte · Lecture seule.

Les chiffres de fidélité du commerce sur une période au choix : passages en caisse, clients venus, nouveaux clients, taux de retour, récompenses gagnées et offertes, chiffre estimé, avec une courbe par jour, semaine ou mois et, au besoin, la comparaison avec la période précédente de même durée. À utiliser pour « comment ça marche ce mois-ci ? », « combien de clients en août ? », « est-ce que ça monte ? ». Pour la liste des clients, utiliser chercher_clients ; pour savoir si la carte rapporte, rentabilite.

## Paramètres

- `periode` (enum, facultatif) : Période étudiée, en jours du fuseau du commerce, aujourd’hui inclus pour les périodes en cours (ce_mois = du 1er à aujourd’hui). « personnalisee » utilise du/au. Défaut derniers_30_jours. Valeurs : aujourdhui, hier, derniers_7_jours, derniers_30_jours, derniers_90_jours, derniers_12_mois, cette_semaine, semaine_derniere, ce_mois, mois_dernier, cette_annee, annee_derniere, depuis_le_debut, personnalisee. Défaut : "derniers_30_jours".
- `du` (string (date), facultatif) : Premier jour inclus (AAAA-MM-JJ). Le donner suffit : la période devient « personnalisee ».
- `au` (string (date), facultatif) : Dernier jour inclus (AAAA-MM-JJ). Défaut : aujourd’hui.
- `comparer` (boolean, facultatif) : Ajoute la variation par rapport à la période de même durée juste avant (ex. 30 jours avant les 30 derniers jours). Défaut : true.
- `indicateurs` (array<enum>, ≤ 9, facultatif) : Indicateurs à rendre, dans cet ordre. Défaut : tous. taux_retour = part des clients venus sur la période qui étaient déjà venus avant ; chiffre_estime = passages × panier moyen déclaré (une estimation, pas une caisse). Valeurs : passages, clients_venus, nouveaux_clients, taux_retour, passages_par_client, recompenses_gagnees, recompenses_offertes, chiffre_estime, total_clients.
- `courbe` (enum, facultatif) : Ce que trace la courbe. Défaut passages. Valeurs : passages, clients_venus, nouveaux_clients, recompenses_gagnees, recompenses_offertes, aucune. Défaut : "passages".
- `granularite` (enum, facultatif) : Pas de la courbe. auto (défaut) : jour jusqu’à 2 mois, semaine jusqu’à ~9 mois, mois au-delà. Valeurs : auto, jour, semaine, mois. Défaut : "auto".

## Exemple

Prompt : « Comment ça marche ce mois-ci, par rapport au mois dernier ? »

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tableau_de_bord",
    "arguments": {
      "periode": "ce_mois",
      "comparer": true
    }
  }
}
```

Source : https://stampywallet.com/docs/mcp/outils/tableau_de_bord/

---

# rentabilite

Avec compte · Lecture seule · Formule Croissance.

Dit si la carte de fidélité rapporte, sur une période au choix : part des clients qui reviennent, passages de retour et ce qu’ils représentent en euros (estimation : passages × panier moyen), rythme médian entre deux visites, récompenses offertes et leur coût si on le donne, récompenses encore à servir, et résultat de la relance automatique. Le panier moyen et le coût d’une récompense peuvent être ajustés pour refaire le calcul. À utiliser pour « est-ce que ça vaut le coup ? », « ça me rapporte combien ? », « mes clients reviennent-ils ? ». Pour les chiffres bruts d’une période, tableau_de_bord.

## Paramètres

- `periode` (enum, facultatif) : Période étudiée, en jours du fuseau du commerce, aujourd’hui inclus pour les périodes en cours (ce_mois = du 1er à aujourd’hui). « personnalisee » utilise du/au. Défaut derniers_90_jours. Valeurs : aujourdhui, hier, derniers_7_jours, derniers_30_jours, derniers_90_jours, derniers_12_mois, cette_semaine, semaine_derniere, ce_mois, mois_dernier, cette_annee, annee_derniere, depuis_le_debut, personnalisee. Défaut : "derniers_90_jours".
- `du` (string (date), facultatif) : Premier jour inclus (AAAA-MM-JJ). Le donner suffit : la période devient « personnalisee ».
- `au` (string (date), facultatif) : Dernier jour inclus (AAAA-MM-JJ). Défaut : aujourd’hui.
- `panier_moyen` (number, 0.1…10000, facultatif) : Panier moyen en euros pour ce calcul. Défaut : celui déclaré dans les réglages du commerce.
- `cout_recompense` (number, 0…10000, facultatif) : Ce que coûte UNE récompense au commerçant (prix de revient), en euros. Sans lui, le coût des récompenses n’est pas chiffré.
- `comparer` (boolean, facultatif) : Ajoute la période de même durée juste avant, pour voir si ça progresse. Défaut : false.

## Exemple

Prompt : « Est-ce que ma carte de fidélité rapporte ? Une récompense me coûte 1,20 €. »

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "rentabilite",
    "arguments": {
      "periode": "derniers_90_jours",
      "cout_recompense": 1.2
    }
  }
}
```

Source : https://stampywallet.com/docs/mcp/outils/rentabilite/

---

# meilleurs_moments

Avec compte · Lecture seule · Formule Croissance.

Montre quand les clients viennent : moyenne de passages par jour de la semaine, répartition par heure, ou les créneaux (jour + heure) les plus chargés, sur une période au choix et à l’heure locale du commerce. Peut aussi compter les inscriptions de nouveaux clients. À utiliser pour « quel est mon meilleur jour ? », « à quelle heure ai-je le plus de monde ? », « quand lancer une offre pour remplir un creux ? ».

## Paramètres

- `par` (enum, facultatif) : jour_semaine (défaut) : moyenne par lundi, mardi… ; heure : total par heure de la journée ; creneau : les couples jour + heure les plus chargés. Valeurs : jour_semaine, heure, creneau. Défaut : "jour_semaine".
- `mesure` (enum, facultatif) : passages (défaut) ou nouveaux_clients (inscriptions à la carte). Valeurs : passages, nouveaux_clients. Défaut : "passages".
- `jours` (array<enum>, ≤ 7, facultatif) : Pour par=heure ou creneau : ne garder que ces jours de la semaine (ex. ["samedi"]). Valeurs : lundi, mardi, mercredi, jeudi, vendredi, samedi, dimanche.
- `periode` (enum, facultatif) : Période étudiée, en jours du fuseau du commerce, aujourd’hui inclus pour les périodes en cours (ce_mois = du 1er à aujourd’hui). « personnalisee » utilise du/au. Défaut derniers_90_jours. Valeurs : aujourdhui, hier, derniers_7_jours, derniers_30_jours, derniers_90_jours, derniers_12_mois, cette_semaine, semaine_derniere, ce_mois, mois_dernier, cette_annee, annee_derniere, depuis_le_debut, personnalisee. Défaut : "derniers_90_jours".
- `du` (string (date), facultatif) : Premier jour inclus (AAAA-MM-JJ). Le donner suffit : la période devient « personnalisee ».
- `au` (string (date), facultatif) : Dernier jour inclus (AAAA-MM-JJ). Défaut : aujourd’hui.
- `limite` (integer, 1…50, facultatif) : Pour par=creneau : nombre de créneaux rendus (défaut 10). Défaut : 10.

## Exemple

Prompt : « À quelle heure ai-je le plus de monde le samedi ? »

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "meilleurs_moments",
    "arguments": {
      "par": "heure",
      "jours": [
        "samedi"
      ]
    }
  }
}
```

Source : https://stampywallet.com/docs/mcp/outils/meilleurs_moments/

---

# chercher_clients

Avec compte · Lecture seule.

Liste les clients du commerce selon un segment (habitués, perdus de vue, à un tampon de la récompense, récompense à offrir, nouveaux, inactifs, jamais revenus) croisé avec des filtres : prénom, tampons sur la carte, nombre de visites, date d’inscription, date de dernière visite, type de wallet ; triés et paginés. Rend pour chacun un identifiant, le prénom et l’initiale du nom, les visites, la dernière visite et l’état de la carte, jamais d’e-mail ni de téléphone. À utiliser pour « qui sont mes meilleurs clients ? », « qui n’est pas revenu ? », « qui est proche de sa récompense ? », ou pour retrouver l’identifiant d’un client avant fiche_client.

## Paramètres

- `segment` (enum, facultatif) : Groupe de départ, défini comme dans l’application. tous (défaut) ; habitues = au moins 4 passages sur les 60 derniers jours ; perdus = venus au moins 4 fois, et absents depuis plus d’une fois et demie leur rythme habituel (médiane des écarts entre leurs passages), ou, sans assez d’historique, depuis plus de le délai du commerce ; congés et jours de fermeture non comptés ; presque = il ne leur manque qu’un tampon pour la récompense ; recompense_prete = une récompense gagnée, pas encore offerte, pas expirée ; nouveaux = inscrits dans les 30 derniers jours ; inactifs = aucun passage depuis plus de le délai du commerce, en jours calendaires, quel que soit leur nombre de visites ; un_seul_passage = un passage au plus : inscrits mais jamais revenus. Valeurs : tous, habitues, perdus, presque, recompense_prete, nouveaux, inactifs, un_seul_passage. Défaut : "tous".
- `recherche` (string, ≤ 60 caractères, facultatif) : Morceau du prénom ou du nom (accents et casse ignorés).
- `tampons_min` (integer, ≥ 0, facultatif) : Tampons au moins sur la carte en cours.
- `tampons_max` (integer, ≥ 0, facultatif) : Tampons au plus sur la carte en cours.
- `visites_min` (integer, ≥ 0, facultatif) : Passages au moins depuis l’inscription (tampons de bienvenue exclus).
- `visites_max` (integer, ≥ 0, facultatif) : Passages au plus depuis l’inscription.
- `inactif_depuis_jours` (integer, 1…3650, facultatif) : Aucun passage depuis au moins N jours calendaires (un client jamais venu compte depuis son inscription).
- `actif_depuis_jours` (integer, 1…3650, facultatif) : Au moins un passage dans les N derniers jours.
- `inscrit_depuis` (string (date), facultatif) : Inscrit ce jour-là ou après (AAAA-MM-JJ).
- `inscrit_avant` (string (date), facultatif) : Inscrit ce jour-là ou avant (AAAA-MM-JJ).
- `derniere_visite_depuis` (string (date), facultatif) : Dernier passage ce jour-là ou après (AAAA-MM-JJ).
- `derniere_visite_avant` (string (date), facultatif) : Dernier passage ce jour-là ou avant (AAAA-MM-JJ). Exclut ceux jamais venus.
- `wallet` (enum, facultatif) : Où le client garde sa carte. aucun = page web, sans wallet. Valeurs : tous, apple, google, aucun. Défaut : "tous".
- `tri` (enum, facultatif) : Ordre des résultats. Défaut derniere_visite (les plus récents d’abord). Valeurs : derniere_visite, visites, visites_90j, tampons, recompenses, inscription, prenom. Défaut : "derniere_visite".
- `ordre` (enum, facultatif) : auto (défaut) : décroissant, sauf prenom (A→Z). Valeurs : auto, asc, desc. Défaut : "auto".
- `limite` (integer, 1…100, facultatif) : Nombre maximum de résultats. Défaut : 25.
- `decalage` (integer, ≥ 0, facultatif) : Nombre de résultats à sauter (pagination). Défaut : 0.

## Exemple

Prompt : « Qui sont mes habitués qui ne viennent plus ? »

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "chercher_clients",
    "arguments": {
      "segment": "perdus",
      "tri": "visites",
      "limite": 20
    }
  }
}
```

Source : https://stampywallet.com/docs/mcp/outils/chercher_clients/

---

# fiche_client

Avec compte · Lecture seule.

L’historique d’UN client : date d’inscription, wallet utilisé, nombre de passages et rythme de visite, passages mois par mois, carte en cours, récompenses gagnées, offertes et à offrir, derniers passages datés. Le retrouver par son identifiant (donné par chercher_clients) ou par son prénom, éventuellement suivi de l’initiale du nom (« Maëlle P. ») ; si plusieurs clients correspondent, la liste des candidats est rendue pour choisir. À utiliser pour « quand est venue Zoé pour la dernière fois ? », « combien de fois Louis est-il venu ? ». Ne donne ni e-mail ni téléphone.

## Paramètres

- `id` (string, facultatif) : Identifiant du client (UUID), tel que rendu par chercher_clients. Prioritaire sur prenom.
- `prenom` (string, ≤ 60 caractères, facultatif) : Prénom du client, éventuellement suivi de l’initiale ou du nom (« Maëlle P. »). Accents et casse ignorés.
- `historique_limite` (integer, 0…200, facultatif) : Nombre de passages récents à détailler (défaut 15). Défaut : 15.
- `inclure_offerts` (boolean, facultatif) : true : l’historique montre aussi les tampons offerts (bienvenue, avis), signalés comme tels. Défaut false : seulement les vrais passages. Défaut : false.
- `mois` (integer, 1…36, facultatif) : Nombre de mois dans la courbe des passages (défaut 12). Défaut : 12.

## Exemple

Prompt : « Quand est venue Zoé pour la dernière fois ? »

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fiche_client",
    "arguments": {
      "prenom": "Zoé"
    }
  }
}
```

Source : https://stampywallet.com/docs/mcp/outils/fiche_client/

---

# envoyer_message

Avec compte · Écrit (confirmer).

Envoie une notification sur l’écran verrouillé des clients (via leur carte Apple Wallet ou Google Wallet). À utiliser pour annoncer une nouveauté, une offre, un événement, ou faire revenir des clients. L’audience est paramétrable (tous, habitués, perdus de vue, presque à la récompense, nouveaux, récompense à retirer, inactifs) et se combine avec des filtres (jours sans passage, tampons sur la carte, passages, date d’inscription). Texte de 180 caractères au plus, envoyé tel quel. Un seul message par jour et par commerce. Appeler d’abord avec confirmer=false : l’aperçu donne le texte exact, le nombre de destinataires et combien peuvent vraiment le recevoir, sans rien envoyer. N’appeler avec confirmer=true qu’après l’accord explicite de la personne : un message parti ne se reprend pas. Pour les messages automatiques (relance, anniversaire, rappels), utiliser regler_automatismes.

## Paramètres

- `texte` (string, ≤ 180 caractères, requis) : Le texte exact de la notification, 180 caractères au plus. Il est précédé du nom du commerce sur le téléphone : inutile de le répéter.
- `audience` (enum, facultatif) : Qui reçoit le message. tous = tous les clients ; habitues = 4 passages ou plus sur 60 jours ; perdus = habitués dont l’absence dépasse une fois et demie leur rythme habituel, ou le délai du commerce sans assez d’historique (la définition de l’écran Clients) ; presque = il ne manque qu’un tampon avant la récompense ; nouveaux = inscrits depuis 30 jours (ou depuis inscrit_depuis) ; recompense_prete = une récompense gagnée, pas encore retirée ; inactifs = tout client sans passage depuis inactif_depuis_jours jours d’ouverture (par défaut le délai du commerce), habitué ou non. Toute audience autre que tous, ou tout filtre, demande la fonction « notifications ciblées ». Valeurs : tous, habitues, perdus, presque, nouveaux, recompense_prete, inactifs. Défaut : "tous".
- `inactif_depuis_jours` (integer, 1…730, facultatif) : Filtre : pas de passage depuis au moins N jours d’OUVERTURE (les jours fermés et les congés ne comptent pas).
- `actif_depuis_jours` (integer, 1…730, facultatif) : Filtre : au moins un passage dans les N derniers jours d’ouverture.
- `tampons_min` (integer, 0…500, facultatif) : Filtre : au moins N tampons sur la carte en cours.
- `tampons_max` (integer, 0…500, facultatif) : Filtre : au plus N tampons sur la carte en cours.
- `passages_min` (integer, 1…10000, facultatif) : Filtre : au moins N passages au total depuis l’inscription.
- `inscrit_depuis` (string (date), facultatif) : Filtre : inscrits ce jour-là ou après (AAAA-MM-JJ).
- `inscrit_avant` (string (date), facultatif) : Filtre : inscrits avant ce jour-là (AAAA-MM-JJ, exclu).
- `confirmer` (boolean, facultatif) : false (défaut) : rend seulement un aperçu de ce qui serait fait, sans rien changer. true : exécute. Toujours montrer l’aperçu à la personne et attendre son accord avant de repasser avec true. Défaut : false.

## Exemple

Prompt : « Préviens mes clients presque à la récompense qu'il y a des croissants aux amandes ce week-end. »

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "envoyer_message",
    "arguments": {
      "texte": "Croissants aux amandes ce week-end : plus qu'un tampon avant votre récompense !",
      "audience": "presque",
      "confirmer": false
    }
  }
}
```

Source : https://stampywallet.com/docs/mcp/outils/envoyer_message/

---

# historique_messages

Avec compte · Lecture seule.

Liste les messages déjà envoyés aux clients, du plus récent au plus ancien, avec leur bilan de remise : reçus, clients sans écran (injoignables), échecs, et encore en cours d’envoi. Résume aussi les messages automatiques partis sur la période (relances des perdus de vue, anniversaires) et dit si un message peut encore partir aujourd’hui. À utiliser pour savoir ce qui a été envoyé, vérifier qu’un envoi est bien arrivé, ou avant d’en écrire un nouveau.

## Paramètres

- `limite` (integer, 1…50, facultatif) : Nombre maximum de résultats. Défaut : 10.
- `decalage` (integer, ≥ 0, facultatif) : Nombre de résultats à sauter (pagination). Défaut : 0.
- `depuis` (string (date), facultatif) : Seulement les envois à partir de ce jour (AAAA-MM-JJ). Sert aussi de début de période pour le résumé des automatiques (30 derniers jours par défaut).
- `jusqu_au` (string (date), facultatif) : Seulement les envois jusqu’à ce jour inclus (AAAA-MM-JJ).

## Exemple

Prompt : « Qu'est-ce que j'ai envoyé à mes clients ce mois-ci, et c'est bien arrivé ? »

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "historique_messages",
    "arguments": {
      "depuis": "2026-10-01"
    }
  }
}
```

Source : https://stampywallet.com/docs/mcp/outils/historique_messages/

---

# regler_automatismes

Avec compte · Écrit (confirmer).

Lit et règle les messages que StampyWallet envoie tout seul aux clients : la relance des habitués qui ne viennent plus (quand leur absence dépasse une fois et demie leur rythme habituel, ou, sans assez d’historique, le délai du commerce, proposé selon son métier et réglable), le message d’anniversaire, les rappels « plus qu’un tampon » et « récompense prête » (et leur délai), les heures calmes pendant lesquelles rien ne part ; montre aussi le bilan du lundi envoyé au commerçant. Sans paramètre de changement : rend l’état actuel, textes compris. Avec des changements : confirmer=false rend un aperçu avant → après sans rien modifier, confirmer=true enregistre. Seuls les champs fournis changent. Pour un message ponctuel, utiliser envoyer_message.

## Paramètres

- `relance_active` (boolean, facultatif) : Active ou coupe la relance automatique des perdus de vue (une par client et par absence).
- `delai_relance_jours` (integer, facultatif) : Délai du commerce avant qu’un habitué soit « perdu de vue », en jours calendaires : une valeur parmi 14, 21, 28, 35, 42, 60, 90. Il sert aux clients sans assez d’historique et borne le rythme des autres (de la moitié au double). Pour revenir au délai proposé pour le métier, mettre "delai_relance" dans effacer.
- `texte_relance` (string, ≤ 180 caractères, facultatif) : Texte de la relance, 180 caractères au plus. Pour revenir au texte par défaut, mettre "texte_relance" dans effacer.
- `anniversaire_active` (boolean, facultatif) : Active ou coupe le message d’anniversaire (il ne part que si un texte existe et si la carte demande la date d’anniversaire).
- `cadeau_anniversaire` (enum, facultatif) : Le cadeau d’anniversaire, valable 30 jours à partir du jour J : message (le texte seul), pourcent (une réduction sur chaque achat), un_offert (« 1 acheté, 1 offert », une fois), choix (le client choisit au comptoir entre la réduction et « 1 acheté, 1 offert »). Les cadeaux déjà ouverts ne changent pas. Valeurs : message, pourcent, un_offert, choix.
- `pourcent_anniversaire` (integer, 1…90, facultatif) : Le pourcentage de la réduction d’anniversaire (pourcent et choix), de 1 à 90.
- `texte_anniversaire` (string, ≤ 180 caractères, facultatif) : Texte du message d’anniversaire, 180 caractères au plus, idéalement avec le cadeau offert. Sans texte, rien ne part.
- `rappel_presque` (boolean, facultatif) : Rappel « plus qu’un tampon » quand il ne manque qu’un passage.
- `rappel_recompense` (boolean, facultatif) : Rappel « votre récompense vous attend » quand elle est gagnée.
- `delai_rappel_minutes` (integer, facultatif) : Délai entre le passage et le rappel, en minutes : une valeur parmi 0, 30, 60, 180, 1440 (1440 = le lendemain).
- `heures_calmes_debut` (integer, 0…23, facultatif) : Début des heures calmes (heure de 0 à 23) : aucune notification automatique n’arrive après.
- `heures_calmes_fin` (integer, 0…23, facultatif) : Fin des heures calmes (heure de 0 à 23) : les envois reprennent à partir de cette heure.
- `canal_avis` (enum, facultatif) : Canal de « demande d’avis » : auto (recommandé : un message important part d’abord par SMS sauf aux clients qui répondent aux notifications, un petit en notification et par SMS seulement aux clients qui répondent mieux aux SMS), notif, secours (SMS si la notification ne porte pas), sms (SMS d’abord), email (e-mail si la notification ne porte pas). Valeurs : auto, notif, secours, sms, email.
- `importance_avis` (enum, facultatif) : Importance de « demande d’avis » : importante (passe avant dans le budget SMS) ou petite. Valeurs : importante, petite.
- `canal_anniversaire` (enum, facultatif) : Canal de « anniversaire » : auto (recommandé : un message important part d’abord par SMS sauf aux clients qui répondent aux notifications, un petit en notification et par SMS seulement aux clients qui répondent mieux aux SMS), notif, secours (SMS si la notification ne porte pas), sms (SMS d’abord), email (e-mail si la notification ne porte pas). Valeurs : auto, notif, secours, sms, email.
- `importance_anniversaire` (enum, facultatif) : Importance de « anniversaire » : importante (passe avant dans le budget SMS) ou petite. Valeurs : importante, petite.
- `canal_rappels` (enum, facultatif) : Canal de « rappels » : auto (recommandé : un message important part d’abord par SMS sauf aux clients qui répondent aux notifications, un petit en notification et par SMS seulement aux clients qui répondent mieux aux SMS), notif, secours (SMS si la notification ne porte pas), sms (SMS d’abord). Valeurs : auto, notif, secours, sms.
- `importance_rappels` (enum, facultatif) : Importance de « rappels » : importante (passe avant dans le budget SMS) ou petite. Valeurs : importante, petite.
- `canal_relance` (enum, facultatif) : Canal de « relance » : auto (recommandé : un message important part d’abord par SMS sauf aux clients qui répondent aux notifications, un petit en notification et par SMS seulement aux clients qui répondent mieux aux SMS), notif, secours (SMS si la notification ne porte pas), sms (SMS d’abord). Valeurs : auto, notif, secours, sms.
- `importance_relance` (enum, facultatif) : Importance de « relance » : importante (passe avant dans le budget SMS) ou petite. Valeurs : importante, petite.
- `canal_messages` (enum, facultatif) : Canal de « messages du commerçant » : auto (recommandé : un message important part d’abord par SMS sauf aux clients qui répondent aux notifications, un petit en notification et par SMS seulement aux clients qui répondent mieux aux SMS), notif, secours (SMS si la notification ne porte pas), sms (SMS d’abord). Valeurs : auto, notif, secours, sms.
- `importance_messages` (enum, facultatif) : Importance de « messages du commerçant » : importante (passe avant dans le budget SMS) ou petite. Valeurs : importante, petite.
- `reserve_sms` (integer, 0…100, facultatif) : Part du budget SMS mensuel gardée pour les messages importants, en % : 0, 25, 50, 75, 100.
- `effacer` (array<enum>, facultatif) : Textes à effacer. texte_relance revient au texte par défaut ; texte_anniversaire vide coupe de fait les envois d’anniversaire ; delai_relance revient au délai proposé pour le métier. Valeurs : texte_relance, texte_anniversaire, delai_relance.
- `confirmer` (boolean, facultatif) : false (défaut) : rend seulement un aperçu de ce qui serait fait, sans rien changer. true : exécute. Toujours montrer l’aperçu à la personne et attendre son accord avant de repasser avec true. Défaut : false.

## Exemple

Prompt : « Active le message d'anniversaire avec 10 % de réduction. »

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "regler_automatismes",
    "arguments": {
      "anniversaire_active": true,
      "cadeau_anniversaire": "pourcent",
      "pourcent_anniversaire": 10,
      "confirmer": false
    }
  }
}
```

Source : https://stampywallet.com/docs/mcp/outils/regler_automatismes/

---

# fermetures

Avec compte · Écrit (confirmer).

Gère les congés et jours de fermeture du commerce : lister, ajouter une période de congés, en supprimer une, ou régler les jours fermés chaque semaine. Important pour la fidélité : les jours fermés ne comptent pas dans l’absence d’un client, donc des congés bien déclarés évitent que des habitués passent pour « perdus de vue » et reçoivent une relance au retour. En option, prevenir_clients=true avec un texte prépare aussi une notification à tous les clients (mêmes règles qu’envoyer_message : un message par jour, aperçu obligatoire). action=lister (défaut) ne change rien. Pour ajouter, supprimer ou régler les jours : confirmer=false rend un aperçu, confirmer=true enregistre (et envoie le message s’il est demandé).

## Paramètres

- `action` (enum, facultatif) : lister : congés à venir et des deux derniers mois, et jours fermés chaque semaine. ajouter : une période (du, au). supprimer : une période par son id (donné par lister). jours_hebdo : remplace les jours fermés chaque semaine par jours_fermes. Valeurs : lister, ajouter, supprimer, jours_hebdo. Défaut : "lister".
- `du` (string (date), facultatif) : Premier jour fermé (AAAA-MM-JJ), pour ajouter.
- `au` (string (date), facultatif) : Dernier jour fermé, inclus (AAAA-MM-JJ). Par défaut, le même jour que du.
- `libelle` (string, ≤ 80 caractères, facultatif) : Nom de la période, pour s’y retrouver (« Congés d’été »).
- `id` (string, facultatif) : Identifiant de la période à supprimer (donné par action=lister).
- `jours_fermes` (array<enum>, ≤ 7, facultatif) : Pour jours_hebdo : la liste COMPLÈTE des jours fermés chaque semaine (liste vide = ouvert tous les jours). Valeurs : dimanche, lundi, mardi, mercredi, jeudi, vendredi, samedi.
- `prevenir_clients` (boolean, facultatif) : true : envoie aussi une notification à tous les clients avec texte. Compte comme le message du jour. Défaut : false.
- `texte` (string, ≤ 180 caractères, facultatif) : Texte de la notification aux clients (180 caractères au plus), si prevenir_clients=true.
- `confirmer` (boolean, facultatif) : false (défaut) : rend seulement un aperçu de ce qui serait fait, sans rien changer. true : exécute. Toujours montrer l’aperçu à la personne et attendre son accord avant de repasser avec true. Défaut : false.

## Exemple

Prompt : « Je ferme du 24 au 31 décembre, préviens mes clients. »

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fermetures",
    "arguments": {
      "action": "ajouter",
      "du": "2026-12-24",
      "au": "2026-12-31",
      "libelle": "Fêtes de fin d'année",
      "prevenir_clients": true,
      "texte": "Nous fermons du 24 au 31 décembre. Belles fêtes, à très vite !",
      "confirmer": false
    }
  }
}
```

Source : https://stampywallet.com/docs/mcp/outils/fermetures/

---

# avis_google

Avec compte · Écrit (confirmer) · Formule Croissance.

Les avis Google du commerce. Chaque client reçoit la même demande d’avis (notification Wallet, SMS ou e-mail selon le canal réglé dans regler_automatismes, canal_avis), avec le lien direct vers la fiche Google : pas de note intermédiaire, pas de tri, aucune récompense contre un avis (règles de Google). Montre les chiffres sur 30 jours (demandes envoyées, clients allés sur Google) ; et règle la demande : lien de la fiche Google, demande active ou non, moment (première récompense ou après N passages), délai, texte. Sans changement : lecture seule. Avec changements : confirmer=false rend un aperçu avant → après, confirmer=true enregistre. Seuls les champs fournis changent.

## Paramètres

- `lien` (string, ≤ 2000 caractères, facultatif) : Lien « écrire un avis » de la fiche Google (g.page/r/…/review, search.google.com/local/writereview?placeid=…). Sans lui, aucune demande ne part.
- `retirer_lien` (boolean, facultatif) : true : retire le lien de la fiche (coupe de fait toutes les demandes).
- `demande_active` (boolean, facultatif) : Envoyer ou non la demande d’avis aux clients.
- `moment` (enum, facultatif) : Quand demander : recompense = à la première récompense ; passages = après N passages (voir passages). Valeurs : recompense, passages.
- `passages` (integer, 1…50, facultatif) : Nombre de passages avant la demande, si moment=passages.
- `delai_minutes` (integer, facultatif) : Délai entre le passage et la demande, en minutes : 0, 30, 60, 180, 1440 (1440 = le lendemain).
- `texte_demande` (string, ≤ 300 caractères, facultatif) : Texte de la demande, 300 caractères au plus. Le lien vers la fiche Google est ajouté après.
- `effacer` (array<enum>, facultatif) : Champs texte à vider. texte_demande revient au texte par défaut. Valeurs : texte_demande.
- `confirmer` (boolean, facultatif) : false (défaut) : rend seulement un aperçu de ce qui serait fait, sans rien changer. true : exécute. Toujours montrer l’aperçu à la personne et attendre son accord avant de repasser avec true. Défaut : false.

## Exemple

Prompt : « Demande un avis Google après le 3e passage, une heure après. »

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "avis_google",
    "arguments": {
      "demande_active": true,
      "moment": "passages",
      "passages": 3,
      "delai_minutes": 60,
      "confirmer": false
    }
  }
}
```

Source : https://stampywallet.com/docs/mcp/outils/avis_google/

---

# voir_carte

Avec compte · Lecture seule.

Montre la carte de fidélité du commerce telle que les clients la voient dans Apple Wallet et Google Wallet, avec ses règles actuelles : mode (tampons, paliers ou points), récompenses et seuils, tampons offerts à l’inscription, expiration des récompenses, réglages des points, style, couleur, tampon, et le lien public d’inscription des clients. À utiliser avant toute modification (modifier_carte reprend les mêmes noms de réglages), ou quand le commerçant demande à quoi ressemble sa carte ou quelle est sa règle. Lecture seule.

## Paramètres

- `variantes` (boolean, facultatif) : true : montre aussi les trois palettes de la collection actuelle, pour proposer un changement de couleur (à passer ensuite en « palette » à modifier_carte). Défaut : false.
- `tampons_poses` (integer, 0…1000000, facultatif) : Tampons (ou points) posés sur l’aperçu, pour montrer une carte en cours (défaut : tampons de bienvenue + 2).
- `qr` (boolean, facultatif) : true : joint le QR d’inscription des clients (celui de l’affichette), pour essayer la carte sur son téléphone. Défaut : false.

## Exemple

Prompt : « Montre-moi ma carte, avec les autres palettes possibles. »

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "voir_carte",
    "arguments": {
      "variantes": true
    }
  }
}
```

Source : https://stampywallet.com/docs/mcp/outils/voir_carte/

---

# modifier_carte

Avec compte · Écrit (confirmer).

Change un ou plusieurs réglages de la carte de fidélité du commerce, en un seul appel : nom imprimé, style (collection, palette ou couleur libre), tampon, règle de récompense (mode tampons/paliers/points, seuils, récompenses), tampons offerts à l’inscription, expiration des récompenses, en mode paliers la forme de la carte (forme_paliers : tampons ou l’une des cinq formes), et en mode points le nom des points, la forme de la carte (forme_points), la valeur par défaut d’un passage, les raccourcis et les points par euro. Seuls les réglages donnés changent ; lire d’abord la carte avec voir_carte. Appeler avec confirmer=false (défaut) pour montrer l’avant/après, puis avec confirmer=true après accord explicite. Un changement de règle s’applique aussi aux cartes déjà chez les clients. Les images (logo, fond, tampon en image) se changent dans l’application, page Carte.

## Paramètres

- `nom` (string, ≤ 80 caractères, facultatif) : Nom du commerce, imprimé en haut de la carte.
- `mode` (enum, facultatif) : tampons : une récompense à un seuil (le plus simple). paliers : plusieurs récompenses sur la même carte (ex. 5 et 10). points : le commerçant saisit un nombre de points à chaque passage (paniers variables). Valeurs : tampons, paliers, points.
- `recompense` (string, ≤ 120 caractères, facultatif) : La récompense (mode tampons). Ignorée si « paliers » est donné.
- `tampons` (integer, 2…30, facultatif) : Nombre de passages pour obtenir la récompense (mode tampons), de 2 à 30.
- `paliers` (array<object>, ≤ 6, facultatif) : Les récompenses et leurs seuils (modes paliers et points). Du plus petit au plus grand.
- `paliers[].a` (integer, 1…1000000, requis) : Seuil : nombre de tampons (ou de points en mode points) pour obtenir ce palier.
- `paliers[].recompense` (string, ≤ 120 caractères, requis) : Ce que le client reçoit, tel qu’imprimé sur la carte. Ex. « Un café offert ».
- `paliers[].icone` (enum, facultatif) : Icône du palier (défaut : cadeau). Valeurs : etincelle, eclat, goutte, main, pinceau, oeil, ciseaux, sechoir, fleur, lotus, coeur, etoile, diamant, couronne, soleil, lune, talon, robe, sac, serviette, cafe, grain, the, cookie, gateau, pain, part, burger, glace, bol, plat, verre, biere, bulles, cocktail, cerises, orange, avocat, piment, oeuf, poisson, fromage, popcorn, feuille, flamme, eclair, sourire, patte, chien, chat, cadeau, haltere, velo, livre, note, appareil, palette, dent, parapluie, ballon, tshirt, basket, croissant.
- `collection` (enum, facultatif) : Style de la carte : original (sobre), cafe (cadre fin), botanique (italique, feuillages), trattoria (festonné), atelier (moderne), pass (comme un pass Apple Wallet : logo en grand, tampons en objets ombrés, fond franc). Valeurs : original, cafe, botanique, trattoria, atelier, pass.
- `palette` (integer, 0…3, facultatif) : Palette de la collection : 0, 1 ou 2 (chaque collection en propose trois ; pass en propose une quatrième, 3). Ignorée si « couleur » est donnée.
- `couleur` (string, facultatif) : Couleur de fond libre, en hexadécimal. L’encre (texte) est choisie automatiquement pour rester lisible.
- `tampon` (enum, facultatif) : Le signe posé à chaque passage. « rond » : le point simple. Beauté : etincelle, eclat, goutte, main, pinceau, oeil, ciseaux, sechoir, fleur, lotus, coeur, etoile, diamant, couronne, soleil, lune, talon, robe, sac, serviette. Food : cafe, grain, the, cookie, gateau, pain, part, burger, glace, bol, plat, verre, biere, bulles, cocktail, cerises, orange, avocat, piment, oeuf, poisson, fromage, popcorn. Divers : feuille, flamme, eclair, sourire, patte, chien, chat, cadeau, haltere, velo, livre, note, appareil, palette, dent, parapluie, ballon, tshirt, basket. Valeurs : rond, etincelle, eclat, goutte, main, pinceau, oeil, ciseaux, sechoir, fleur, lotus, coeur, etoile, diamant, couronne, soleil, lune, talon, robe, sac, serviette, cafe, grain, the, cookie, gateau, pain, part, burger, glace, bol, plat, verre, biere, bulles, cocktail, cerises, orange, avocat, piment, oeuf, poisson, fromage, popcorn, feuille, flamme, eclair, sourire, patte, chien, chat, cadeau, haltere, velo, livre, note, appareil, palette, dent, parapluie, ballon, tshirt, basket, croissant.
- `tampons_bienvenue` (integer, 0…5, facultatif) : Tampons offerts à l’inscription du client (0 à 5). 1 par défaut : une carte entamée donne envie d’être finie.
- `nom_des_points` (string, ≤ 20 caractères, facultatif) : Mode points : comment s’appellent les points (« points », « graines », « étoiles »…).
- `forme_paliers` (enum, facultatif) : Mode paliers : le dessin de la carte. tampons (défaut) : les tampons en grille, chaque récompense à la place du tampon de son seuil. Ou l’une des cinq formes des points, qui compte alors des tampons : medailles (une jauge et une médaille par récompense), vitrine (les récompenses côte à côte, chacune sa jauge), remplissage (la prochaine récompense en grand, qui se colore), chemin (une route en S où chaque tampon fait avancer le curseur), anneau (une jauge ronde autour de la prochaine récompense). Les photos des récompenses se déposent dans l’application, page Carte. Valeurs : tampons, medailles, vitrine, remplissage, chemin, anneau.
- `forme_points` (enum, facultatif) : Mode points : le dessin de la carte. medailles (défaut) : une jauge épaisse et une grande médaille par récompense. vitrine : les récompenses côte à côte, chacune sa petite jauge. remplissage : la prochaine récompense en grand, qui se colore à mesure. chemin : une route en S, les récompenses en étapes. anneau : une jauge ronde autour de la prochaine récompense, la liste à côté. Les photos des récompenses se déposent dans l’application, page Carte. Valeurs : medailles, vitrine, remplissage, chemin, anneau.
- `expiration_recompense_jours` (integer, 0…365, facultatif) : Jours pendant lesquels une récompense gagnée reste valable : 0, 30, 60, 90, 180, 365 (0 = n’expire pas).
- `points_par_defaut` (integer, 1…100000, facultatif) : Mode points : points posés par défaut à chaque passage (1 à 100 000).
- `points_raccourcis` (array<integer>, ≤ 12, facultatif) : Mode points : les valeurs proposées d’un geste au scan (jusqu’à 6, triées et dédoublonnées). Ex. [1, 2, 5, 10].
- `points_par_euro` (number, 0.01…10000, facultatif) : Mode points : points par euro dépensé, repère affiché au commerçant (ex. 1 ou 0,5).
- `confirmer` (boolean, facultatif) : false (défaut) : rend seulement un aperçu de ce qui serait fait, sans rien changer. true : exécute. Toujours montrer l’aperçu à la personne et attendre son accord avant de repasser avec true. Défaut : false.

## Exemple

Prompt : « Passe ma carte en paliers : un café à 5 passages, un croissant à 10. »

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "modifier_carte",
    "arguments": {
      "mode": "paliers",
      "paliers": [
        {
          "a": 5,
          "recompense": "Un café offert",
          "icone": "cafe"
        },
        {
          "a": 10,
          "recompense": "Un croissant offert",
          "icone": "croissant"
        }
      ],
      "confirmer": false
    }
  }
}
```

Source : https://stampywallet.com/docs/mcp/outils/modifier_carte/

---

# fiche_commerce

Avec compte · Écrit (confirmer).

Lit ou modifie la fiche du commerce : nom, type de commerce, panier moyen (sert aux estimations du tableau de bord), langue des clients, coordonnées imprimées au dos de la carte (adresse, téléphone, horaires, site web, message de bienvenue) et lien public d’inscription des clients (stampywallet.com/rejoindre/, celui du QR). Sans paramètre de changement : rend la fiche actuelle. Avec des changements : confirmer=false (défaut) montre l’avant/après, confirmer=true écrit après accord explicite. Un ancien lien public continue de fonctionner après un changement (les QR déjà imprimés restent bons).

## Paramètres

- `nom` (string, ≤ 80 caractères, facultatif) : Nom du commerce (aussi imprimé sur la carte).
- `metier` (enum, facultatif) : Type de commerce. « autre » : instituts, ongles, fleuristes, coiffeurs, épiceries… Valeurs : cafe, boulangerie, restaurant, autre.
- `panier_moyen` (number, 0.01…100000, facultatif) : Dépense moyenne d’un client par passage, en euros.
- `langue` (enum, facultatif) : Langue du commerce : celle de la carte, des pages et des messages vus par les clients. Valeurs : fr, en, es.
- `adresse` (string, ≤ 160 caractères, facultatif) : Adresse, au dos de la carte (160 caractères au plus).
- `telephone` (string, ≤ 30 caractères, facultatif) : Téléphone, au dos de la carte.
- `horaires` (string, ≤ 120 caractères, facultatif) : Horaires d’ouverture, en texte libre (ex. « Mar–sam 7 h–19 h »).
- `site_web` (string, ≤ 160 caractères, facultatif) : Site web ou page Instagram.
- `message_bienvenue` (string, ≤ 180 caractères, facultatif) : Petit mot au dos de la carte, lu par le client en l’ajoutant.
- `lien` (string, ≤ 120 caractères, facultatif) : Lien public voulu, en clair (« Le Fournil de la Gare » devient « le-fournil-de-la-gare »), de 3 à 32 caractères. Un lien déjà pris par un autre commerce est refusé.
- `effacer` (array<enum>, ≤ 6, facultatif) : Champs à vider. « lien » : l’adresse publique redevient l’identifiant technique (le lien reste réservé à ce commerce). Valeurs : adresse, telephone, horaires, site_web, message_bienvenue, lien.
- `confirmer` (boolean, facultatif) : false (défaut) : rend seulement un aperçu de ce qui serait fait, sans rien changer. true : exécute. Toujours montrer l’aperçu à la personne et attendre son accord avant de repasser avec true. Défaut : false.

## Exemple

Prompt : « Ajoute mes horaires au dos de la carte : mardi au samedi, 7 h à 19 h. »

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fiche_commerce",
    "arguments": {
      "horaires": "Mar–sam 7 h–19 h",
      "confirmer": false
    }
  }
}
```

Source : https://stampywallet.com/docs/mcp/outils/fiche_commerce/

---

# affichette

Avec compte · Lecture seule.

Rend le QR code d’inscription des clients (celui à poser au comptoir, que les clients scannent pour ajouter la carte à leur téléphone), le lien public, la carte, et les liens de téléchargement de l’affichette à imprimer (PDF A5 ou A6) et du QR seul (PNG, SVG) pour un menu, une vitrine ou Canva. À utiliser quand le commerçant veut imprimer son affichette, récupérer son QR code ou le lien à mettre dans sa bio. Les téléchargements s’ouvrent dans l’application, connecté. Pour recevoir les PDF par e-mail : envoyer_affichette. Lecture seule.

## Paramètres

- `format` (enum, facultatif) : Format du PDF mis en avant : a5 (demi-feuille, affiche de comptoir) ou a6 (quart de feuille, chevalet ou porte-carte). Valeurs : a5, a6. Défaut : "a5".

## Exemple

Prompt : « Donne-moi mon QR code et l'affichette à imprimer. »

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "affichette",
    "arguments": {
      "format": "a5"
    }
  }
}
```

Source : https://stampywallet.com/docs/mcp/outils/affichette/

---

# envoyer_affichette

Avec compte · Écrit (confirmer).

Envoie l’affichette de comptoir (PDF A5 et A6, avec le QR d’inscription des clients) à l’adresse e-mail du compte StampyWallet connecté, pour l’imprimer depuis un autre appareil ou chez un imprimeur. Seulement à cette adresse, jamais à une autre. Appeler avec confirmer=false (défaut) pour annoncer l’envoi, puis confirmer=true après accord.

## Paramètres

- `confirmer` (boolean, facultatif) : false (défaut) : rend seulement un aperçu de ce qui serait fait, sans rien changer. true : exécute. Toujours montrer l’aperçu à la personne et attendre son accord avant de repasser avec true. Défaut : false.

## Exemple

Prompt : « Envoie-moi l'affichette par e-mail pour l'imprimer. »

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "envoyer_affichette",
    "arguments": {
      "confirmer": false
    }
  }
}
```

Source : https://stampywallet.com/docs/mcp/outils/envoyer_affichette/

---

# equipe

Avec compte · Écrit (confirmer) · Propriétaire seulement.

Gère l’équipe du commerce (propriétaire seulement). action=lister : les membres (nom, e-mail, rôle, tampons posés) et les invitations en attente. action=inviter : crée une invitation personnelle valable 14 jours (rôle employé = scanner seulement, ou responsable = chiffres, clients, messages, carte) ; avec « email », elle part par e-mail à la personne, sinon le lien est rendu pour être transmis. action=changer_role : passe un membre en employé ou responsable. action=retirer : retire l’accès d’un membre et ferme ses sessions. action=annuler_invitation : annule un lien pas encore utilisé. Les changements prennent confirmer=false (défaut, aperçu) puis confirmer=true après accord explicite. Nommer un propriétaire se fait dans l’application.

## Paramètres

- `action` (enum, facultatif) : Ce qu’il faut faire. Valeurs : lister, inviter, changer_role, retirer, annuler_invitation. Défaut : "lister".
- `membre_id` (string, ≤ 36 caractères, facultatif) : changer_role, retirer : identifiant du membre, lu avec action=lister.
- `email` (string, ≤ 254 caractères, facultatif) : inviter : adresse de la personne invitée, l’invitation lui est envoyée par e-mail. changer_role, retirer : e-mail d’un membre (à la place de membre_id).
- `nom` (string, ≤ 60 caractères, facultatif) : inviter : repère pour s’y retrouver dans les invitations (ex. « Julie, le matin »).
- `role` (enum, facultatif) : inviter (défaut staff), changer_role : staff = employé, ne voit que le scanner ; manager = responsable, voit chiffres, clients, messages et règle la carte, sans toucher à l’équipe. Valeurs : staff, manager.
- `invitation` (string, ≤ 300 caractères, facultatif) : annuler_invitation : le lien d’invitation ou son jeton, lus avec action=lister.
- `confirmer` (boolean, facultatif) : false (défaut) : rend seulement un aperçu de ce qui serait fait, sans rien changer. true : exécute. Toujours montrer l’aperçu à la personne et attendre son accord avant de repasser avec true. Défaut : false.

## Exemple

Prompt : « Invite Julie comme employée, son e-mail est julie@example.com. »

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "equipe",
    "arguments": {
      "action": "inviter",
      "email": "julie@example.com",
      "nom": "Julie, le matin",
      "role": "staff",
      "confirmer": false
    }
  }
}
```

Source : https://stampywallet.com/docs/mcp/outils/equipe/

---

# L'API StampyWallet

Ajoutez 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](https://stampywallet.com/docs/api/webhooks/)). 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](https://stampywallet.com/docs/api/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](site:nouveautes/).

## L'adresse de base

Toutes les routes sont servies en HTTPS, au format JSON (champs en français, en snake_case), sous :

```text title="Adresse de base"
https://app.stampywallet.com/v1
```

Les 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](https://stampywallet.com/docs/api/authentification/)), puis lisez la fiche de votre commerce :

```bash title="curl"
curl https://app.stampywallet.com/v1/commerce \
  -H "Authorization: Bearer sw_live_votre_cle"
```
```js title="Node.js"
const reponse = await fetch('https://app.stampywallet.com/v1/commerce', {
  headers: { Authorization: `Bearer ${process.env.STAMPY_CLE}` },
});
console.log(await reponse.json());
```
```python title="Python"
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](https://stampywallet.com/docs/api/commerce/) et les règles de la carte |
| `POST /v1/clients` | [Créer un client](https://stampywallet.com/docs/api/creer-client/) et obtenir le lien de sa carte |
| `GET /v1/clients` | [Retrouver un client](https://stampywallet.com/docs/api/chercher-clients/) par téléphone, e-mail ou carte |
| `GET /v1/clients/:id` | [Lire un client](https://stampywallet.com/docs/api/lire-client/) et l'état de sa carte |
| `POST /v1/passages` | [Ajouter un passage](https://stampywallet.com/docs/api/ajouter-passage/) : un tampon, ou des points selon le montant |
| `DELETE /v1/passages/:id` | [Annuler un passage](https://stampywallet.com/docs/api/annuler-passage/) |
| `POST /v1/recompenses` | [Offrir une récompense](https://stampywallet.com/docs/api/offrir-recompense/) gagnée |
| `POST /v1/entrants/:jeton` | [Recevoir les ventes de votre caisse](https://stampywallet.com/docs/api/entrants/) (Square, Shopify, SumUp, Zettle, ou le format générique) |

Et dans l'autre sens, les [webhooks sortants](https://stampywallet.com/docs/api/webhooks/) : neuf [événements](https://stampywallet.com/docs/api/evenements/), signés.

> **Astuce :** pas de développeur sous la main ? La page [Relier votre caisse](https://stampywallet.com/docs/api/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](https://stampywallet.com/docs/mcp/brancher/) : 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](https://stampywallet.com/docs/api/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.

Source : https://stampywallet.com/docs/api/

---

# Authentification

Chaque appel à l'API porte une clé secrète sw_live_, créée dans Réglages › Intégrations et montrée une seule fois. 120 requêtes par minute et par clé.

## Créer une clé

1. **Ouvrez Réglages › Intégrations** dans votre espace StampyWallet (le propriétaire ou un responsable).
2. **Créez une clé** et donnez-lui un nom qui dit où elle sert (« Caisse du comptoir », « Site »).
3. **Copiez-la tout de suite.** Elle commence par `sw_live_` et n'est montrée entière qu'une seule fois : StampyWallet n'en garde qu'une empreinte. Perdue, elle ne se retrouve pas : révoquez-la et créez-en une autre.

## L'envoyer à chaque appel

La clé part dans l'en-tête `Authorization`, après le mot `Bearer` :

```http title="En-tête"
Authorization: Bearer sw_live_4f9c2a7e1b...
```

Une clé donne accès à **un** commerce : celui dans lequel elle a été créée. Si vous gérez plusieurs établissements, créez une clé dans chacun.

> **Attention :** la clé agit en votre nom : elle crée des clients et ajoute des passages. Gardez-la côté serveur (variable d'environnement, coffre de secrets), jamais dans le code d'une page web ou d'une application mobile, jamais dans un dépôt Git.

## Révoquer une clé

Dans **Réglages › Intégrations**, révoquez la clé : les appels qui la portent échouent aussitôt avec `401` et le code `cle_revoquee`. Faites-le dès qu'une clé a pu fuiter, ou quand un prestataire n'en a plus besoin.

## Les erreurs d'accès

| Statut | `code` | Quand |
|---|---|---|
| `401` | `non_authentifie` | En-tête absent ou clé inconnue |
| `401` | `cle_revoquee` | La clé a été révoquée |
| `403` | `formule_requise` | Le commerce n'a pas la formule Croissance (l'API y est comprise, et ouverte pendant l'essai) |
| `403` | `interdit` | L'action n'est pas permise pour ce commerce |
| `429` | `trop_de_requetes` | Plus de 120 requêtes par minute avec cette clé |

## La limite de débit

**120 requêtes par minute et par clé.** Au-delà, la réponse est `429` avec l'en-tête `Retry-After: 60` : attendez ce nombre de secondes avant de reprendre. Une caisse ordinaire en est très loin.

Le détail du format des erreurs est sur la page [Erreurs](https://stampywallet.com/docs/api/erreurs/).

Source : https://stampywallet.com/docs/api/authentification/

---

# Erreurs et réessais

Le format des erreurs de l'API, tous leurs codes, et l'en-tête Idempotency-Key pour réessayer un POST sans risque de doublon.

## Le format d'une erreur

Une erreur répond avec un statut HTTP 4xx ou 5xx et toujours le même corps :

```json title="Réponse d'erreur"
{
  "erreur": {
    "code": "client_introuvable",
    "message": "Aucun client ne correspond dans ce commerce."
  }
}
```

- `code` est stable : c'est lui que votre programme doit tester.
- `message` est une phrase lisible, pour vos journaux. Son texte peut changer.

## Les codes

| Statut | Codes |
|---|---|
| `400` | `requete_invalide` (JSON illisible), `client_requis`, `recherche_requise`, `montant_invalide`, `quantite_invalide`, `points_invalide`, `email_invalide`, `telephone_invalide`, `idempotency_key_invalide` |
| `401` | `non_authentifie`, `cle_revoquee`, `signature_invalide` (adresses d'entrée) |
| `403` | `formule_requise` (l'API demande la formule Croissance), `interdit` |
| `404` | `introuvable` (adresse), `client_introuvable`, `passage_introuvable` |
| `409` | `trop_tot`, `pas_dernier`, `deja_annule`, `recompense_offerte`, `aucune_recompense`, `requete_en_cours` |
| `422` | `conditions_requises`, `montant_insuffisant` |
| `429` | `trop_de_requetes` (voir [la limite de débit](https://stampywallet.com/docs/api/authentification/#limite)) |
| `500` | `interne` : réessayez plus tard, avec la même `Idempotency-Key` |

## Réessayer sans doublon : Idempotency-Key

Un réseau qui coupe au mauvais moment, et vous ne savez pas si le passage a été enregistré. Pour réessayer sans risque, envoyez sur chaque `POST` (`/clients`, `/passages`, `/recompenses`) un en-tête `Idempotency-Key` : une valeur unique par opération, de 1 à 200 caractères, par exemple le numéro du ticket.

```bash title="curl"
curl https://app.stampywallet.com/v1/passages \
  -H "Authorization: Bearer sw_live_votre_cle" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ticket-2026-10-25-0042" \
  -d '{"client": {"telephone": "+33612345678"}, "montant": 12.50}'
```

- La réponse est gardée **24 heures**. La même clé rejouée rend le même statut et le même corps, avec l'en-tête `Idempotent-Replayed: true`.
- Une erreur `4xx` est gardée aussi : la rejouer rend la même erreur. Une erreur `500` libère la clé, pour que vous puissiez réessayer.
- Pendant que la première requête tourne encore : `409 requete_en_cours`.

> **Astuce :** sur [`POST /v1/passages`](https://stampywallet.com/docs/api/ajouter-passage/), le champ `reference` (votre numéro de ticket) protège aussi : une même référence ne tamponne qu'une fois par commerce, même sans `Idempotency-Key`.

Source : https://stampywallet.com/docs/api/erreurs/

---

# Lire le commerce

GET /v1/commerce rend la fiche du commerce lié à la clé et les règles de sa carte de fidélité.

`GET /v1/commerce`

Rend le commerce auquel appartient la clé : son nom, sa devise, son fuseau et les règles de sa carte (mode, objectif, récompenses, règle au montant). Pratique pour vérifier une clé, ou pour afficher la règle de la carte dans votre caisse.

## Exemple

```bash title="curl"
curl https://app.stampywallet.com/v1/commerce \
  -H "Authorization: Bearer sw_live_votre_cle"
```
```js title="Node.js"
const r = await fetch('https://app.stampywallet.com/v1/commerce', {
  headers: { Authorization: `Bearer ${process.env.STAMPY_CLE}` },
});
const commerce = await r.json();
```

## Réponse

```json title="200 OK"
{
  "id": "5f0c8e2a-3b1d-4c9e-9a51-2d7f3e8b6a10",
  "nom": "Boulangerie Lemaire",
  "mode": "tampons",
  "tampons_requis": 10,
  "recompense": "Une baguette tradition offerte",
  "recompenses": [ { "seuil": 10, "libelle": "Une baguette tradition offerte" } ],
  "devise": "EUR",
  "montant_par_tampon": 10,
  "points_par_unite": null,
  "tampons_bienvenue": 1,
  "conditions_exigees": false,
  "premium": null,
  "fuseau": "Europe/Paris",
  "langue": "fr"
}
```

| Champ | Sens |
|---|---|
| `mode` | `tampons`, `paliers` ou `points` ([les types de carte](https://stampywallet.com/docs/guide/types-de-carte/)) |
| `recompenses` | Chaque récompense avec son `seuil` |
| `montant_par_tampon` | La règle « 10 € = 1 tampon », ou `null` |
| `points_par_unite` | En mode points : combien de points pour 1 unité de monnaie |
| `conditions_exigees` | `true` si le commerce exige l'acceptation de ses conditions : passez alors `conditions_acceptees: true` en créant un client |
| `premium` | Le second compteur, quand le commerce l'a ouvert, sinon `null` |

Source : https://stampywallet.com/docs/api/commerce/

---

# Créer un client

POST /v1/clients inscrit un client au programme de fidélité et rend le lien de sa carte, à lui envoyer par SMS ou e-mail.

`POST /v1/clients`

Inscrit un client, comme s'il avait scanné l'affichette, et rend l'objet client avec `lien_carte` : la page où il ajoute sa carte à Apple Wallet ou Google Wallet. Les tampons de bienvenue du commerce sont posés, comme à l'inscription.

**Corps (JSON)**

- `prenom` (string, facultatif) : Prénom du client, affiché sur sa carte.
- `nom` (string, facultatif) : Nom de famille.
- `telephone` (string, facultatif) : Un mobile, au format du pays du commerce ou international (`+33612345678`). Sinon `400 telephone_invalide`.
- `email` (string, facultatif) : Adresse e-mail.
- `conditions_acceptees` (boolean, facultatif) : Obligatoire (`true`) quand le commerce exige ses conditions (`conditions_exigees` de [`GET /v1/commerce`](https://stampywallet.com/docs/api/commerce/)) ; sinon `422 conditions_requises`.

> **Attention :** cette route **ne dédoublonne pas** : appelée deux fois, elle crée deux clients. Cherchez d'abord avec [`GET /v1/clients`](https://stampywallet.com/docs/api/chercher-clients/), ou passez directement par [`POST /v1/passages`](https://stampywallet.com/docs/api/ajouter-passage/) avec `creer_si_absent: true`, qui ne crée le client que s'il n'existe pas.

Le client créé par l'API n'est jamais inscrit aux SMS d'offres : il n'en a pas reçu l'information.

## Exemple

```bash title="curl"
curl https://app.stampywallet.com/v1/clients \
  -H "Authorization: Bearer sw_live_votre_cle" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: inscription-0412" \
  -d '{"prenom": "Léa", "telephone": "+33612345678"}'
```
```js title="Node.js"
const r = await fetch('https://app.stampywallet.com/v1/clients', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.STAMPY_CLE}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'inscription-0412',
  },
  body: JSON.stringify({ prenom: 'Léa', telephone: '+33612345678' }),
});
const client = await r.json();
console.log(client.lien_carte);
```
```python title="Python"
import os, requests

r = requests.post(
    "https://app.stampywallet.com/v1/clients",
    headers={"Authorization": f"Bearer {os.environ['STAMPY_CLE']}",
             "Idempotency-Key": "inscription-0412"},
    json={"prenom": "Léa", "telephone": "+33612345678"},
)
lien = r.json()["lien_carte"]
```

## Réponse

`201 Created` et [l'objet client](https://stampywallet.com/docs/api/lire-client/#objet), par exemple :

```json title="201 Created"
{
  "id": "c2a91f3e-7d40-4b8a-a3c5-91e0d6f4b2c7",
  "prenom": "Léa",
  "nom": null,
  "telephone": "+33612345678",
  "email": null,
  "carte": "X7k2pQ9mLw",
  "lien_carte": "https://stampywallet.com/c/X7k2pQ9mLw",
  "cree_le": "2026-10-25T10:41:52.120Z",
  "etat": { "mode": "tampons", "tampons": 1, "points": null, "objectif": 10, "restants": 9,
            "prochaine_recompense": { "seuil": 10, "libelle": "Une baguette tradition offerte" },
            "recompenses_disponibles": [], "recompenses_obtenues": 0,
            "dernier_passage": null, "premium": null }
}
```

> **Note :** envoyez `lien_carte` au client par le canal de votre choix : StampyWallet ne lui écrit pas à cette étape.

Source : https://stampywallet.com/docs/api/creer-client/

---

# Retrouver un client

GET /v1/clients retrouve un client par son téléphone, son e-mail ou le code de sa carte.

`GET /v1/clients`

Retrouve un client du commerce. Donnez **un seul** des trois paramètres de requête (sinon `400 recherche_requise`) :

**Paramètres de requête**

- `telephone` (string, facultatif) : Le numéro, encodé dans l'adresse (`%2B33612345678`). Il est lu dans le pays du commerce : `0612345678` et `+33612345678` se retrouvent.
- `email` (string, facultatif) : Adresse e-mail, sans tenir compte des majuscules.
- `carte` (string, facultatif) : Le code de la carte, celui que porte son QR.

## Exemple

```bash title="curl"
curl "https://app.stampywallet.com/v1/clients?telephone=%2B33612345678" \
  -H "Authorization: Bearer sw_live_votre_cle"
```

## Réponse

```json title="200 OK"
{
  "clients": [
    {
      "id": "c2a91f3e-7d40-4b8a-a3c5-91e0d6f4b2c7",
      "prenom": "Léa",
      "nom": "Martin",
      "telephone": "+33612345678",
      "email": null,
      "carte": "X7k2pQ9mLw",
      "lien_carte": "https://stampywallet.com/c/X7k2pQ9mLw",
      "cree_le": "2026-10-25T10:41:52.120Z",
      "etat": { "mode": "tampons", "tampons": 7, "points": null, "objectif": 10, "restants": 3,
                "prochaine_recompense": { "seuil": 10, "libelle": "Une baguette tradition offerte" },
                "recompenses_disponibles": [], "recompenses_obtenues": 1,
                "dernier_passage": "2026-10-28T08:02:11.000Z", "premium": null }
    }
  ]
}
```

La liste est vide (`"clients": []`) quand personne ne correspond : ce n'est pas une erreur. Quand plusieurs fiches portent le même e-mail ou le même numéro, c'est la plus récemment venue qui est rendue. Le détail des champs : [l'objet client](https://stampywallet.com/docs/api/lire-client/#objet).

Source : https://stampywallet.com/docs/api/chercher-clients/

---

# Lire un client

GET /v1/clients/:id rend un client et l'état de sa carte de fidélité, tampons, points et récompenses à offrir.

`GET /v1/clients/:id`

Rend un client et l'état de sa carte. `:id` est l'UUID rendu par [`POST /v1/clients`](https://stampywallet.com/docs/api/creer-client/) ou [`GET /v1/clients`](https://stampywallet.com/docs/api/chercher-clients/). Un identifiant inconnu répond `404 client_introuvable`.

```bash title="curl"
curl https://app.stampywallet.com/v1/clients/c2a91f3e-7d40-4b8a-a3c5-91e0d6f4b2c7 \
  -H "Authorization: Bearer sw_live_votre_cle"
```

## L'objet client

Le même objet revient dans toutes les routes client, et dans le champ `client` des autres réponses :

```json title="200 OK"
{
  "id": "c2a91f3e-7d40-4b8a-a3c5-91e0d6f4b2c7",
  "prenom": "Léa",
  "nom": "Martin",
  "telephone": "0612345678",
  "email": "lea@exemple.fr",
  "carte": "X7k2pQ9mLw",
  "lien_carte": "https://stampywallet.com/c/X7k2pQ9mLw",
  "cree_le": "2026-10-22T09:14:03.120Z",
  "etat": {
    "mode": "tampons",
    "tampons": 3,
    "points": null,
    "objectif": 10,
    "restants": 7,
    "prochaine_recompense": { "seuil": 10, "libelle": "Un café offert" },
    "recompenses_disponibles": [
      { "id": "504c8734-3bbd-4fe9-95f8-7a67c8239dab", "libelle": "Un café offert", "seuil": 10,
        "piste": "normal", "obtenue_le": "2026-10-20T16:03:44.000Z", "expire_le": null }
    ],
    "recompenses_obtenues": 1,
    "dernier_passage": "2026-10-22T09:20:00.000Z",
    "premium": null
  }
}
```

| Champ | Sens |
|---|---|
| `carte` | Le code de la carte, celui de son QR |
| `lien_carte` | La page de la carte, qui propose l'ajout à Apple Wallet ou Google Wallet |
| `etat.tampons`, `etat.points` | `tampons` en modes tampons et paliers, `points` en mode points ; l'autre vaut `null` |
| `etat.restants` | Ce qui manque avant la prochaine récompense |
| `etat.recompenses_disponibles` | Les récompenses gagnées, pas encore offertes : leur `id` sert à [les offrir](https://stampywallet.com/docs/api/offrir-recompense/) |
| `etat.premium` | `{ nom, tampons, objectif, restants }` quand le commerce a ouvert le second compteur, sinon `null` |

> **Note :** les identifiants sont des UUID. Des préfixes `cli_`, `pas_` ou `rec_` devant un UUID sont acceptés en entrée, et ignorés.

Source : https://stampywallet.com/docs/api/lire-client/

---

# Ajouter un passage

POST /v1/passages ajoute un tampon ou des points à la carte d'un client depuis votre caisse, et dit si une récompense est atteinte.

`POST /v1/passages`

L'équivalent d'un scan au comptoir, envoyé par votre caisse : un tampon (ou plusieurs), ou des points. Les règles et les limites sont celles du comptoir, la carte du client se met à jour dans son Wallet, et le passage compte comme les autres (habitués, rappels, demande d'avis).

**Corps (JSON)**

- `client` (object, requis) : Qui reçoit le passage : **un** de `id`, `carte` (le code de la carte), `email` ou `telephone`.
- `montant` (number, facultatif) : Montant du ticket, en unités (`12.5` pour 12,50 €). Si le commerce a une règle « 10 € = 1 tampon », le montant l'emporte sur `quantite` ; en mode points, il est converti avec la règle de points par euro du commerce.
- `quantite` (integer, facultatif) : Modes tampons et paliers : nombre de tampons, 1 par défaut, 50 au plus.
- `points` (integer, facultatif) : Mode points, sans montant : les points à poser. Par défaut, la valeur du commerce.
- `reference` (string, facultatif) : Le numéro du ticket. Une référence ne tamponne qu'une fois par commerce.
- `creer_si_absent` (boolean, facultatif) : `true` : un client inconnu, désigné par `email` ou `telephone`, est créé (avec `prenom` et `nom` s'ils sont dans `client`). Par défaut `false`.
- `conditions_acceptees` (boolean, facultatif) : Quand le commerce exige ses conditions et que `creer_si_absent` crée le client (dans `client` ou à la racine).

## Exemple

```bash title="curl"
curl https://app.stampywallet.com/v1/passages \
  -H "Authorization: Bearer sw_live_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "client": { "telephone": "+33612345678", "prenom": "Léa" },
    "montant": 12.5,
    "reference": "TICKET-4512",
    "creer_si_absent": true
  }'
```
```js title="Node.js"
const r = await fetch('https://app.stampywallet.com/v1/passages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.STAMPY_CLE}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    client: { telephone: '+33612345678', prenom: 'Léa' },
    montant: 12.5,
    reference: 'TICKET-4512',
    creer_si_absent: true,
  }),
});
const resultat = await r.json();
if (resultat.recompense_atteinte) console.log('Récompense à offrir !');
```
```python title="Python"
import os, requests

r = requests.post(
    "https://app.stampywallet.com/v1/passages",
    headers={"Authorization": f"Bearer {os.environ['STAMPY_CLE']}"},
    json={"client": {"telephone": "+33612345678", "prenom": "Léa"},
          "montant": 12.5, "reference": "TICKET-4512", "creer_si_absent": True},
)
print(r.json()["recompense_atteinte"])
```

## Réponse

```json title="201 Created"
{
  "passage": {
    "id": "226fdea1-ba59-49fb-93e6-60a14a765134",
    "client_id": "c2a91f3e-7d40-4b8a-a3c5-91e0d6f4b2c7",
    "valeur": 1,
    "montant": 12.5,
    "reference": "TICKET-4512",
    "cree_le": "2026-10-22T09:20:00.000Z"
  },
  "rejoue": false,
  "client_cree": false,
  "recompense_atteinte": true,
  "recompenses_gagnees": 1,
  "plafonne": false,
  "client": { "id": "c2a91f3e-7d40-4b8a-a3c5-91e0d6f4b2c7", "prenom": "Léa", "etat": { "tampons": 0, "objectif": 10 } }
}
```

| Champ | Sens |
|---|---|
| `passage.valeur` | Les tampons ou points posés |
| `passage.montant` | Le montant enregistré, ou `null` |
| `rejoue` | `true` quand la `reference` avait déjà servi : la réponse est alors `200` et rend le passage d'origine, sans tamponner une deuxième fois |
| `client_cree` | `true` si `creer_si_absent` a créé le client |
| `recompense_atteinte`, `recompenses_gagnees` | Ce passage fait gagner une récompense (ou plusieurs) : à [offrir](https://stampywallet.com/docs/api/offrir-recompense/) quand le client la prend |
| `plafonne` | `true` si la valeur a été ramenée au plafond du comptoir |
| `client` | [L'objet client](https://stampywallet.com/docs/api/lire-client/#objet) après le passage |

## Les refus

| Statut | `code` | Quand |
|---|---|---|
| `404` | `client_introuvable` | Aucun client ne correspond, et `creer_si_absent` n'est pas à `true` |
| `409` | `trop_tot` | Un passage du même client a eu lieu il y a moins que le délai anti double passage du commerce (90 secondes par défaut) |
| `422` | `montant_insuffisant` | Le montant ne fait pas un tampon (ou un point) |
| `422` | `conditions_requises` | Le client serait créé, mais les conditions du commerce ne sont pas acceptées |

> **Attention :** donnez toujours une `reference` (le numéro de ticket) : une caisse qui réessaie après une coupure ne pose pas deux tampons. Une référence dont le passage a été annulé ne se repose pas.

Source : https://stampywallet.com/docs/api/ajouter-passage/

---

# Annuler un passage

DELETE /v1/passages/:id retire le dernier passage d'un client, par exemple après un ticket annulé ou remboursé en caisse.

`DELETE /v1/passages/:id`

Retire un passage, avec les droits d'un responsable : les tampons ou points qu'il a posés sont enlevés, et une récompense qu'il avait débloquée disparaît avec lui. `:id` est l'UUID rendu par [`POST /v1/passages`](https://stampywallet.com/docs/api/ajouter-passage/).

Corps facultatif : `{ "motif": "Ticket annulé" }` (ou `?motif=` dans l'adresse). Par défaut, le motif est « API ».

## Exemple

```bash title="curl"
curl -X DELETE https://app.stampywallet.com/v1/passages/226fdea1-ba59-49fb-93e6-60a14a765134 \
  -H "Authorization: Bearer sw_live_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{"motif": "Ticket remboursé"}'
```

## Réponse

```json title="200 OK"
{
  "annule": true,
  "recompenses_retirees": 1,
  "client": { "id": "c2a91f3e-7d40-4b8a-a3c5-91e0d6f4b2c7", "prenom": "Léa", "etat": { "tampons": 9, "objectif": 10 } }
}
```

## Les refus

Comme au comptoir, seul le **dernier** passage d'un client s'annule, et jamais deux fois.

| Statut | `code` | Quand |
|---|---|---|
| `404` | `passage_introuvable` | Le passage n'existe pas dans ce commerce |
| `409` | `pas_dernier` | Ce n'est pas le dernier passage du client |
| `409` | `deja_annule` | Le passage est déjà annulé |
| `409` | `recompense_offerte` | La récompense débloquée par ce passage a déjà été offerte (la réponse porte un champ `recompense`) |

Source : https://stampywallet.com/docs/api/annuler-passage/

---

# Offrir une récompense

POST /v1/recompenses marque comme offerte une récompense gagnée par un client, depuis votre caisse.

`POST /v1/recompenses`

Marque une récompense gagnée comme remise au client, l'équivalent du bouton « Offert » du scanner. La carte du client se met à jour dans son Wallet.

**Corps (JSON)**

- `client` (object, requis) : Le client : **un** de `id`, `carte`, `email` ou `telephone`.
- `recompense_id` (string, facultatif) : L'UUID de la récompense à offrir (dans `etat.recompenses_disponibles` de [l'objet client](https://stampywallet.com/docs/api/lire-client/#objet)). Par défaut : la plus ancienne due.
- `piste` (string, facultatif) : `normal` ou `premium` (le second compteur) : sans `recompense_id`, la plus ancienne due de cette piste.

## Exemple

```bash title="curl"
curl https://app.stampywallet.com/v1/recompenses \
  -H "Authorization: Bearer sw_live_votre_cle" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: recompense-ticket-0057" \
  -d '{"client": {"carte": "X7k2pQ9mLw"}}'
```

## Réponse

```json title="200 OK"
{
  "recompense": {
    "id": "504c8734-3bbd-4fe9-95f8-7a67c8239dab",
    "libelle": "Un café offert",
    "piste": "normal",
    "offerte_le": "2026-10-22T09:25:00.000Z"
  },
  "client": { "id": "c2a91f3e-7d40-4b8a-a3c5-91e0d6f4b2c7", "prenom": "Léa", "etat": { "recompenses_disponibles": [] } }
}
```

Sans récompense à offrir, la réponse est `409` avec le code `aucune_recompense`.

Source : https://stampywallet.com/docs/api/offrir-recompense/

---

# Webhooks

Recevez un appel HTTP signé sur votre serveur, Zapier, Make ou n8n à chaque passage, récompense ou nouvelle carte, et vérifiez sa signature HMAC.

Un webhook est une adresse de votre serveur que StampyWallet appelle à chaque événement du comptoir : un passage, une récompense, une nouvelle carte, une carte cadeau vendue. C'est ce qui relie StampyWallet à une caisse, un CRM, un tableur ou un outil sans code, sans intégration officielle.

> **Dans l'autre sens ? :** pour que votre caisse ajoute un tampon à chaque vente, utilisez [`POST /v1/passages`](https://stampywallet.com/docs/api/ajouter-passage/), ou [recevez les ventes de votre caisse](https://stampywallet.com/docs/api/entrants/) directement.

## Configurer une adresse

Dans **Réglages › Intégrations › Webhooks** (le propriétaire et les responsables) :

1. **Ajoutez une adresse** `https://` publique, et cochez si vous voulez des événements. **Aucune case cochée : tous les événements**, y compris ceux qui s'ajouteront plus tard.
2. **Copiez le secret de signature**, qui commence par `whsec_`. Il n'est montré qu'une fois ; ensuite l'écran n'en affiche que les quatre derniers caractères.
3. **Cliquez sur « Envoyer un test »** : un `passage.cree` d'exemple, marqué `"test": true`, part aussitôt vers votre adresse, et l'écran affiche la réponse obtenue.

L'écran montre les 20 derniers envois (statut, code, durée, essai) et un bouton **Renvoyer** sur ceux qui ont échoué. Dix adresses au plus par commerce ; chacune se désactive, se réactive ou se supprime.

> **Attention :** sont refusées : une adresse qui n'est pas en `https://`, une adresse qui contient un identifiant (`https://moi:secret@…`), et toute adresse privée ou locale (`localhost`, `10.x`, `192.168.x`…), même obtenue par le DNS. Tous les ports sont acceptés. Les redirections ne sont jamais suivies : une réponse 3xx compte comme un échec.

## Ce que reçoit votre serveur

Une requête `POST` en JSON, avec ces en-têtes :

```http title="En-têtes"
POST /votre/adresse HTTP/1.1
Content-Type: application/json
User-Agent: StampyWallet-Webhooks/1.0
StampyWallet-Evenement: passage.cree
StampyWallet-Id: evt_WdGHduXPRbExh0vh5eYtCjXo
StampyWallet-Signature: t=1792648365,v1=8f3c…(64 caractères hexadécimaux)
```

Et ce corps. L'enveloppe est la même pour tous les événements ; seul `donnees` change ([la liste des événements](https://stampywallet.com/docs/api/evenements/)) :

```json title="passage.cree"
{
  "id": "evt_WdGHduXPRbExh0vh5eYtCjXo",
  "type": "passage.cree",
  "cree_le": "2026-10-22T05:52:45.694Z",
  "commerce": { "id": "9f1cbdfc-df71-4fab-a554-3bdbb7c71ebf", "nom": "Le Café des Crochets" },
  "donnees": {
    "client": { "id": "40de4b86-1d7a-4cc6-add3-b7a83fa43c04", "prenom": "Inès",
                "telephone": "+33611223344", "email": "ines@example.com" },
    "passage": {
      "id": "226fdea1-ba59-49fb-93e6-60a14a765134",
      "quantite": 1,
      "montant": null,
      "devise": "EUR",
      "reference": "caisse-1",
      "source": "scan",
      "piste": "normal",
      "tampons": 1,
      "objectif": 2
    }
  }
}
```

- `id` : `evt_` suivi de 24 caractères. **Le même pour tous les envois d'un événement** (essais, renvois, et d'une adresse à l'autre) : c'est votre clé de dédoublonnage.
- `cree_le` : le moment de l'événement (pas celui de l'envoi), en ISO 8601 UTC.
- `test` : présent, à `true`, seulement sur l'envoi du bouton « Envoyer un test ».
- `donnees.client` : `{ id, prenom }`, plus `telephone` et `email` seulement si le client les a donnés ; `null` pour une carte cadeau ou un forfait.
- Les montants (`montant`, `prix`) sont en **centimes**, entiers, avec leur `devise` (ISO 4217).
- De nouvelles clés peuvent apparaître : ignorez ce que vous ne connaissez pas.

## Vérifier la signature

Vérifiez chaque requête **avant** de faire confiance à son contenu : sans cela, n'importe qui pourrait appeler votre adresse.

```text title="Le calcul"
StampyWallet-Signature: t=<horodatage unix en secondes>,v1=<signature>
signature = hex( HMAC-SHA256( clé = secret, message = "<t>.<corps brut>" ) )
```

- La clé est le secret **entier**, préfixe `whsec_` compris.
- Le message est l'horodatage `t`, un point, puis le corps **tel que reçu**, en octets. Ne relisez pas le JSON avant de vérifier : un JSON réécrit n'a plus les mêmes octets.
- Refusez un `t` à plus de 5 minutes de votre horloge : cela empêche de rejouer une vieille requête.
- L'en-tête peut porter plusieurs `v1=` (le jour d'un changement de secret) : il suffit qu'une seule corresponde. Comparez à temps constant.

```js title="Node.js"
const crypto = require('node:crypto');

/** corpsBrut : le corps reçu, en Buffer (ou en texte), AVANT tout JSON.parse. */
function verifierStampyWallet(secret, corpsBrut, entete, tolerance = 300) {
  let t = null;
  const v1 = [];
  for (const morceau of String(entete || '').split(',')) {
    const i = morceau.indexOf('=');
    const cle = morceau.slice(0, i).trim();
    const valeur = morceau.slice(i + 1).trim();
    if (cle === 't' && /^\d+$/.test(valeur)) t = Number(valeur);
    if (cle === 'v1') v1.push(valeur);
  }
  if (t === null || v1.length === 0) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > tolerance) return false;
  const attendue = crypto.createHmac('sha256', secret)
    .update(`${t}.`).update(corpsBrut).digest('hex');
  return v1.some((s) => s.length === attendue.length
    && crypto.timingSafeEqual(Buffer.from(s), Buffer.from(attendue)));
}

// Avec Express : garder le corps brut sur cette route.
app.post('/stampywallet', express.raw({ type: 'application/json' }), (req, res) => {
  const ok = verifierStampyWallet(process.env.STAMPYWALLET_WEBHOOK_SECRET,
    req.body, req.get('StampyWallet-Signature'));
  if (!ok) return res.status(400).end();
  const evenement = JSON.parse(req.body.toString('utf8'));
  // dédoublonner sur evenement.id, puis traiter plus tard
  res.status(200).end();
});
```
```python title="Python"
import hashlib
import hmac
import time

def verifier_stampywallet(secret: str, corps_brut: bytes, entete: str, tolerance: float = 300) -> bool:
    """corps_brut : les octets reçus (Flask : request.get_data()), avant tout json.loads."""
    t, v1 = None, []
    for morceau in (entete or "").split(","):
        cle, _, valeur = morceau.strip().partition("=")
        if cle == "t" and valeur.isdigit():
            t = int(valeur)
        elif cle == "v1":
            v1.append(valeur)
    if t is None or not v1:
        return False
    if abs(int(time.time()) - t) > tolerance:
        return False
    attendue = hmac.new(secret.encode(), f"{t}.".encode() + corps_brut, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(s, attendue) for s in v1)

# Avec Flask :
# @app.post("/stampywallet")
# def recevoir():
#     if not verifier_stampywallet(os.environ["STAMPYWALLET_WEBHOOK_SECRET"],
#                                  request.get_data(),
#                                  request.headers.get("StampyWallet-Signature", "")):
#         abort(400)
#     evenement = request.get_json()
#     return "", 200
```
```php title="PHP"
<?php
function verifier_stampywallet(string $secret, string $corpsBrut, string $entete, int $tolerance = 300): bool
{
    $t = null;
    $v1 = [];
    foreach (explode(',', $entete) as $morceau) {
        $paire = explode('=', trim($morceau), 2);
        if (count($paire) !== 2) {
            continue;
        }
        if ($paire[0] === 't' && ctype_digit($paire[1])) {
            $t = (int) $paire[1];
        } elseif ($paire[0] === 'v1') {
            $v1[] = $paire[1];
        }
    }
    if ($t === null || count($v1) === 0) {
        return false;
    }
    if (abs(time() - $t) > $tolerance) {
        return false;
    }
    $attendue = hash_hmac('sha256', $t . '.' . $corpsBrut, $secret);
    foreach ($v1 as $s) {
        if (hash_equals($attendue, $s)) {
            return true;
        }
    }
    return false;
}

// le corps brut, avant json_decode
$corps = file_get_contents('php://input');
$ok = verifier_stampywallet(getenv('STAMPYWALLET_WEBHOOK_SECRET'), $corps,
    $_SERVER['HTTP_STAMPYWALLET_SIGNATURE'] ?? '');
```

### Vecteur de test

Pour vérifier votre code : avec ces valeurs et une tolérance infinie (`Infinity`, `float("inf")`, `PHP_INT_MAX`), la fonction doit rendre vrai. Le corps tient sur une seule ligne, sans retour à la ligne final, et contient un « é » exprès : la signature porte sur les octets UTF-8.

```text title="Vecteur"
secret : whsec_5WZbPq8rLk2N7xYdTf3Hc9JmVg4RsQe1
t      : 1761134400
corps  : {"id":"evt_4fK9mQ2xT7bL1nR8vZ3cW6yH","type":"passage.cree","cree_le":"2026-10-22T12:00:00.000Z","commerce":{"id":"9b2f6c1e-4d3a-4f7b-8e21-5a6c7d8e9f01","nom":"Le Café du Coin"},"donnees":{"client":{"id":"3c1d2e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f","prenom":"Camille"},"passage":{"id":"7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b","quantite":1,"montant":null,"devise":"EUR","reference":null,"source":"scan","piste":"normal","tampons":4,"objectif":10}}}
v1     : 4346dff69a3e9e25937b22ec031a8eaf8cfce3baca4dfb932865682b8f891f1d
en-tête: t=1761134400,v1=4346dff69a3e9e25937b22ec031a8eaf8cfce3baca4dfb932865682b8f891f1d
```

## Répondre, et les réessais

- Répondez par un code **2xx en moins de 10 secondes**. Le corps de votre réponse est ignoré. Répondez vite, et faites le travail long ensuite.
- Sinon, **huit essais** au total : le premier tout de suite, puis après 1 min, 5 min, 30 min, 2 h, 5 h, 8 h et 8 h. Le dernier part environ 23 h 30 après le premier ; au huitième échec, l'envoi est abandonné.
- Après **50 échecs d'affilée** sur une adresse, elle est **désactivée** et le propriétaire du commerce reçoit un e-mail. Réactivez-la une fois votre serveur réparé : son compteur repart à zéro.
- L'envoi de test n'est essayé qu'une fois et ne compte pas dans les échecs.
- **Renvoyer** renvoie le même événement (même `id`, mêmes octets), avec une signature neuve.
- **Au moins une fois, sans ordre garanti** : un événement peut arriver deux fois, dédoublonnez sur `StampyWallet-Id` ; deux événements proches peuvent arriver dans le désordre, fiez-vous à `cree_le`.
- Les envois sont gardés 30 jours dans le journal.

| Statut d'un envoi | Sens |
|---|---|
| `en_attente` | Pas encore essayé |
| `echec` | Le dernier essai a raté ; un autre est prévu |
| `livre` | Un 2xx a été reçu |
| `abandonne` | Huit échecs, ou adresse désactivée, ou remplacé par un renvoi |

> **Sans code :** Zapier, Make et n8n reçoivent ces webhooks tels quels : collez l'adresse de leur déclencheur « Webhook » comme adresse. Les pas à pas sont sur [Relier votre caisse](https://stampywallet.com/docs/api/relier-votre-caisse/#sans-code).

Source : https://stampywallet.com/docs/api/webhooks/

---

# Liste des événements

Les neuf événements envoyés par les webhooks StampyWallet, quand ils partent, et le contenu exact de leur champ donnees.

Chaque événement a la même enveloppe (`id`, `type`, `cree_le`, `commerce`, voir [Webhooks](https://stampywallet.com/docs/api/webhooks/#requete)). Seul `donnees` change ; il est montré seul ci-dessous. Les événements partent du comptoir comme de l'API : un passage scanné ou posé par [`POST /v1/passages`](https://stampywallet.com/docs/api/ajouter-passage/) produit le même `passage.cree`.

| Événement | Envoyé quand |
|---|---|
| `client.cree` | Un client rejoint le programme (sa carte est créée) |
| `carte.ajoutee` | Le client enregistre sa carte dans Apple Wallet ou Google Wallet |
| `passage.cree` | Un passage est posé : un ou plusieurs tampons, ou des points |
| `passage.annule` | Le dernier passage d'un client est annulé |
| `recompense.atteinte` | Un passage franchit un palier : une récompense est due (une par palier franchi) |
| `recompense.offerte` | La récompense est remise au client |
| `recompense.annulee` | La remise d'une récompense est annulée : elle redevient due |
| `carte_cadeau.vendue` | Une carte cadeau est vendue |
| `forfait.vendu` | Un forfait prépayé est vendu |

> **Note :** `carte.ajoutee` vaut pour Apple Wallet et Google Wallet : `donnees.carte.wallet` vaut `apple` ou `google`. Côté Apple, l'événement part à chaque nouvel appareil (un iPhone puis une montre en produisent deux). Retirer la carte n'émet rien.

## client.cree

```json title="donnees"
{
  "client": {
    "id": "3374a06e-9608-4376-91cb-1a3fb6721b04",
    "prenom": "Camille",
    "cree_le": "2026-10-22T05:52:45.664Z"
  }
}
```

`telephone` et `email` n'apparaissent que si le client les a donnés. `prenom` peut être `null`.

## carte.ajoutee

```json title="donnees"
{
  "client": { "id": "40de4b86-1d7a-4cc6-add3-b7a83fa43c04", "prenom": "Inès",
              "telephone": "+33611223344", "email": "ines@example.com" },
  "carte": { "wallet": "apple" }
}
```

## passage.cree

```json title="donnees"
{
  "client": { "id": "40de4b86-1d7a-4cc6-add3-b7a83fa43c04", "prenom": "Inès",
              "telephone": "+33611223344", "email": "ines@example.com" },
  "passage": {
    "id": "226fdea1-ba59-49fb-93e6-60a14a765134",
    "quantite": 1,
    "montant": null,
    "devise": "EUR",
    "reference": "caisse-1",
    "source": "scan",
    "piste": "normal",
    "tampons": 1,
    "objectif": 2
  }
}
```

- `quantite` : ce que vaut le passage (tampons, ou points en mode points).
- `montant` : le montant du ticket en centimes s'il a été saisi, sinon `null`.
- `reference` : l'identifiant d'opération envoyé par l'appelant (la référence de l'API, ou celle du comptoir), sinon `null`.
- `source` : `scan`, `manuel`, `api`…
- `piste` : `normal`, ou `premium` pour le second compteur.
- `tampons` (ou `points` en mode points) et `objectif` : le compteur **après** le passage. Un passage qui termine la carte rend celui de la carte suivante (souvent `0`) ; la récompense arrive dans un `recompense.atteinte` à part.

## passage.annule

```json title="donnees"
{
  "client": { "id": "40de4b86-1d7a-4cc6-add3-b7a83fa43c04", "prenom": "Inès",
              "telephone": "+33611223344", "email": "ines@example.com" },
  "passage": {
    "id": "d8f62d77-88a6-44ef-a0c3-2a7d5066b90a",
    "quantite": 1,
    "source": "scan",
    "piste": "normal",
    "tampons": 0,
    "objectif": 2
  },
  "recompenses_retirees": 0,
  "motif": "double scan"
}
```

`passage.id` est celui du `passage.cree` d'origine, et le compteur celui d'après l'annulation. `recompenses_retirees` : les récompenses que ce passage avait débloquées et qui disparaissent avec lui. `motif` : la raison saisie au comptoir, ou `null`.

## recompense.atteinte

```json title="donnees"
{
  "client": { "id": "40de4b86-1d7a-4cc6-add3-b7a83fa43c04", "prenom": "Inès",
              "telephone": "+33611223344", "email": "ines@example.com" },
  "recompense": {
    "id": "504c8734-3bbd-4fe9-95f8-7a67c8239dab",
    "libelle": "Un café offert",
    "palier": 2,
    "piste": "normal",
    "expire_le": null
  },
  "passage_id": "8bfbdd5e-eff4-4a3b-94fe-1557ec6edce6"
}
```

Un événement par palier franchi. `expire_le` vaut `null` si les récompenses du commerce n'expirent pas.

## recompense.offerte

```json title="donnees"
{
  "client": { "id": "40de4b86-1d7a-4cc6-add3-b7a83fa43c04", "prenom": "Inès",
              "telephone": "+33611223344", "email": "ines@example.com" },
  "recompense": {
    "id": "504c8734-3bbd-4fe9-95f8-7a67c8239dab",
    "libelle": "Un café offert",
    "piste": "normal",
    "offerte_le": "2026-10-22T05:54:51.790Z"
  }
}
```

## recompense.annulee

```json title="donnees"
{
  "client": { "id": "40de4b86-1d7a-4cc6-add3-b7a83fa43c04", "prenom": "Inès",
              "telephone": "+33611223344", "email": "ines@example.com" },
  "recompense": {
    "id": "504c8734-3bbd-4fe9-95f8-7a67c8239dab",
    "libelle": "Un café offert",
    "piste": "normal"
  },
  "motif": "mauvaise carte"
}
```

## carte_cadeau.vendue

```json title="donnees"
{
  "client": null,
  "carte_cadeau": {
    "id": "ac7e56a5-3c00-492f-971a-21ca7d675fd6",
    "code": "EJ9Y-7FYN",
    "sorte": "montant",
    "produit": null,
    "montant": 2500,
    "devise": "EUR",
    "pour": "Lucie",
    "de": "Marc",
    "canal": "comptoir",
    "expire_le": "2027-04-22T05:54:51.879Z"
  }
}
```

`sorte` vaut `montant` ou `produit` (alors `produit` porte son nom et `montant` son prix). Ici, 2500 centimes : 25 €.

> **Attention :** `code` est le code de la carte cadeau, celui que porte son QR : il suffit à la débiter au comptoir. Traitez-le comme un secret : ne l'écrivez pas dans un tableur partagé ni dans des journaux.

## forfait.vendu

```json title="donnees"
{
  "client": null,
  "forfait": {
    "id": "0ec29323-ed13-4e6b-9595-963601290eac",
    "code": "XFF2-WTW9",
    "nom": "10 cafés",
    "unites": 10,
    "prix": 3000,
    "devise": "EUR",
    "titulaire": "Paul",
    "canal": "comptoir",
    "expire_le": "2027-04-22T05:54:51.891Z"
  }
}
```

`titulaire` : le nom écrit à la vente, ou `null`. `expire_le` vaut `null` pour un forfait sans échéance. Comme pour une carte cadeau, `code` est à garder secret.

> **Note :** les données personnelles se limitent à ce que le client a donné en s'inscrivant. Une fois reçues, elles sont sous votre responsabilité : ne les gardez que le temps nécessaire.

Source : https://stampywallet.com/docs/api/evenements/

---

# Recevoir les événements de votre caisse

POST /v1/entrants/:jeton reçoit les ventes de Square, Shopify, SumUp, Zettle ou de n'importe quel outil, et ajoute le passage au bon client.

`POST /v1/entrants/:jeton`

Une adresse à donner à votre caisse : à chaque vente payée, la caisse l'appelle, et StampyWallet ajoute le passage à la carte du client, retrouvé par son e-mail ou son téléphone. Pas de clé à écrire dans la caisse : le jeton de l'adresse suffit. Une adresse inconnue ou révoquée répond `404`.

## Les sources

Chaque adresse est créée pour une source dans **Réglages › Intégrations**, avec une clé de signature facultative. StampyWallet lit alors le format de cette caisse tel quel :

| Source | Ce qui compte | Client | Montant | Référence |
|---|---|---|---|---|
| `square` | `payment.created` / `payment.updated` au statut `COMPLETED` | E-mail de l'acheteur, ou e-mail et téléphone du client | Hors pourboire | L'id du paiement |
| `shopify` | `orders/paid` | E-mail et téléphone du client ou de la commande | Sous-total de la commande | L'id de la commande |
| `sumup` (bêta) | Transaction `PAID` ou `SUCCESSFUL` | E-mail ou téléphone | Montant de la transaction | Code de transaction |
| `zettle` (bêta) | `PurchaseCreated` | E-mail ou téléphone du client | Montant de l'achat | L'id de l'achat |
| `generique` | Le corps de [`POST /v1/passages`](https://stampywallet.com/docs/api/ajouter-passage/) | `client` | `montant` | `reference` (facultative) |

> **Note :** les sources des caisses **ne créent jamais de client** : une vente sans client connu est ignorée. Une vente sans e-mail ni téléphone, ou sans référence, est ignorée aussi. Seule la source `generique` peut créer un client, avec `creer_si_absent: true`.

## La signature

Quand une clé de signature est enregistrée pour l'adresse, chaque appel doit être signé, sinon `401 signature_invalide`. Collez-la toujours quand la caisse en fournit une.

| Source | En-tête | Signature |
|---|---|---|
| `generique` | `X-Stampy-Signature` | HMAC-SHA256 hexadécimal du corps brut, avec la clé de l'adresse (`sha256=` accepté devant) |
| `square` | `x-square-hmacsha256-signature` | HMAC-SHA256 base64 de l'URL de notification suivie du corps brut |
| `shopify` | `X-Shopify-Hmac-Sha256` | HMAC-SHA256 base64 du corps brut |
| `sumup` | `X-Payload-Signature` | HMAC-SHA256 hexadécimal du corps brut |
| `zettle` | `X-iZettle-Signature` | HMAC-SHA256 hexadécimal de `timestamp + "." + payload` |

## Le format générique

Pour un script, un outil sans code ou une caisse sans format connu, envoyez le même corps que [`POST /v1/passages`](https://stampywallet.com/docs/api/ajouter-passage/) :

```bash title="curl"
corps='{"client": {"telephone": "+33612345678"}, "montant": 18.9, "reference": "T-2026-1025-0091"}'
signature=$(printf '%s' "$corps" | openssl dgst -sha256 -hmac "$STAMPY_ENTRANT_SECRET" | sed 's/^.* //')

curl https://app.stampywallet.com/v1/entrants/9QkT2vX7pL4mR8sN1bC6dF3gH5jK0wYz \
  -H "Content-Type: application/json" \
  -H "X-Stampy-Signature: $signature" \
  -d "$corps"
```
```js title="Node.js"
const crypto = require('node:crypto');

const corps = JSON.stringify({ client: { telephone: '+33612345678' }, montant: 18.9, reference: 'T-2026-1025-0091' });
const signature = crypto.createHmac('sha256', process.env.STAMPY_ENTRANT_SECRET).update(corps).digest('hex');

await fetch(process.env.STAMPY_ENTRANT_URL, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-Stampy-Signature': signature },
  body: corps,
});
```

## Les réponses

Une fois l'appel authentifié, la réponse est toujours `200`, pour que la caisse n'apprenne rien de votre fichier de clients :

- `{ "ok": true, "ignore": true }` : l'événement ne nous concerne pas (non payé, autre sujet, sans client, ou sans référence pour une caisse) ;
- `{ "ok": true }` : dans tous les autres cas, que le client existe ou non, que le passage soit posé ou refusé (trop tôt, montant trop petit).

Seule une vraie panne répond `500` : la caisse réessaie, et la référence garantit qu'un nouvel essai ne tamponne pas deux fois. Chaque adresse accepte 300 appels par minute.

Les réglages pas à pas, caisse par caisse : [Relier votre caisse](https://stampywallet.com/docs/api/relier-votre-caisse/).

Source : https://stampywallet.com/docs/api/entrants/

---

# Relier votre caisse

Les réglages pas à pas pour que Square, Shopify, SumUp, Zettle, Zapier, Make ou n8n ajoutent un tampon à chaque vente, sans développeur.

Relier votre caisse, c'est donner à la caisse une adresse StampyWallet à appeler à chaque vente payée. Le passage s'ajoute alors tout seul à la carte du client, retrouvé par son téléphone ou son e-mail. Rien n'est requis pour démarrer : le scan au comptoir suffit, la caisse est un plus, surtout pour une [carte à points](https://stampywallet.com/docs/guide/types-de-carte/#points).

> **Note :** la caisse ne connaît le client que si elle a son téléphone ou son e-mail (fiche client, ticket envoyé par e-mail, commande en ligne), et le client doit déjà avoir sa carte StampyWallet : une caisse ne crée jamais de client. Une vente anonyme est ignorée : pour elle, le scan au comptoir reste le bon geste.

## Dans StampyWallet, d'abord

1. **Ouvrez Réglages › Intégrations** et choisissez **Recevoir les ventes d'une caisse**.
2. **Choisissez la caisse** (Square, Shopify, SumUp, Zettle, ou « Autre » pour le format générique).
3. **Copiez l'adresse** créée, de la forme `https://app.stampywallet.com/v1/entrants/ent_…`.

## Puis dans votre caisse

**Square**
1. Ouvrez le **Square Developer Dashboard**, créez une application (ou ouvrez la vôtre), puis **Webhooks › Subscriptions › Add subscription**.
2. Collez l'adresse StampyWallet comme **Notification URL** et cochez les événements **`payment.created`** et **`payment.updated`**.
3. Copiez la **Signature key** de l'abonnement et collez-la dans Réglages › Intégrations.
4. Seuls les paiements passés à `COMPLETED` comptent.
**Shopify**
1. Dans l'administration Shopify : **Paramètres › Notifications › Webhooks › Créer un webhook**.
2. Événement : **Paiement de commande** (`orders/paid`), format **JSON**, adresse : celle de StampyWallet.
3. Copiez le secret affiché sous la liste des webhooks (« Vos webhooks seront signés avec… ») et collez-le dans Réglages › Intégrations.
4. Le client est retrouvé par l'e-mail ou le téléphone de la commande.
**SumUp**
1. SumUp envoie ses notifications de transaction à l'adresse indiquée par une application reliée à votre compte. Depuis votre espace développeur SumUp, déclarez l'adresse StampyWallet pour les transactions réussies.
2. Collez dans Réglages › Intégrations le secret de signature fourni, s'il y en a un.
3. Bêta : écrivez-nous si une vente n'arrive pas, nous regardons avec vous.
**Zettle**
1. Zettle (PayPal) envoie ses événements par son API de webhooks : créez un abonnement à l'événement d'achat créé (`PurchaseCreated`) vers l'adresse StampyWallet.
2. Collez dans Réglages › Intégrations la clé de signature de l'abonnement.
3. Bêta : écrivez-nous si une vente n'arrive pas.

## Sans code : Zapier, Make, n8n

Dans les deux sens : un outil sans code peut **envoyer** à StampyWallet les ventes d'une caisse qu'il connaît, ou **recevoir** les événements StampyWallet pour remplir un tableur, un CRM ou une liste d'e-mails.

**Zapier**
**Envoyer une vente à StampyWallet**
1. Déclencheur : votre caisse ou boutique (« New Payment », « New Order »…).
2. Action : **Webhooks by Zapier › POST**, URL : l'adresse « Autre » (format générique), type de données : JSON.
3. Corps : `{"client": {"telephone": "…"}, "montant": …, "reference": "…"}` (ou `email` à la place de `telephone`), la référence étant le numéro de la vente.

**Recevoir les événements StampyWallet**
1. Déclencheur : **Webhooks by Zapier › Catch Hook**. Copiez l'adresse du hook.
2. Collez-la comme point de réception dans Réglages › Intégrations ([Webhooks](https://stampywallet.com/docs/api/webhooks/)), puis cliquez sur « Envoyer un test ».
**Make**
**Envoyer une vente à StampyWallet**
1. Module de votre caisse en déclencheur, puis module **HTTP › Make a request**.
2. Méthode `POST`, URL : l'adresse « Autre », corps JSON `{"client": {"telephone": "…"}, "montant": …, "reference": "…"}`, comme [`POST /v1/passages`](https://stampywallet.com/docs/api/ajouter-passage/).

**Recevoir les événements StampyWallet**
1. Module **Webhooks › Custom webhook**, copiez l'adresse.
2. Collez-la comme point de réception dans Réglages › Intégrations, puis « Envoyer un test » pour que Make apprenne la structure.
**n8n**
**Envoyer une vente à StampyWallet**
1. Nœud de votre caisse en déclencheur, puis nœud **HTTP Request**.
2. Méthode `POST`, URL : l'adresse « Autre », corps JSON `{"client": {"telephone": "…"}, "montant": …, "reference": "…"}`, comme [`POST /v1/passages`](https://stampywallet.com/docs/api/ajouter-passage/).

**Recevoir les événements StampyWallet**
1. Nœud **Webhook** (méthode POST), copiez l'adresse de production.
2. Collez-la comme point de réception dans Réglages › Intégrations. Pour vérifier la signature, ajoutez un nœud **Code** avec l'exemple Node.js de la page [Webhooks](https://stampywallet.com/docs/api/webhooks/#signature).

## Une autre caisse

Si votre caisse sait appeler une adresse à chaque vente (beaucoup le font, sous le nom de « webhook » ou « notification »), utilisez l'adresse « Autre » et le [format générique](https://stampywallet.com/docs/api/entrants/#le-format-generique). Sinon, écrivez-nous depuis la page [contact](site:contact/) : nous regardons avec vous.

## Questions fréquentes

**Ça marche avec ma caisse ?**
Les réglages sont prêts pour Square, Shopify, SumUp et Zettle. Toute autre caisse qui sait appeler une adresse à chaque vente passe par le format générique, et une caisse que Zapier, Make ou n8n connaissent peut passer par eux. Sinon, écrivez-nous : nous regardons avec vous.

**Faut-il un développeur ?**
Non. Vous copiez une adresse dans StampyWallet, vous la collez dans votre caisse, puis vous collez dans StampyWallet le secret de signature que la caisse vous donne, s'il y en a un.

**Mon client doit-il déjà avoir sa carte ?**
Oui. Une caisse ne crée jamais de client : elle retrouve la carte par le téléphone ou l'e-mail du client. Une vente anonyme est ignorée, et le scan au comptoir reste alors le bon geste.

**Une vente peut-elle compter deux fois ?**
Non. Chaque vente porte sa référence : si la caisse réessaie après une coupure, le passage n'est pas posé une deuxième fois.

**Le raccordement de la caisse est-il compris dans mon abonnement ?**
Il fait partie de la formule Croissance, à 40 € HT par mois, et il est ouvert pendant l'essai gratuit de 30 jours. Il n'est pas compris dans la formule Essentiel.

Source : https://stampywallet.com/docs/api/relier-votre-caisse/

---

# Installer le skill « belles cartes »

Un fichier Markdown qui apprend à votre assistant IA à dessiner les cartes de fidélité d'un commerce comme nous le faisons : ses vraies images d'abord, les quatorze formes de carte, des icônes qui disent la récompense, et une relecture avant de montrer.

https://stampywallet.com/docs/skill.md

## Installation

**Claude**
1. **Téléchargez** [skill.md](skill.md).
2. Dans Claude, ouvrez **Paramètres › Capacités › Skills** et ajoutez le fichier (Claude accepte un dossier compressé contenant `SKILL.md` : renommez le fichier si l'interface le demande).
3. **Ajoutez le connecteur StampyWallet** (`https://app.stampywallet.com/mcp`) pour que les cartes soient rendues pour de vrai : [Brancher Claude](https://stampywallet.com/docs/mcp/claude/).
4. Demandez : « Dessine les cartes de fidélité de [nom du commerce, ville]. »
**ChatGPT**
1. **Copiez** le fichier (bouton Copier ci-dessus).
2. Dans un **Projet ChatGPT**, collez-le dans les instructions du projet.
3. **Ajoutez le connecteur StampyWallet** : [Brancher ChatGPT](https://stampywallet.com/docs/mcp/chatgpt/).
4. Dans une conversation du projet : « Dessine les cartes de fidélité de [nom du commerce]. »
**Cursor et agents**
1. Donnez à votre agent l'adresse brute : `https://stampywallet.com/docs/skill.md`, ou copiez le fichier dans le dossier de skills ou de règles de votre agent (par exemple `.claude/skills/belles-cartes/SKILL.md` pour Claude Code).
2. Ajoutez le serveur MCP `https://app.stampywallet.com/mcp` à sa configuration : [Cursor et agents](https://stampywallet.com/docs/mcp/cursor/).
3. Demandez : « Lis le skill, puis dessine les cartes de fidélité de ce commerce. »

## Ce que contient le fichier

```markdown title="skill.md"
---
name: belles-cartes-de-fidelite
description: Dessiner au moins 12 versions de la carte de
  fidélité d'un commerce, avec ses vraies images, via le
  MCP StampyWallet, relues une à une.
---

# Belles cartes de fidélité

## 1. Connaître le commerce
## 2. Trouver ses vraies images
## 3. Rendre au moins 12 versions, tous types confondus
## 4. Relire chaque carte, en grand
## 5. Présenter le choix
## 6. Mettre en service
```

La méthode, étape par étape : [Ce que fait le skill](https://stampywallet.com/docs/skill/methode/).

## Questions fréquentes

**Faut-il un compte StampyWallet ?**
Non. Le skill et l'outil `concevoir_carte` marchent sans compte. Le compte ne sert qu'à mettre la carte en service, et l'outil `creer_commerce` le crée pour vous.

**Le skill marche-t-il sans le serveur MCP ?**
Il guide l'assistant, mais sans le serveur MCP celui-ci ne peut pas rendre de vraies images de carte : il les décrit seulement.

**Puis-je le modifier ?**
Oui, c'est un simple fichier Markdown. Gardez la règle des vraies images et la relecture : ce sont elles qui font la différence.

**Les images du commerce sont-elles enregistrées ?**
Non. `concevoir_carte` les montre sur l'aperçu sans rien enregistrer. Elles ne sont posées sur la carte que si le commerçant la met en service.

Source : https://stampywallet.com/docs/skill/

---

# Ce que fait le skill

Les quatorze formes de carte, les vraies images d'abord, les icônes sous licence quand les photos ne collent pas, et la relecture de chaque carte avant de la montrer.

## Les quatorze formes

Le skill demande au moins douze versions, une par forme du moteur de cartes, pour que le commerçant voie tout ce qui est possible avant de choisir :

| Mode | Formes | Pour quoi |
|---|---|---|
| Tampons | grille, cercles, libre, objets | Une récompense au bout de N passages |
| Plusieurs récompenses | chemin, vitrine, médailles, remplissage, anneau | Des récompenses de plus en plus belles |
| Points | remplissage, anneau, chemin, vitrine, médailles | Des points selon ce que le client dépense |

Chaque forme se rend avec [`concevoir_carte`](https://stampywallet.com/docs/mcp/outils/concevoir_carte/), paramètres `mode` et `forme`. Le détail des modes : [Les types de carte](https://stampywallet.com/docs/guide/types-de-carte/).

## Les vraies images d'abord

Le logo du commerce (`logo_url`) et les photos de ses produits (`paliers[].image_url`) passent avant toute illustration. Sans couleur donnée, la carte prend les couleurs du logo. Les photos de récompense sont détourées, en gris avant d'être gagnées, en couleur après.

> **Attention :** les images d'un commerçant servent à SA carte, qu'on lui propose. Elles ne se publient nulle part ailleurs, et une illustration ne se présente jamais comme une photo du commerce.

## Icônes et licences

Quand une photo ne colle pas à une récompense (floue, hors sujet, illisible une fois réduite), le skill va chercher une icône ou une illustration qui dit la récompense au premier coup d'œil, à licence claire :

- icônes **Lucide**, **Phosphor**, **Tabler** (MIT ou ISC), recolorées aux couleurs du commerce ;
- photos et illustrations **Unsplash** ou **Pexels** ;
- ou l’une de la soixantaine d’icônes intégrées (`paliers[].icone`).

## Relire chaque carte

Avant de montrer, chaque carte s'ouvre en grand : nom entier, récompenses lisibles et non coupées, texte contrasté, logo net, photos reconnaissables même en gris. Une carte qui échoue est refaite.

## Présenter, puis mettre en service

Une planche numérotée par type, une ligne par version, et toujours la même phrase : chaque image et chaque icône se change. Le commerçant choisit un numéro ; alors seulement, [`creer_commerce`](https://stampywallet.com/docs/mcp/outils/creer_commerce/) met la carte en service (aperçu, puis accord).

![Exemple de planche de cartes](https://placehold.co/600x400 "Une planche numérotée : une carte par forme, rangées par type.")

Source : https://stampywallet.com/docs/skill/methode/