Aller au contenu
StampyWalletDocs
API et webhooks / Webhooks / Événements

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). 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 produit le même passage.cree.

ÉvénementEnvoyé quand
client.creeUn client rejoint le programme (sa carte est créée)
carte.ajouteeLe client enregistre sa carte dans Apple Wallet ou Google Wallet
passage.creeUn passage est posé : un ou plusieurs tampons, ou des points
passage.annuleLe dernier passage d'un client est annulé
recompense.atteinteUn passage franchit un palier : une récompense est due (une par palier franchi)
recompense.offerteLa récompense est remise au client
recompense.annuleeLa remise d'une récompense est annulée : elle redevient due
carte_cadeau.vendueUne carte cadeau est vendue
forfait.venduUn 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

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

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

passage.cree

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

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

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

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

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

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

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.

Mis à jour le

Cette page vous a aidé ?