Ü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 oderidempotencyKey-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
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):
| Endpunkt | Auth / Guard | Hauptzweck |
|---|---|---|
POST /api/v1/scans/pass/:passId/use | x-scanner-key | Vom Scanner ausgelöste Stempel-, Punkte- oder Guthabenänderung über request payload. |
POST /api/v1/passes/:id/use | Arbeitsbereich-JWT / API-Schlüssel | Vom Backend-CRM oder Webhook ausgelöste Stempel- oder Punkteausführung auf einem Pass. |
POST /api/v1/mechanics/redeem | Scanner-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/state | Scanner-Schlüssel oder JWT | Liefert aktuellen Stempel-/Punktestand sowie allowedActions-Fähigkeitsflags. |
GET /api/v1/mechanics/:mechanicId/passes/:passId/ledger | Scanner-Schlüssel oder JWT | Listet historische Mechanik-Transaktionen auf (?limit=50, max. 500). |
GET /api/v1/balance-changes | Arbeitsbereich-JWT / API-Schlüssel | Fragt 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:
/api/v1/scans/pass/pass_loy_884120/use
{
"action": "INCREMENT",
"mechanicId": "11111111-2222-4333-8444-555555555555",
"amount": "2",
"deviceId": "ios-idfv-cafe-03",
"operatorId": "barista_03",
"location": "Main Counter"
}
Feld (request payload) | Typ | Validierung / Hinweise |
|---|---|---|
action | Enum (optional, Standard INCREMENT) | Einer der Werte 'INCREMENT', 'DECREMENT', 'DEBIT', 'CREDIT', 'VALIDATE', 'NOOP', 'SET'. |
mechanicId | UUID (optional) | Verifiziert die an diesen Pass gebundene Zielmechanik. |
amount | Dezimal-String (optional) | Muss dem Muster /^\d+(\.\d{1,6})?$/ entsprechen (z. B. "2" oder "12.90"). |
deviceId / operatorId / location | Strings (optional) | Werden im Audit-Ledger für die Schichtabstimmung erfasst. |
idempotencyKey | String (optional) | Muss mit dem Idempotency-Key-Header übereinstimmen, falls beide angegeben werden. |
Antwort (200 OK — IPassUseResponse):
{
"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
{
"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):
{
"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
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
Visuelle & Asset-Aktualisierung: Ersetzt stufenspezifische Hintergrundfarben, Strip-/Banner-Bilder und Stufen-Bezeichnungsfelder direkt am Pass-Datensatz.
-
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-TriggerTIER_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.
