API et webhooks / Référence / Ajouter un passage
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/passagesL'é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)
clientobjectrequis
Qui reçoit le passage : un de
id, carte (le code de la carte), email ou telephone.montantnumberfacultatif
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.quantiteintegerfacultatif
Modes tampons et paliers : nombre de tampons, 1 par défaut, 50 au plus.
pointsintegerfacultatif
Mode points, sans montant : les points à poser. Par défaut, la valeur du commerce.
referencestringfacultatif
Le numéro du ticket. Une référence ne tamponne qu'une fois par commerce.
creer_si_absentbooleanfacultatif
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_accepteesbooleanfacultatif
Quand le commerce exige ses conditions et que
creer_si_absent crée le client (dans client ou à la racine).Exemple
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
}'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 !');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
{
"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 quand le client la prend |
plafonne | true si la valeur a été ramenée au plafond du comptoir |
client | L'objet client 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.
Mis à jour le
Cette page vous a aidé ?Merci pour votre retour.