POS Integration Guide

Dieser Guide erklärt, welche Daten ein Kassensystem zur sauberen Stamply-Integration braucht, wie Kunden identifiziert werden, welche API-Methoden typisch sind und Doppelbuchungen vermieden werden.

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.

Doppelbuchungen vermeiden (Wichtig)

Erfahrungsgemäss senden POS-Systeme 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)