POS Integration Guide

Dieser Guide beschreibt, wie ein Kassensystem (POS) Stamply sauber integriert: welche Daten benötigt werden, wie Kund:innen identifiziert werden, welche API-Methoden typischerweise genutzt werden und

Integrations-Modelle

A) Scan-Flow (empfohlen für schnelle POS-Integration)

Ablauf: Kassierer:in scannt QR/Wallet-Pass → POS erhält Identifier → POS/Backend ruft Stamply API auf.

Vorteile

• Minimaler Setup-Aufwand

• Keine CRM-/Kundenkonto-Abhängigkeit

Typische Nutzung

• Café, Bäckerei, Takeaway, Retail – “Kunde zeigt Code, wir buchen”

B) Auto-Flow (Customer Account / Identifier)

Ablauf: POS kennt Kund:in über Kundenkonto/ID/Telefon/E-Mail → POS/Backend mappt auf Stamply Customer → API Call.

Vorteile

• Vollautomatisch (kein Scan nötig)

• Gut für Member-basierte Businesses

Risiko/Komplexität

• Du brauchst eine stabile Customer-Mapping-Logik (und Konsent/Prozesse im POS)

Minimal benötigte POS-Daten (MVP)

Für eine robuste Integration solltest du mindestens diese Daten pro Verkauf/Transaktion haben:

Feld	Pflicht	Beispiel	Warum
transaction_id	✅	POS-2026-000123	keine Doppelbuchungen, Refund/Reverse-Zuordnung
created_at	✅	2026-01-08T12:34:56Z	Audit / Historie / Debug
total_amount	✅*	42.50	Für Spend-/Cashback-Mechaniken (falls genutzt)
currency	✅*	CHF	Für Amount-basierte Mechaniken
customer_identifier	✅	Scan-Token / Customer-ID	Kund:in muss identifiziert werden, sonst keine Buchung möglich
store_id	optional	luzern-01	Multi-Store Reporting/Debug
terminal_id	optional	t-07	Debug / Fraud / Support
line_items	optional**	SKU/Qty/Price	Nötig, wenn Regeln auf Artikelgruppen basieren sollen

* Pflicht, wenn du Spend/Cashback/Amount-Logik nutzt. ** Für einfache “1 Kauf = 1 Buchung” Integrationen nicht nötig – aber stark empfohlen, sobald Regeln/Segmente kommen.

Kund:innen-Identifikation

Ohne eindeutige Identifikation kann keine Loyalty-Aktion verbucht werden.

Scan-Flow (QR/Wallet)

• POS erhält beim Scan einen Identifier/Code (z. B. aus QR)

• Dieser Identifier wird im API Call verwendet, um die richtige Card/Customer zu finden bzw. zu buchen

Auto-Flow (Customer Account)

• POS arbeitet mit einer eigenen Kunden-ID (oder E-Mail/Telefon)

• Du brauchst ein Mapping “POS Customer” → “Stamply Customer/Card”

• Empfehlung: Mapping serverseitig halten (nicht im POS-Client)

Methode wählen: Was buche ich eigentlich?

Stamply unterscheidet je nach Card Type (ID) und Mechanik.

Praktische Defaults (für POS)

• Stamp Card (ID 0)

  • Visit-Mechanik → Add visit

  • Spend-Mechanik → Add purchase

  • Klassische Stempel → Add stamp

• Cashback (ID 1) → Add amount

• Coupon (ID 3) → Redeem coupon

• Reward (ID 7)

  • Points-Mechanik → Add scores

  • Visit-Mechanik → Add visit

  • Spend-Mechanik → Add purchase

Die vollständige “Methoden nach Kartentyp”-Matrix findest du in der API-Übersicht.

POS Event → API Aktion (Mapping)

Sale / Purchase (normaler Verkauf)

POS Event: Zahlung erfolgreich / Receipt erstellt Aktion: eine passende “Add …”-Methode auf die Karte anwenden

Beispiele:

• “1 Kauf = 1 Besuch” → Add visit

• “1 CHF = Punkte” → Add points / Add scores (je nach Card Type)

• “Spend-Mechanik” → Add purchase

• “Cashback” → Add amount

Void / Refund / Storno

POS Event: Verkauf wird komplett oder teilweise rückgängig gemacht Aktion: passende “Subtract …”-Methode anwenden (Gegenbuchung)

Voraussetzung: Du musst zu jeder Buchung transaction_id speichern, damit du exakt die richtige Buchung reversen kannst.

---

6) Idempotenz & Double-Booking vermeiden (Pflicht)

POS-Systeme senden Events manchmal doppelt (Retries, Offline-Sync, Timeouts). Deine Integration muss verhindern, dass ein Verkauf doppelt gebucht wird.

Empfohlenes Muster

• Verwende transaction_id als eindeutigen Schlüssel

• Speichere pro transaction_id:

  • welche Loyalty-Aktion du ausgeführt hast (z. B. “Add visit”, “Add purchase 42.50”)

  • Ergebnis/Response (optional)

  • Timestamp

Regel

• Kommt dieselbe transaction_id erneut: nicht erneut buchen (return success / no-op)

---

7) Rate Limit & Retry (Best Practice)

Stamply API hat ein Rate Limit (siehe API Seite). Wenn du HTTP 429 bekommst:

• Queue die Aktion (serverseitig)

• Retry mit Backoff (z. B. 1s → 2s → 4s …)

• Keine aggressiven Retries direkt aus dem POS-Client

---

8) Empfehlung für die Architektur

POS Client

• scannt / nimmt Verkauf entgegen

• sendet Event an deinen Backend-Connector (Webhook/HTTP)

Backend-Connector (Integration Service)

• hält API Key sicher

• normalisiert Daten

• sorgt für Idempotenz/Queueing

• ruft Stamply API auf

Das ist in der Praxis stabiler als direkte Calls aus dem POS-Frontend.

---

9) Debugging / Support: Was du loggen solltest

Minimal:

• transaction_id

• created_at

• store_id / terminal_id (falls vorhanden)

• gewählte API Methode (z. B. Add visit)

• Status: success / failed + HTTP Code (z. B. 429)

• Referenz auf Card/Customer-Identifier (maskiert, wenn nötig)

---