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/kassen-eingang.md (oder mit dem Header Accept: text/markdown).

StampyWalletDocs
API und Webhooks / Kassen / Kassendaten empfangenAls Markdown ansehen

Ereignisse Ihrer Kasse empfangen

POST /v1/entrants/:jeton empfängt die Verkäufe aus Square, Shopify, SumUp, Zettle oder jedem anderen Tool und schreibt den Besuch dem richtigen Kunden gut.

POST /v1/entrants/:jeton

Eine Adresse, die Sie in Ihrer Kasse hinterlegen: Bei jedem bezahlten Verkauf ruft die Kasse sie auf, und StampyWallet schreibt den Besuch auf die Karte des Kunden, den es über seine E-Mail-Adresse oder Telefonnummer findet. Sie müssen keinen Schlüssel in die Kasse eintragen: Das Token in der Adresse genügt. Eine unbekannte oder widerrufene Adresse antwortet mit 404.

Die Quellen

Jede Adresse wird für eine Quelle unter Einstellungen › Integrationen erstellt, mit einem optionalen Signaturschlüssel. StampyWallet liest dann das Format dieser Kasse so, wie es ankommt:

QuelleWas zähltKundeBetragReferenz
squarepayment.created / payment.updated mit Status COMPLETEDE-Mail des Käufers, oder E-Mail und Telefon des KundenOhne TrinkgeldDie ID der Zahlung
shopifyorders/paidE-Mail und Telefon des Kunden oder der BestellungZwischensumme der BestellungDie ID der Bestellung
sumup (Beta)Transaktion PAID oder SUCCESSFULE-Mail oder TelefonBetrag der TransaktionTransaktionscode
zettle (Beta)PurchaseCreatedE-Mail oder Telefon des KundenBetrag des KaufsDie ID des Kaufs
generiqueDer Body von POST /v1/passagesclientmontantreference (optional)

Hinweis : die Kassenquellen legen nie einen Kunden an: Ein Verkauf ohne bekannten Kunden wird ignoriert. Ein Verkauf ohne E-Mail und ohne Telefon, oder ohne Referenz, wird ebenfalls ignoriert. Nur die Quelle generique kann einen Kunden anlegen, mit creer_si_absent: true.

Die Signatur

Ist für die Adresse ein Signaturschlüssel hinterlegt, muss jeder Aufruf signiert sein, sonst 401 signature_invalide. Fügen Sie ihn immer ein, wenn die Kasse einen bereitstellt.

QuelleHeaderSignatur
generiqueX-Stampy-SignatureHMAC-SHA256 hexadezimal über den Roh-Body, mit dem Schlüssel der Adresse (sha256= davor wird akzeptiert)
squarex-square-hmacsha256-signatureHMAC-SHA256 Base64 über die Benachrichtigungs-URL, gefolgt vom Roh-Body
shopifyX-Shopify-Hmac-Sha256HMAC-SHA256 Base64 über den Roh-Body
sumupX-Payload-SignatureHMAC-SHA256 hexadezimal über den Roh-Body
zettleX-iZettle-SignatureHMAC-SHA256 hexadezimal über timestamp + "." + payload

Das generische Format

Für ein Skript, ein No-Code-Tool oder eine Kasse ohne bekanntes Format senden Sie denselben Body wie bei POST /v1/passages:

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"

Die Antworten

Sobald der Aufruf authentifiziert ist, lautet die Antwort immer 200, damit die Kasse nichts über Ihren Kundenstamm erfährt:

  • { "ok": true, "ignore": true }: Das Ereignis betrifft uns nicht (nicht bezahlt, anderes Thema, ohne Kunde, oder bei einer Kasse ohne Referenz);
  • { "ok": true }: in allen anderen Fällen, ob der Kunde existiert oder nicht, ob der Besuch gutgeschrieben oder abgelehnt wurde (zu früh, Betrag zu klein).

Nur eine echte Störung antwortet mit 500: Die Kasse versucht es erneut, und die Referenz stellt sicher, dass ein neuer Versuch nicht zweimal stempelt. Jede Adresse nimmt 300 Aufrufe pro Minute an.

Die Einstellungen Schritt für Schritt, Kasse für Kasse: Kasse anbinden.

War diese Seite hilfreich?