Zum Inhalt springen

Für KI-Agenten: Das Verzeichnis der Dokumentation steht unter https://stampywallet.com/de/docs/llms.txt, die gesamte Dokumentation in einer Datei unter https://stampywallet.com/de/docs/llms-full.txt, und diese Seite gibt es als Markdown: https://stampywallet.com/de/docs/api/besuch-erfassen.md (oder mit dem Header Accept: text/markdown).

StampyWalletDocs
API und Webhooks / Referenz / Besuch erfassenAls Markdown ansehen

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.

POST /v1/passages

Das 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)

client
object
erforderlich
Wer den Besuch erhält: eines von id, carte (der Code der Karte), email oder telephone.
montant
number
optional
Betrag des Bons, in Einheiten (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.
quantite
integer
optional
Modi Stempel und Stufen: Anzahl der Stempel, standardmäßig 1, höchstens 50.
points
integer
optional
Punktemodus ohne Betrag: die zu vergebenden Punkte. Standardmäßig der Wert des Geschäfts.
reference
string
optional
Die Bonnummer. Eine Referenz stempelt pro Geschäft nur einmal.
creer_si_absent
boolean
optional
true: Ein unbekannter Kunde, angegeben über email oder telephone, wird angelegt (mit prenom und nom, wenn sie in client stehen). Standardmäßig false.
conditions_acceptees
boolean
optional
Wenn das Geschäft die Zustimmung zu seinen Bedingungen verlangt und 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
  }'

Antwort

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 } }
}
FeldBedeutung
passage.valeurDie vergebenen Stempel oder Punkte
passage.montantDer gespeicherte Betrag, oder null
rejouetrue, wenn die reference schon verwendet wurde: Die Antwort ist dann 200 und liefert den ursprünglichen Besuch, ohne ein zweites Mal zu stempeln
client_creetrue, wenn creer_si_absent den Kunden angelegt hat
recompense_atteinte, recompenses_gagneesDieser Besuch bringt eine Prämie (oder mehrere): einzulösen, wenn der Kunde sie abholt
plafonnetrue, wenn der Wert auf die Obergrenze der Theke gekürzt wurde
clientDas Kundenobjekt nach dem Besuch

Ablehnungen

StatuscodeWann
404client_introuvableKein passender Kunde, und creer_si_absent steht nicht auf true
409trop_totEin Besuch desselben Kunden liegt kürzer zurück als die Sperrfrist gegen Doppelbesuche des Geschäfts (standardmäßig 90 Sekunden)
422montant_insuffisantDer Betrag reicht nicht für einen Stempel (oder einen Punkt)
422conditions_requisesDer 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.

War diese Seite hilfreich?