Skip to content
Hilfecenter-Anleitung · Einlösung & TransaktionenOnboarding-Phase 2
3 Min. LesezeitGeprüft 2026-11-16

Treuepunkte & Stempel

Vergeben Sie Stempel beim Scan, führen Sie automatische Prämien-Resets aus, berechnen Sie Besuchspunkte und Tier-Schwellenwerte.

In dieser Anleitung

Prüfen Sie passende Dashboard-Bereiche, Steuerelemente und Zoom-Hinweise zu diesem Thema.

Vergrößerter UI-Fokus
Wichtige UI-Elemente

Auswahl „Add a Pass Mechanic“ (Zoom)

Wählen Sie aus 6 integrierten Mechaniken: Stempelkarte, Stempel-Einlösung, Guthaben (Stored Value), Punkte & Stufen, Einmal-pro-Tag-Validierung oder Laufzeitverlängerung.

Überblick

Passinstance verarbeitet Stempelkarten-Prägungen, Treuepunkte-Gutschriften, automatische Stufenaufstiege und Prämieneinlösungen über Loyalty & Stamp Engine, Pass Mechanics API und Tier Progression Engine. Personal und Backend-Integrationen können Treue-Updates über einen Standard-Kassenscan (POST /api/v1/scans), die direkte Scanner-Pass-Ausführung (POST /api/v1/scans/pass/:passId/use), die arbeitsbereichsauthentifizierte Pass-Nutzung (POST /api/v1/passes/:id/use), die POS-Terminal-Einlösung (POST /v1/pos/redeem) oder die explizite Prämieneinlösung (POST /api/v1/mechanics/redeem) auslösen.

Wichtig: Alle Änderungen von Treueguthaben und Prämieneinlösungen erfolgen in atomaren Transaktionen mit strikter Idempotenzprüfung (Idempotency-Key-Header oder idempotencyKey-Feld). Nach jeder Änderung von Stempeln, Punkten oder Stufen generiert Passinstance automatisch dynamische Strip-Grafiken neu und versendet stille Push-Updates an Apple Wallet und Google Wallet.

Architektur & Ablauf der Mechanik-Ausführung

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
TREUEGUTSCHRIFT, STUFENAUFSTIEG & PRÄMIENEINLÖSUNG
BETEILIGTE SYSTEMKOMPONENTEN
P1 Scanner / POS-Terminal
P2 Loyalty & Stamp Engine / Mechanics
P3 Tier Progression Engine & Wallet-Push
SCHRITT 1 ANFRAGE / AKTION POST/api/v1/scans
SCHRITT 2 ANFRAGE / AKTION ScanAction / Mechanik ausführen:
›
{ action: "INCREMENT" }
›
INCREMENT / DECREMENT
›
CREDIT / DEBIT / SET
›
STAMP_CARD / LOYALTY_PROGRAM
SCHRITT 3 ANFRAGE / AKTION Stufenschwellen prüfen
SCHRITT 4 ANFRAGE / AKTION Stufen-Assets & Farben laden
SCHRITT 5 ANTWORT Guthaben & Ledger speichern
SCHRITT 6 ANTWORT 200 OK (resultingValue)
SCHRITT 7 ANFRAGE / AKTION POINTS_UPDATED /
›
8. APNs & Google Wallet Push
›
TIER_CHANGED-Events auslösen
›
(Neuer Strip & Stufen-Badge)

Erlaubte Mechanik-Aktionen & Status-Endpunkte

request payload akzeptiert eine von sieben expliziten Aktionen (INCREMENT, DECREMENT, DEBIT, CREDIT, VALIDATE, NOOP, SET), entsprechend der scan action-Ledger-Taxonomie (INCREMENT | DECREMENT | VALIDATE | DEBIT | CREDIT | NOOP):

EndpunktAuth / GuardHauptzweck
POST /api/v1/scans/pass/:passId/usex-scanner-keyVom Scanner ausgelöste Stempel-, Punkte- oder Guthabenänderung über request payload.
POST /api/v1/passes/:id/useArbeitsbereich-JWT / API-SchlüsselVom Backend-CRM oder Webhook ausgelöste Stempel- oder Punkteausführung auf einem Pass.
POST /api/v1/mechanics/redeemScanner-Schlüssel oder JWT (request payload)Führt eine Einlösung einer vollen Stempelkarte oder Prämie aus (action: 'DECREMENT').
GET /api/v1/mechanics/:mechanicId/passes/:passId/stateScanner-Schlüssel oder JWTLiefert aktuellen Stempel-/Punktestand sowie allowedActions-Fähigkeitsflags.
GET /api/v1/mechanics/:mechanicId/passes/:passId/ledgerScanner-Schlüssel oder JWTListet historische Mechanik-Transaktionen auf (?limit=50, max. 500).
GET /api/v1/balance-changesArbeitsbereich-JWT / API-SchlüsselFragt mandantenweite Verläufe von Treue- und Prepaid-Guthabenänderungen ab.

