Besuch erfassen
POST /v1/passages fügt der Karte eines Kunden aus Ihrer Kasse einen Stempel oder Punkte hinzu und meldet, ob eine Prämie erreicht ist.
/v1/passagesDas Gegenstück zu einem Scan an der Theke, gesendet von Ihrer Kasse: ein Stempel (oder mehrere) oder Punkte. Es gelten dieselben Regeln und Grenzen wie an der Theke, die Karte des Kunden aktualisiert sich in seinem Wallet, und der Besuch zählt wie jeder andere (Stammkunden, Erinnerungen, Bitte um Bewertung).
Body (JSON)
id, carte (der Code der Karte), email oder telephone.12.5 für 12,50 €). Hat das Geschäft eine Regel „10 € = 1 Stempel“, hat der Betrag Vorrang vor quantite; im Punktemodus wird er mit der Regel „Punkte pro Euro“ des Geschäfts umgerechnet.true: Ein unbekannter Kunde, angegeben über email oder telephone, wird angelegt (mit prenom und nom, wenn sie in client stehen). Standardmäßig false.creer_si_absent den Kunden anlegt (in client oder auf oberster Ebene).Beispiel
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('Prämie fällig!');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"])Antwort
{
"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 } }
}| Feld | Bedeutung |
|---|---|
passage.valeur | Die vergebenen Stempel oder Punkte |
passage.montant | Der gespeicherte Betrag, oder null |
rejoue | true, wenn die reference schon verwendet wurde: Die Antwort ist dann 200 und liefert den ursprünglichen Besuch, ohne ein zweites Mal zu stempeln |
client_cree | true, wenn creer_si_absent den Kunden angelegt hat |
recompense_atteinte, recompenses_gagnees | Dieser Besuch bringt eine Prämie (oder mehrere): einzulösen, wenn der Kunde sie abholt |
plafonne | true, wenn der Wert auf die Obergrenze der Theke gekürzt wurde |
client | Das Kundenobjekt nach dem Besuch |
Ablehnungen
| Status | code | Wann |
|---|---|---|
404 | client_introuvable | Kein passender Kunde, und creer_si_absent steht nicht auf true |
409 | trop_tot | Ein Besuch desselben Kunden liegt kürzer zurück als die Sperrfrist gegen Doppelbesuche des Geschäfts (standardmäßig 90 Sekunden) |
422 | montant_insuffisant | Der Betrag reicht nicht für einen Stempel (oder einen Punkt) |
422 | conditions_requises | Der Kunde würde angelegt, aber die Bedingungen des Geschäfts sind nicht akzeptiert |
Achtung : geben Sie immer eine reference an (die Bonnummer): So vergibt eine Kasse, die es nach einem Verbindungsabbruch erneut versucht, keine zwei Stempel. Eine Referenz, deren Besuch storniert wurde, wird nicht erneut vergeben.