Überblick
Treue- & Stempelkarten digitalisieren klassische Papier-Stempelkarten („8 Kaffees kaufen, den 9. gratis erhalten“) als interaktive native Wallet-Pässe. Kundinnen und Kunden verlieren ihre Karte nie wieder, Mitarbeitende verbuchen Besuche per optischem QR-Scan in zwei Sekunden und Unternehmen fördern Wiederbesuche über automatisierte Sperrbildschirm-Mitteilungen.
Backend-Architektur & Mechanik-Enums
Digitale Stempelkarten kombinieren dynamische Strip-Grafiken mit deterministischer Regelausführung im Pass Mechanics Engine:
-
Pass-Typ (pass type):
storeCard. -
Katalog-Demo-Vorlagen:
restaurant-stamp-cardundcoffee-loyalty. -
Mechanik-Typen (mechanic type):
- STAMP_CARD_ADD: Erhöht den aktiven Stempelstand um defaultChangeValue (typischerweise 1). - STAMP_CARD_DEDUCT: Ermöglicht dem Kassenpersonal die Korrektur versehentlicher Stempel oder das Abziehen von Stempeln bei Teileinlösungen.
-
Konfiguration des visuellen Stempelrasters:
- StampImage-Array: Ordnet den Stempelpositionen 0..N individuelle Bildzustände zu (gerendert auf Apple-Strip-Grafiken und modularen Google-Wallet-Bildern). - maximumValue: Gesamtanzahl benötigter Stempel bis zur vollen Karte (z. B. 8 oder 10). - rewardImageResourceId: Individuelles Pokal- oder Prämiensymbol, das bei vollständiger Stempelkarte eingeblendet wird.
Ausführungslogik der Stempel-Engine & Obergrenzen-Verhalten
Wenn eine Mitarbeiterin oder ein Mitarbeiter den Pass scannt, prüft der Pass Mechanics Engine die aktiven Schwellenwerte:
-
1
Stempel-Inkrement: Addiert
defaultChangeValue(Standard1) zum aktuellen Pass-Stand:
newStamps = clamp(currentStamps + defaultChangeValue, 0, maximumValue)
-
2
Verhalten bei Erreichen des Limits (
onCap) & Aktionssemantik (scan action / transaction type):
- onCap: "noop": Erreicht die Karte die maximale Stempelzahl, gibt die Engine { ok: true, reason: "Card is full", appliedAction: "NOOP" } zurück. Der volle Kartenstand bleibt sichtbar, damit das Personal die abgeschlossene Karte prüfen und die Prämie aushändigen kann. - onCap: "reset": Löst automatisch das Prämienereignis aus und setzt die Stempel auf 0 zurück: { ok: true, reason: "Card reset" }. - Standardverhalten: Gibt { ok: false, reason: "Stamp card is full" } zurück und fordert das Personal auf, den separaten Einlöseprozess anzustoßen (POST /api/v1/mechanics/redeem oder POST /api/v1/passes/:id/use mit scan action: INCREMENT, DECREMENT, VALIDATE, protokolliert mit transaction type: EARN, REDEEM, ADJUST, SCAN).
-
3
Verhalten bei Prämieneinlösung (
rewardClaimBehavior):
- RESET_TO_ZERO: Setzt bei Einlösung durch das Personal alle Stempel auf 0 zurück. - START_NEW_CYCLE: Überträgt überschüssige Stempel aus größeren Einkäufen direkt in den nächsten Prämienzyklus. - KEEP_COMPLETED: Behält den vollständigen visuellen Zustand bei, bis der Prämien-Coupon eingelöst wurde.
-
4
CRM-Korrelation (
externalId): Verknüpfen Sie Ihre Kunden- bzw. Treueprogramm-ID mitPass.externalId, damit POS, Webshop und mobile App Stempelaktualisierungen sauber überPOST /api/v1/passes/upsert-by-external-idsynchronisieren können.

Schutz gegen Mehrfachscans pro Tag (VALID_ONCE_PER_DAY)
Um versehentliches doppeltes Abstempeln oder Missbrauch an der Kasse zu verhindern, fügen Sie die Sekundärregel VALID_ONCE_PER_DAY hinzu:
-
Die Engine ermittelt die Zeitzone des Händlerstandorts über
resolveCustomerTimeZone. -
Scannt ein Teammitglied dieselbe Kundenkarte am selben Kalendertag ein zweites Mal, liefert der zweite Scan eine informative Warnung (
ALREADY_SCANNED_TODAY), ohne einen unberechtigten zweiten Stempel hinzuzufügen.
Sperrbildschirm-Updates in Echtzeit
Sobald ein Stempel gutgeschrieben oder eingelöst wird:
-
Passinstance sendet eine stille APNs-Benachrichtigung an das iPhone der Kundin oder des Kunden.
-
Apple Wallet aktualisiert die visuelle Stempelgrafik und blendet einen Sperrbildschirm-Hinweis ein: „Sie haben einen Stempel erhalten! Sie haben jetzt 5 von 8 Stempeln.“
-
Google Wallet aktualisiert das Live-Karten-Widget und zeigt auf Android eine Benachrichtigung an.
Wichtig: Dynamische Stempelkarten-Strip-Grafiken werden von der Passinstance-Grafik-Engine automatisch in Retina-Auflösungen (@1x, @2x, @3x) gerendert und garantieren gestochen scharfe Stempelmarken auf hochauflösenden Smartphone-Displays.
Lesen Sie unsere vollständige Übersicht zu Digitalen Stempelkarten, entdecken Sie Restaurants & Cafés oder sehen Sie sich den Leitfaden zu Stempelsammelregeln an.