Endpunkte für Treuegutschriften & Prämieneinlösung

1. Direkte Mechanik-Ausführung (POST /api/v1/scans/pass/:passId/use)

Nachdem ein Scanner oder POS-Terminal den Pass abgefragt hat (GET /api/v1/scans/pass?barcode=...), kann es eine Stempelgutschrift, Punktevergabe oder Abbuchung über request payload direkt gegen die UUID :passId ausführen:

POST /api/v1/scans/pass/pass_loy_884120/use
Headers
x-scanner-key sk_live_cafe_counter_01
Idempotency-Key 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
Content-Type application/json
JSON
{
  "action": "INCREMENT",
  "mechanicId": "11111111-2222-4333-8444-555555555555",
  "amount": "2",
  "deviceId": "ios-idfv-cafe-03",
  "operatorId": "barista_03",
  "location": "Main Counter"
}
Feld (request payload)TypValidierung / Hinweise
actionEnum (optional, Standard INCREMENT)Einer der Werte 'INCREMENT', 'DECREMENT', 'DEBIT', 'CREDIT', 'VALIDATE', 'NOOP', 'SET'.
mechanicIdUUID (optional)Verifiziert die an diesen Pass gebundene Zielmechanik.
amountDezimal-String (optional)Muss dem Muster /^\d+(\.\d{1,6})?$/ entsprechen (z. B. "2" oder "12.90").
deviceId / operatorId / locationStrings (optional)Werden im Audit-Ledger für die Schichtabstimmung erfasst.
idempotencyKeyString (optional)Muss mit dem Idempotency-Key-Header übereinstimmen, falls beide angegeben werden.

Antwort (200 OK — IPassUseResponse):

JSON
{
  "success": true,
  "data": {
    "scanId": "scan_01hxyz8820ab",
    "passId": "pass_loy_884120",
    "action": "INCREMENT",
    "success": true,
    "resultingValue": "8"
  },
  "description": "Pass INCREMENT successfully",
  "errors": [],
  "statusCode": 200
}

2. Freigeschaltete Prämie einlösen (POST /api/v1/mechanics/redeem)

Wenn ein Kunde eine gesammelte Stempelkarten-Prämie beansprucht oder angesammelte Einheiten einsetzt, rufen Sie POST /api/v1/mechanics/redeem mit request payload auf:

POST /api/v1/mechanics/redeem Headers: x-scanner-key: sk_live_cafe_counter_01 (oder Authorization: Bearer <jwt>) Idempotency-Key: 4f8b92c1-7a1e-4b33-9c12-4b1c30a9d872 Content-Type: application/json

JSON
{
  "passId": "a1b2c3d4-e5f6-4a7b-8c9d-0123456789ab",
  "mechanicId": "11111111-2222-4333-8444-555555555555",
  "ruleId": "default",
  "idempotencyKey": "4f8b92c1-7a1e-4b33-9c12-4b1c30a9d872"
}

(Hinweis: Sowohl passId als auch mechanicId — sowie optional idempotencyKey im JSON-Body — müssen gültige UUIDs sein; falls ruleId übergeben wird, muss der Wert "default" lauten.)

Antwort (200 OK — IRedeemResponse):

JSON
{
  "success": true,
  "newBalance": 0,
  "newBalanceDecimal": "0",
  "reward": "default",
  "message": "Reward redeemed successfully"
}

Automatische Stufenaufstiege (Tier Progression Engine)

Immer wenn ein Scan, POST /api/v1/scans/pass/:passId/use oder POST /v1/pos/redeem (operation: "ADD_POINTS" oder "ADD_STAMPS") den Punkte- oder Besuchszähler eines Passes verändert, wertet Tier Progression Engine die konfigurierten Stufenschwellen der Vorlage aus:

  1. 1
    Schwellenwert-Auswertung: Prüft, ob der aktualisierte Stand eine höhere Stufe erreicht hat (z. B. Bronze: 0–249, Silver: 250–499, Gold: 500+).
  2. 2
    Visuelle & Asset-Aktualisierung: Ersetzt stufenspezifische Hintergrundfarben, Strip-/Banner-Bilder und Stufen-Bezeichnungsfelder direkt am Pass-Datensatz.
  3. 3
    Sperrbildschirm-Benachrichtigung: Löst eine Apple-Wallet-changeMessage-Benachrichtigung aus (z. B. „Glückwunsch! Sie haben die Gold-Stufe erreicht“) und feuert den Workflow-Trigger TIER_CHANGED, mit dem Sie automatisierte Willkommensvorteile versenden können.

Erfahren Sie mehr über das Einrichten von Treueprogrammen unter Treue- & Stempelkarten sowie über automatisierte Stufenprämien unter Workflow-Konfiguration.

Bereit für Ihr erstes Wallet-Kartenprogramm?

Erstellen Sie Ihren Workspace, konfigurieren Sie Ihre Vorlage und testen Sie eine echte Karte in Apple Wallet und Google Wallet, bevor Sie skalieren.