Zum Hauptinhalt springen

LOOP Loyalty — API-Vertrag

Was​

Frontend-Vertrag (URLs, BFF, Cookie, Einlösen B/C, Status-Links): LOOP — v0-Integrationsvertrag.

LOOP ist die Bindungsstufe von NOW!: eine pseudonyme Karte pro Besucher und Center, Stempelkarten je Shop (z. B. 10 Stempel = Gratis-Cappuccino) und centerweite Punkte. PR1: Datenmodell, Stempel-Logik und APIs. PR2 (Wallet): Apple/Google Wallet über Passcreator (serverseitig im Cockpit). Noch nicht enthalten: Status-Stufen, Member-Konto, Parken, Bon-Upload.

Ohne Händler-App: Das Ladenpersonal braucht kein eigenes Gerät und keinen Login. Es handelt direkt am Kundenhandy: Wischen beim Einlösen, Laden-PIN beim Verschenken von Stempeln.

Warum​

NOW! lockt Besucher an (Deals, Drops, Concierge). LOOP holt sie zurück und liefert den Nachweis, dass ein Besuch im Laden stattgefunden hat. Konzept und Freigabe: docs/LOOP-IN-NOW-VORSCHLAG.md (PR #324).

Wer​

WerNutzt
Besucher (über v0-Frontend / NOW!)Public-API: Karte anlegen, Stand lesen, stempeln, einlösen, Wallet-Pass (Add-to-Wallet-URLs)
Ladenpersonal (am Kundenhandy, ohne eigenes Gerät)Wischen beim Einlösen, Laden-PIN beim Verschenken
Center-Management / SMGDashboard-API und AgencyOS/MCP: Programm, Stempelkarten inkl. Laden-PIN, Stempelpunkte, Kennzahlen

Besucher-Oberflächen (Stempel-Screen, Einlöse-Screen, Verschenken-Screen, Kartenstand) werden in v0 gebaut, nicht in apps/digital-signage. Cockpit liefert Regeln, Daten und APIs.

Wo​

Public-API (ohne Login, CORS offen, Rate-Limits pro IP)​

Besucher-Auth: Authorization: Bearer <cardToken>. Das Token kommt einmalig aus POST /cards; v0 speichert es. Die Datenbank kennt nur den SHA-256-Hash.

MethodePfadBodyAntwort data
POST/api/public/loyalty/cards{ centerId }{ cardToken, recoveryToken, recoveryUrl, card } (201)
POST/api/public/loyalty/session/restore{ recoveryToken }{ cardToken, card } (200) — Session-Reentry, siehe Session Reentry
GET/api/public/loyalty/cards/me—card
GET/api/public/loyalty/cards/me/reentry—{ reentryToken } (geplant, Wiedereinstieg)
POST/api/public/loyalty/cards/reentry{ reentryToken } (ohne Bearer){ cardToken, card } (geplant, Wiedereinstieg)
POST/api/public/loyalty/stamps{ code, source?: 'nfc' | 'qr' }{ stampCount, rewardsAvailable, rewardsEarned, pointsAwarded, card }
POST/api/public/loyalty/stamps/gift{ code, stamps, pin, reason? }{ stampCount, rewardsAvailable, rewardsEarned, pointsAwarded, card }
POST/api/public/loyalty/redemptions/counter{ code } (Stempelpunkt){ code, expiresAt, rewardTitle, shopName, serverTime, redemptionMode }
POST/api/public/loyalty/redemptions/counter/confirm{ redemptionCode, pin? } (pin nur im Modus C){ status: 'redeemed', rewardTitle, shopId, redeemedAt, card }
POST/api/public/loyalty/redemptions/points{ code } (Stempelpunkt des Prämien-Shops){ code, expiresAt, rewardTitle, shopName, serverTime, redemptionMode: 'counter', pointsCost, pointsBalance }
POST/api/public/loyalty/redemptions/points/confirm{ redemptionCode } (PR-…){ status: 'redeemed', rewardTitle, shopId, pointsSpent, redeemedAt, card }
GET/api/public/loyalty/wallet/capabilities?centerId=—{ provider, configured, enabled, templateConfigured }
GET/api/public/loyalty/wallet/pass—{ pass } (nur wenn Pass schon verknüpft)
POST/api/public/loyalty/wallet/pass—{ pass } (201 — Pass anlegen oder aktualisieren)

pass (Wallet):

{
"passIdentifier": "…",
"downloadPage": "https://app.passcreator.com/p/…",
"appleWalletUrl": "https://app.passcreator.com/…pkpass",
"androidWalletUrl": "https://pay.google.com/gp/v/save/…",
"cardNumber": "LP-7K3M-9QX2",
"storedValue": 40
}
  • v0 zeigt appleWalletUrl / androidWalletUrl als Redirect oder Link („Zu Apple Wallet hinzufügen“).
  • Kein Passcreator-API-Key im Browser — nur serverseitig (PASSCREATOR_API_KEY auf dem Dashboard).
  • Nach Stempel aktualisiert das Cockpit den Pass automatisch, wenn autoSyncOnStamp=true und die Karte bereits einen Pass hat.
  • Ein Passcreator-Master-Template für alle Center (Variante A): Das Branding je Pass kommt aus den Cockpit-Center-Daten, nicht aus einem eigenen Template pro Center. Beim Anlegen und bei jedem Update sendet das Cockpit templateFields mit den Center-Daten.
  • Das Passcreator-Template muss diese dynamischen Felder definieren (Feldname = API-Schlüssel):
FeldQuellePflicht
centerNameShoppingCenter.name (Fallback LOOP, wenn leer)ja
cardNumberKartennummer (auch Barcode-Wert)ja
pointsBalanceaktuelle Punkte/Stempelja
storedValuespiegelt pointsBalance (Passcreator-Standardfeld, Feld im Template aktivieren)ja
centerSlugShoppingCenter.slug — nur gesendet, wenn das Center einen Slug hatoptional
recoveryUrlBesucher-App Reentry /k/<token> (Back-Feld); siehe Session Reentryoptional
  • Das Template-Barcode-Feld zeigt auf cardNumber. Felder, die das Template nicht definiert, ignoriert Passcreator.
  • Farben & Logo je Pass: Beim Anlegen/Aktualisieren sendet das Cockpit zusätzlich backgroundColor, foregroundColor, labelColor (aus ShoppingCenter.baseColor) und optional urlToLogo (HTTPS aus logoUrl/logo). Passcreator setzt das nur um, wenn am Master-Template *DifferentForEachPass aktiv ist — einmalig per Bootstrap --apply-pilot-branding. Demo-logoText/description am Template werden dort ebenfalls bereinigt.
  • Sperrbildschirm-Text: Die Pass-description in Apple Wallet kommt weiterhin aus dem Passcreator-Template (Bootstrap), nicht pro API-Call; der Centername steht auf dem Pass in den Feldern (centerName).

card:

{
"cardNumber": "LP-7K3M-9QX2",
"centerId": "…",
"pointsBalance": 40,
"pointsReward": { "title": "1 Stunde gratis parken", "cost": 100, "shopId": "…", "shopName": "Q-Park", "available": false, "missing": 60 },
"stampCards": [
{
"stampCardId": "…",
"shopId": "…",
"shopName": "Café Linde",
"title": "Stempelkarte",
"rewardTitle": "Gratis-Cappuccino",
"stampsRequired": 10,
"stampCount": 6,
"rewardsAvailable": 0,
"redemptionMode": "counter"
}
]
}
  • redemptionMode: counter (Modus B, nur Wischen) oder counter_pin (Modus C, PIN-Feld zeigen), siehe Modus C.
  • cardNumber ist kein Geheimnis: Kasse und Wallet-Barcode.
  • code beim Stempeln, Verschenken und Einlösen stammt aus der NFC-/QR-URL des Stempelpunkts an der Kasse (siehe Admin-API). Er belegt, dass der Kunde im Laden steht.

Einlösen an der Kasse (NFC-Tag und Wischen)​

  1. Kunde mit voller Karte tippt an den NFC-Tag der Kasse. v0 ruft …/redemptions/counter mit dem Tag-Code auf.
  2. v0 zeigt einen großen grünen Live-Bildschirm (Prämie, Shopname, laufende Uhrzeit aus serverTime, Animation), damit ein Screenshot auffällt. Der Vorgang gilt 3 Minuten; ein offener Vorgang wird wiederverwendet.
  3. Das Personal wischt auf dem Kundenhandy „Eingelöst“. v0 ruft …/redemptions/counter/confirm auf. Genau eine Prämie wird verbraucht, ein zweites Bestätigen liefert CODE_USED. Danach wird der Wallet-Pass wie nach einem Stempel synchronisiert.

Restrisiko: Wer die Tag-URL kopiert, könnte außerhalb des Ladens starten und selbst wischen. Er löst damit nur eine Prämie ein, die er wirklich erstempelt hat. Auffälligkeiten zeigen sich in stats.redemptions je Center.

Stempel verschenken (Laden-PIN am Kundenhandy)​

Das Personal kann einer Karte mehrere Stempel schenken (z. B. Entschuldigung, Großeinkauf):

  1. Kunde tippt an den NFC-Tag der Kasse.
  2. Das Personal wählt auf dem Kundenhandy die Anzahl und gibt die Laden-PIN ein (4–6 Ziffern, je Stempelkarte im Dashboard gesetzt). v0 ruft …/stamps/gift auf.

Regeln (serverseitig):

  • Grenzen aus dem Center-Programm: manualGrantMaxPerAction (Standard 5) und manualGrantMaxPerShopDay (Standard 20, Kalendertag Europe/Berlin).
  • Nach 5 falschen PINs ist die PIN des Shops 15 Minuten gesperrt (PIN_LOCKED, details.lockedUntil). Fehlversuche bleiben gespeichert, auch wenn die Anfrage scheitert.
  • Die PIN wird nur als scrypt-Hash gespeichert und nie ausgegeben; Admin-Antworten zeigen hasStaffPin.
  • Jeder Vorgang steht mit Anzahl und Grund in loyalty_stamp_events (source = manual).
  • Verschenkte Stempel bringen keine Center-Punkte, außer manualStampsEarnPoints = true.

Dashboard-API (Session + Center-Zugriff)​

MethodePfadRollen
GET, PUT/api/centers/{centerId}/loyalty/programSUPER_ADMIN, DEVELOPER, PLATFORM_ADMIN, CENTER_ADMIN, ORG_MARKETING_MANAGER, CENTER_MANAGER
GET, POST/api/centers/{centerId}/loyalty/stamp-cardswie oben (POST legt an oder aktualisiert, eine Karte pro Shop)
GET, POST/api/centers/{centerId}/loyalty/stamp-pointswie oben (POST erzeugt einen Stempelpunkt mit code)
PATCH/api/centers/{centerId}/loyalty/stamp-points/{pointId}wie oben — Body { "isActive": boolean }; 404, wenn der Punkt nicht zum Center gehört. Kein DELETE (Historie).
GET/api/centers/{centerId}/loyalty/stats?days=30[&groupBy=day]zusätzlich CONTENT_EDITOR, AGENCY_CONTENT_EDITOR, CM_ASSISTANT
GET, PUT/api/centers/{centerId}/loyalty/wallet-configwie Programm (Passcreator-Template, Sync)
GET/api/centers/{centerId}/loyalty/shopswie Programm — nur id und name der Center-Shops (Auswahlliste der Dashboard-Oberfläche)

Tagesverlauf: Mit groupBy=day enthält die Stats-Antwort zusätzlich daily — lückenlose Liste der letzten days Kalendertage (Europe/Berlin, älteste zuerst) mit { date, stamps, manualStamps, redemptions }. Ohne Parameter bleibt die Antwort unverändert. Stempelpunkte (Codes) sind bewusst nicht über AgencyOS/MCP lesbar; Anlegen und Deaktivieren laufen über die Dashboard-Session.

Programmfelder (PUT, nur übergebene Felder): isActive, pointsPerStamp (0–1000), stampCooldownMinutes (0–1440, Standard 8 Minuten zwischen zwei Stempeln derselben Karte im selben Shop), manualGrantMaxPerAction (1–50), manualGrantMaxPerShopDay (1–500), manualStampsEarnPoints, visitorAppBaseUrl (Basis-URL der Besucher-Anwendung, siehe unten), pointsRewardTitle, pointsRewardCost (1–100000, Standard 100), pointsRewardShopId (Punkte-Prämie, siehe unten). Ohne gespeichertes Programm gelten die Standardwerte mit isActive = false, visitorAppBaseUrl = null und pointsRewardTitle = null.

Punkte-Prämie (centerweit): Wofür Besucher ihre Center-Punkte einlösen, im Pilot CARRÉ „1 Stunde gratis parken“. pointsRewardTitle (bis 120 Zeichen; null oder leer = Punkte werden nur gesammelt) und pointsRewardShopId (Shop des Centers, z. B. das Parkhaus oder die Center-Info; null = keine Einlösung) gehören zusammen: Eingelöst wird am Stempelpunkt dieses Shops, der Shop braucht keine Stempelkarte. Ein pointsRewardShopId außerhalb des Centers wird mit 404 NOT_FOUND abgelehnt. pointsRewardCost ist der Preis in Punkten je Einlösung; bei 10 Punkten je Stempel sind 100 Punkte zehn Einkäufe. Die Karte (GET /cards/me) zeigt pointsReward mit available und missing, oder null, wenn keine Prämie eingerichtet ist. Tippt eine Karte am Stempelpunkt des Prämien-Shops auf Stempeln (POST /stamps), antwortet die API 409 POINTS_REWARD_POINT mit details { rewardTitle, pointsCost, pointsBalance, available }: Das Frontend bietet dann „Einlösen“ an statt zu stempeln.

redemptionCodeTtlMinutes wird nicht mehr angenommen: Wird es gesendet, antwortet die API 400 INVALID_INPUT („redemptionCodeTtlMinutes wird nicht mehr unterstützt …“), und die Lese-Antwort enthält das Feld nicht mehr. Einlösen an der Kasse gilt fest 3 Minuten (die Datenbankspalte bleibt aus Kompatibilitätsgründen bestehen).

visitorAppBaseUrl: Adresse der Stempel-Seite der Besucher-Anwendung (v0), z. B. https://<v0-Domain>/loop/stempel. Das Dashboard hängt nur ?code=<Stempelpunkt-Code> an und erzeugt daraus QR-Code und NFC-Inhalt; die Adresse gilt je Center für das ganze Team und jedes Gerät. Regeln: https ist Pflicht (http nur für localhost), höchstens 300 Zeichen, keine Zugangsdaten, kein #-Anker, abschließende / werden entfernt; null oder leer entfernt den Wert. Fehlerantwort: 400 INVALID_INPUT mit visitorAppBaseUrl: …. Der übliche Pfad ist /loop/stempel (siehe Integrationsvertrag); das Dashboard weist darauf hin, sperrt aber andere Pfade nicht. Schon gedruckte Codes behalten die alte Adresse.

Stempelkarten-Felder (POST): shopId, rewardTitle (Pflicht), stampsRequired (1–50, Standard 10), title, isActive, staffPin (4–6 Ziffern; null entfernt die PIN; weglassen = unverändert), requireRedeemPin (Modus C, siehe unten; weglassen = unverändert, neue Karte false). Eine neue PIN setzt eine bestehende Sperre zurück. Antwort enthält hasStaffPin, pinLockedUntil und requireRedeemPin, nie die PIN selbst. requireRedeemPin: true ohne gesetzte Laden-PIN (oder zusammen mit staffPin: null) wird mit 400 INVALID_INPUT abgelehnt.

AgencyOS-API und MCP​

MethodePfadMCP-Tool
GET/api/agencyos/v1/centers/{centerId}/loyalty/programcockpit_loyalty_program_get
PATCH/api/agencyos/v1/centers/{centerId}/loyalty/programcockpit_loyalty_program_update
GET/api/agencyos/v1/centers/{centerId}/loyalty/stamp-cardscockpit_loyalty_stamp_cards_list
POST/api/agencyos/v1/centers/{centerId}/loyalty/stamp-cardscockpit_loyalty_stamp_card_upsert (inkl. staffPin)
GET/api/agencyos/v1/centers/{centerId}/loyalty/stats (?days=, ?groupBy=day)cockpit_loyalty_stats (days, groupBy)
GET/api/agencyos/v1/centers/{centerId}/loyalty/wallet-configcockpit_loyalty_wallet_config_get
PATCH/api/agencyos/v1/centers/{centerId}/loyalty/wallet-configcockpit_loyalty_wallet_config_update

Wallet-Konfiguration (PATCH, nur übergebene Felder): isEnabled, passcreatorTemplateId (string oder null), autoSyncOnStamp (Standard true), pushNotificationOnStamp (Standard false). Antwort enthält providerConfigured (ob PASSCREATOR_API_KEY auf dem Server gesetzt ist).

Ausblick (separates Epic, nicht PR2/Pilot): Pass-Branding (Logo, Farben, Layout) vollständig aus dem Cockpit über die Passcreator Template-API oder später ein eigener Wallet-Issuer ohne Passcreator — siehe project_specs.md (LOOP Wallet — Branding aus Cockpit / eigener Issuer) und Ausblick in der Dashboard-Doku.

Schreibende Tools sind als write-config eingestuft.

Fehler​

{ success: false, error: '<Text>', code, details? }

codeHTTPBedeutung
INVALID_INPUT400Pflichtfeld fehlt oder ungültig
INVALID_CARD401Token fehlt oder Karte unbekannt
PIN_INVALID403Laden-PIN falsch
NOT_FOUND404Center, Shop, Stempelpunkt, Karte oder Vorgang unbekannt
PROGRAM_INACTIVE409LOOP im Center nicht aktiv
NO_REWARD409keine Prämie verfügbar
CODE_USED409Einlöse-Vorgang schon bestätigt
PIN_NOT_SET409für diesen Shop ist keine Laden-PIN hinterlegt
CODE_EXPIRED410Einlöse-Vorgang abgelaufen (3 Minuten)
LIMIT_REACHED422Grenze für verschenkte Stempel (pro Vorgang oder pro Shop und Tag)
PIN_LOCKED423zu viele falsche PINs, details.lockedUntil
COOLDOWN429Sperrfrist je Shop läuft, details.nextAllowedAt
WALLET_DISABLED409Wallet im Center nicht aktiv
WALLET_NOT_CONFIGURED409Passcreator-Template fehlt
WALLET_NOT_LINKED404GET Pass ohne vorheriges POST
WALLET_UNAVAILABLE502/503Passcreator-Key fehlt oder Provider-Fehler
POINTS_REWARD_POINT409POST /stamps am Stempelpunkt des Prämien-Shops: hier wird nicht gestempelt, sondern die Punkte-Prämie eingelöst (details.rewardTitle, pointsCost, pointsBalance, available)
NOT_ENOUGH_POINTS409Punkte-Prämie: Guthaben reicht nicht (details.pointsBalance, pointsCost, missing)
REENTRY_INVALID404Wiedereinstieg: Token unbekannt oder rotiert (geplant)

Rate-Limit pro IP (429 mit Retry-After): Karte anlegen 20/h, Karte lesen 120/min, Stempeln 60/15 min, Verschenken 20/15 min, Einlösen 30/15 min, Wallet-Pass 30/h.

Wiedereinstieg: Stateless Reentry, zwei Spuren (geplant, Cockpit-Teil offen)​

Problem (Befund 11.10.2026): Die Karte hängt im Besucher-Frontend am httpOnly-Cookie loop_card. Der iOS Code-Scanner aus dem Kontrollzentrum, die In-App-Browser von Instagram und Facebook sowie Android-WebViews haben eigene Cookie-Speicher (SFSafariViewController ist seit iOS 11 von Safari isoliert, WWDC 2017 Session 225). Dort fehlt das Cookie, und beim Scan entsteht stumm eine neue, leere Karte. Die Kamera-App, NFC-Hintergrundlesen und Chrome Custom Tabs sind nicht betroffen.

Lösung: Der Wiedereinstieg darf nicht vom Browserzustand abhängen. Jede Karte bekommt einen festen Reentry-Token, der die Karte in jedem Browser öffnet. Zwei Spuren führen zur selben Karte:

SpurWegZustand
1 · Cookiegleicher Browser, loop_card vorhandenwie bisher, nichts ändert sich
2 · Reentry-Linkhttps://<Besucher-Domain>/k/<reentryToken> aus dem Wallet-Pass oder vom Nutzer gesichert („Karte sichern“)Frontend tauscht den Token gegen cardToken, setzt das Cookie, leitet auf /loop

Cockpit-Teil (Saad, offen):

MethodePfadAuthAntwort
GET/api/public/loyalty/cards/me/reentryBearer cardToken{ reentryToken } — beim ersten Aufruf erzeugen, danach stabil
POST/api/public/loyalty/cards/reentrykeine{ cardToken, card } (200); unbekannt → 404 REENTRY_INVALID
POST/api/public/loyalty/cards/me/reentry/rotateBearer{ reentryToken } neu, alter ungültig (optional, zweite Stufe)
  • Token: 32 Byte zufällig, base64url (43 Zeichen, erlaubt [A-Za-z0-9_-]{20,200}), in der Datenbank nur als SHA-256-Hash wie cardToken. Additive Migration: Spalte reentry_token_hash an loyalty_cards oder eigene Tabelle.
  • Der Token öffnet nur: Er liefert cardToken + card. Stempeln, Einlösen und Verschenken bleiben an den Bearer-Token gebunden. Ein geleakter Link gibt also dieselben Rechte wie das Cookie, nicht mehr.
  • Rate-Limit POST /cards/reentry pro IP wie Karte anlegen (20/h), damit Raten unmöglich bleibt.
  • Wallet-Pass: Rückseite bekommt ein Feld „Karte öffnen“ mit dem Link <visitorAppBaseUrl-Origin>/k/<reentryToken> (Apple: attributedValue mit <a href> und Roh-URL im value; Google: appLinkData.webAppLinkInfo). Origin = visitorAppBaseUrl ohne Pfad (https://now-loop.vercel.app). Bei Rotation Pass aktualisieren.
  • Der Reentry-Token erscheint nie in Logs, Analytics oder im Referrer.

Frontend-Teil (umgesetzt in smg-loop-app, 11.10.2026):

  • GET /k/<reentryToken> → Cockpit POST /cards/reentry → Cookie setzen → 302 /loop?wiederhergestellt=ok; Token ungültig → …=invalid; Cockpit-Route fehlt noch (404 ohne code) → …=unavailable. Referrer-Policy: no-referrer.
  • GET /api/loop/cards/reentry → Cockpit GET /cards/me/reentry → { url } (eigene Domain + /k/<token>).
  • /loop: Block „Karte sichern“ (Link teilen oder kopieren), Onboarding-Hinweis „Schon eine Karte? Über Wallet-Pass oder gesicherten Link öffnen“, Hinweis bei erkanntem In-App-Browser mit „In Safari/Chrome öffnen“.
  • Solange das Cockpit die Routen nicht hat, bleibt „Karte sichern“ unsichtbar und /k/… zeigt „noch nicht verfügbar“.

Punkte-Prämie einlösen (Ablauf)​

Gleicher Ablauf wie das Einlösen an der Kasse, nur mit Punkten statt Stempelkarte und ohne Laden-PIN:

  1. Besucher tippt den Stempelpunkt des Prämien-Shops an (z. B. Parkhaus-Kasse). POST /redemptions/points mit dem Stempelpunkt-code → PR-…, gilt 3 Minuten; offene Vorgänge derselben Karte werden wiederverwendet. Reicht das Guthaben nicht: 409 NOT_ENOUGH_POINTS.
  2. Grüner Live-Bildschirm mit Prämie, Shop und Serveruhr; das Personal wischt. POST /redemptions/points/confirm mit redemptionCode zieht pointsCost Punkte genau einmal ab (Kartensperre, Ledger-Buchung reason = points_reward, delta < 0). Zweites Bestätigen → CODE_USED, nach Ablauf → CODE_EXPIRED. Danach Wallet-Sync wie nach einem Stempel.

Tabelle loyalty_points_redemptions (eigene Tabelle, additiv; loyalty_redemptions bleibt für Stempelkarten). Kennzahlen: stats enthält zusätzlich pointsRedemptions (Anzahl) und pointsRedeemed (abgezogene Punkte, positiv).

So testen​

  1. Programm aktivieren: PUT /api/centers/{centerId}/loyalty/program mit { "isActive": true }.
  2. Stempelkarte anlegen: POST …/loyalty/stamp-cards mit { "shopId": "…", "rewardTitle": "Gratis-Cappuccino", "stampsRequired": 3, "staffPin": "4711" } → hasStaffPin: true.
  3. Stempelpunkt anlegen: POST …/loyalty/stamp-points mit { "shopId": "…" } → code merken.
  4. Karte anlegen: POST /api/public/loyalty/cards mit { "centerId": "…" } → cardToken merken.
  5. Stempeln: POST /api/public/loyalty/stamps mit Bearer und { "code": "…" } → stampCount: 1, pointsAwarded: 10. Sofort erneut → COOLDOWN (Standard-Sperrfrist 8 Minuten).
  6. Verschenken: POST /api/public/loyalty/stamps/gift mit { "code": "…", "stamps": 2, "pin": "4711" } → rewardsEarned: 1, pointsAwarded: 0. Falsche PIN → PIN_INVALID; fünfmal falsch → PIN_LOCKED.
  7. Einlösen: POST /api/public/loyalty/redemptions/counter mit dem Stempelpunkt-code → LR-…, dann POST …/redemptions/counter/confirm mit redemptionCode. Zweites Confirm → CODE_USED.
  8. Kennzahlen: GET …/loyalty/stats zeigt Stempel je Shop, davon verschenkt, und eine Einlösung.

Wallet (Staging, Passcreator):

  1. PASSCREATOR_API_KEY auf dem Dashboard setzen; Health: GET /api/integrations/passcreator/health (Admin-Session, prüft Passcreator-Listing GET /api/pass-template — nicht /api/v2/pass-template, dort 404).
  2. Master-Template optional: node scripts/passcreator-bootstrap-loop-master-template.mjs (Dry-Run), mit --apply anlegen — siehe Passcreator Bootstrap.
  3. PATCH /api/agencyos/v1/centers/{centerId}/loyalty/wallet-config mit { "isEnabled": true, "passcreatorTemplateId": "…" }.
  4. Karte wie oben anlegen → POST /api/public/loyalty/wallet/pass mit Bearer → appleWalletUrl / androidWalletUrl.
  5. Stempeln → Pass storedValue / Push (wenn pushNotificationOnStamp=true) via Passcreator-Update.

Unit-Tests: passcreator-api-paths.test.ts, loyalty-rules.test.ts, loyalty-wallet-rules.test.ts (inkl. buildWalletTemplateFields), loyalty-stamp-url.test.ts, loyalty-launch-checklist.test.ts (in pnpm test:ci).

Punkte-Prämie (Staging):

  1. PATCH …/loyalty/program mit { "pointsRewardTitle": "1 Stunde gratis parken", "pointsRewardCost": 20, "pointsRewardShopId": "<Parkhaus-Shop>" }, für diesen Shop einen Stempelpunkt anlegen (keine Stempelkarte).
  2. Zwei Stempel in einem anderen Shop sammeln (20 Punkte). POST /stamps mit dem Parkhaus-Code → 409 POINTS_REWARD_POINT, details.available: true.
  3. POST /redemptions/points mit dem Parkhaus-Code → PR-…; POST /redemptions/points/confirm → pointsSpent: 20, card.pointsBalance: 0; zweites Bestätigen → CODE_USED. GET …/stats zeigt pointsRedemptions: 1, pointsRedeemed: 20.

Betrieb​

  • Tabellen: loyalty_programs, loyalty_wallet_configs, loyalty_stamp_cards, loyalty_stamp_points, loyalty_cards (inkl. passcreator_pass_identifier, wallet_linked_at), loyalty_card_progress, loyalty_stamp_events, loyalty_points_ledger, loyalty_redemptions (siehe db_structure.md). Migrationen: 20261009120000_add_loop_loyalty_SAFE.sql, 20261009153000_add_loop_wallet_passcreator_SAFE.sql, 20261009180000_loop_pin_cooldown_SAFE.sql (Laden-PIN, Sperrfrist-Standard 8), 20261009210000_loop_visitor_app_base_url_SAFE.sql (loyalty_programs.visitor_app_base_url), 20261009220000_loop_redeem_pin_SAFE.sql (loyalty_stamp_cards.require_redeem_pin). Beide Spalten sind additiv (nullable bzw. DEFAULT false); vor dem Deploy ausführen.
  • Env: PASSCREATOR_API_KEY (org-weit, nur Dashboard/Render — nie in v0).
  • Code: apps/dashboard/src/lib/loyalty/, apps/dashboard/src/lib/integration/passcreator-client.ts.
  • Gleichzeitige Stempel werden pro Karte serialisiert (SELECT … FOR UPDATE), Verschenken zusätzlich pro Stempelkarte (Tageslimit und PIN-Fehlversuche).
  • Gesperrte PIN entsperren: neue PIN über die Stempelkarte setzen (Dashboard oder API; setzt Zähler und Sperre zurück).
  • Rate-Limits abschalten (nur lokal): COCKPIT_DISABLE_PUBLIC_VISITOR_RATE_LIMIT=1.
  • CORS für v0: Die Middleware beantwortet Preflight-Anfragen auf /api/* selbst und setzt Access-Control-Allow-Origin nur für *.cockpit-os.de (und lokal). Weil die Public-Loyalty-Routen einen Authorization-Header brauchen, sollte ein v0-Frontend auf fremder Domain sie serverseitig aufrufen (eigene Route im v0-Projekt). Direkter Browser-Aufruf von fremden Domains braucht eine Erweiterung der Allowlist.
  • Datenschutz: keine personenbezogenen Daten; Kennzahlen nur aggregiert. Händler sehen keine Einzelkarten.

Einlöse-Modi​

Was: Pilot-Standard ist Modus B (am Kundenhandy, NFC-Tag, Wischen). Modus C ist derselbe Ablauf mit optionaler Laden-PIN vor dem Wischen, auf demselben Bildschirm. Es gibt keine Partner-App und keinen Händler-Login. Der frühere Partner-Code-Weg („Modus A“) wurde mit PR #334 vollständig entfernt: Es gibt weder die Public-Route noch Partner-Routen dafür.

Warum: Eine Partner-App an jeder Kasse skaliert nicht, und LOOP greift nicht in Kassensysteme ein. Der NFC-Tag (Stempelpunkt) belegt, dass der Kunde im Laden steht. Das Personal braucht kein eigenes Gerät.

Wer ist betroffen: Besucher und Ladenpersonal (Bedienung), SMG/v0-Frontend (Signage, Companion/NOW!), Center-Betrieb (Konfiguration).

Vollständige Frontend-Vertragsseite: LOOP — v0-Integrationsvertrag (URLs, BFF, Cookie, Env, Fehlerbehandlung, Status-Links, Testliste).

Überblick​

ModusAblaufRolleStand 2026-10-09
B — Vor Ort per NFC und WischenKunde tippt NFC-Tag, grüner Live-Bildschirm, Personal wischt auf dem KundenhandyPilot-StandardUmgesetzt (PR #334, auf main; auf älteren Umgebungen liefern die Routen 404)
C — B plus Laden-PINgleicher Bildschirm: PIN-Feld, danach Wischenoptional je Shop (Stempelkarte)Umgesetzt (0.1.654): Schalter requireRedeemPin an der Stempelkarte, pin bei counter/confirm, redemptionMode in den Antworten. Dieselbe Laden-PIN wie beim Verschenken
Früherer Partner-Code-WegKunde fordert LR-…-Code, Partner-Token bestätigtkein ProduktwegMit PR #334 entfernt (keine Route, kein Token)

Das Ladenpersonal handelt nie mit eigenem Login.

Modus B — Vor Ort per NFC und Wischen​

Pfade wie in PR #334 implementiert:

  1. Karte ist voll (rewardsAvailable > 0). Der Kunde tippt den NFC-Tag der Kasse. Der Link enthält denselben Stempelpunkt-Code wie beim Stempeln; das Frontend unterscheidet über die Kartenlage und eine Auswahl („Prämie einlösen“ oder „Stempel sammeln“).
  2. POST /api/public/loyalty/redemptions/counter mit Bearer cardToken und { code } → { code, expiresAt, rewardTitle, shopName, serverTime }. Der Vorgang gilt 3 Minuten; erneuter Aufruf liefert den offenen Vorgang (Neuladen ist unkritisch).
  3. Das Frontend zeigt den grünen Live-Bildschirm (Prämie, Shop, Uhr aus serverTime, Animation, Restzeit).
  4. Das Personal wischt. POST /api/public/loyalty/redemptions/counter/confirm mit { redemptionCode } (im Modus C zusätzlich pin) verbraucht genau eine Prämie; zweites Bestätigen → CODE_USED, nach Ablauf → CODE_EXPIRED. Danach Wallet-Sync wie nach einem Stempel.

Die Prämie gehört zum Shop des Stempelpunkts. Ohne volle Karte für diesen Shop antwortet die API NO_REWARD.

Restrisiko: Wer die Tag-URL kopiert, kann außerhalb des Ladens starten und selbst wischen. Er löst nur eine Prämie ein, die er wirklich erstempelt hat. Auffälligkeiten zeigen die Kennzahlen (stats.redemptions). Wer mehr Schutz braucht, aktiviert Modus C für den Shop.

Noch nicht vorhanden (niedrige Priorität): GET /api/public/loyalty/redemptions/counter/{code} als Statusabruf. Bis dahin reicht der idempotente POST …/counter.

Modus C — Laden-PIN vor dem Wischen​

Gleicher Bildschirm wie B, ohne zusätzlichen Schritt oder zweiten Screen: Verlangt die Stempelkarte des Shops eine PIN, zeigt das Frontend ein PIN-Feld über dem Wisch-Regler; wischen ist erst nach Eingabe möglich.

Vertrag (additiv, umgesetzt):

  • Konfiguration je Stempelkarte (je Shop): requireRedeemPin (boolean, Standard false = Modus B). Pflege im Dashboard (Stempelkarten, Schalter „PIN beim Einlösen verlangen“), per POST …/loyalty/stamp-cards (Dashboard und AgencyOS) und MCP (cockpit_loyalty_stamp_card_upsert). Der Schalter braucht eine gesetzte Laden-PIN; die PIN ist dieselbe wie beim Verschenken (4–6 Ziffern).
  • Lesen für das Frontend: redemptionMode (counter oder counter_pin) je Eintrag in card.stampCards[] (GET /cards/me, Stempel-Antworten) und in der Antwort von POST …/redemptions/counter. Das Frontend zeigt das PIN-Feld genau dann, wenn redemptionMode === 'counter_pin'; keine Env-Variable und kein Raten nötig.
  • Bestätigen: POST …/redemptions/counter/confirm mit { redemptionCode, pin }. Im Modus B wird pin ignoriert. Im Modus C gilt:
FallAntwort
pin fehlt oder ist leer403 PIN_INVALID (zählt nicht als Fehlversuch)
pin falsch403 PIN_INVALID (zählt als Fehlversuch)
5 Fehlversuche423 PIN_LOCKED, details.lockedUntil (15 Minuten, gemeinsamer Zähler mit dem Verschenken)
Shop hat (nachträglich) keine PIN409 PIN_NOT_SET
PIN richtigwie Modus B; die Prämie wird verbraucht

Ein abgelaufener oder bereits eingelöster Vorgang (CODE_EXPIRED, CODE_USED) wird vor der PIN geprüft und verbraucht keinen Fehlversuch.

Ohne requireRedeemPin und ohne pin bleibt der Vertrag von B unverändert: Frontends dürfen pin weglassen.

Reihenfolge​

  1. Erledigt: PR #334 (Modus B, Verschenken) ist auf main.
  2. P0: Pilot CARRÉ Bad Cannstatt einrichten; Frontend durch SMG in v0 (siehe Integrationsvertrag).
  3. Erledigt: Modus C (pin bei counter/confirm, requireRedeemPin je Stempelkarte, redemptionMode im Public-Read).
  4. P3: Statusabruf GET …/counter/{code}.

So testen (Modus B, PR #334 ist gemergt)​

  1. Stempelkarte mit stampsRequired: 2 anlegen, Stempelpunkt anlegen, Karte erzeugen.
  2. Zweimal stempeln (Sperrfrist beachten oder stampCooldownMinutes auf 0 setzen).
  3. POST …/redemptions/counter mit dem Stempelpunkt-code → code (LR-…) und serverTime.
  4. POST …/redemptions/counter/confirm mit redemptionCode → status: 'redeemed'; erneut → CODE_USED.
  5. GET …/loyalty/stats zeigt eine Einlösung.

So testen (Modus C)​

  1. Stempelkarte mit Laden-PIN (staffPin: "4711") und requireRedeemPin: true anlegen (Dashboard: Stempelkarten, Schalter „PIN beim Einlösen verlangen"). Antwort enthält requireRedeemPin: true.
  2. Karte füllen, POST …/redemptions/counter: Antwort hat redemptionMode: "counter_pin".
  3. POST …/counter/confirm ohne pin → 403 PIN_INVALID; mit falscher PIN → 403 PIN_INVALID; mit 4711 → status: 'redeemed'.
  4. Fünf falsche PINs → 423 PIN_LOCKED mit details.lockedUntil; neue PIN am Stempelkarten-Formular hebt die Sperre auf.
  5. requireRedeemPin: true bei einer Karte ohne PIN → 400 INVALID_INPUT.
  6. PUT …/loyalty/program mit { "redemptionCodeTtlMinutes": 30 } → 400 INVALID_INPUT; mit { "visitorAppBaseUrl": "http://x.de" } → 400; mit https://…/loop/stempel → gespeichert.

Nutzungsstatistik: Seitenaufrufe werden anonymisiert erfasst. Im Umami-Dashboard nach diesem Pfad filtern: /developer-guide/loop-loyalty-api