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
| Wer | Nutzt |
|---|---|
| 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 / SMG | Dashboard-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.
| Methode | Pfad | Body | Antwort 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_KEYauf dem Dashboard). - Nach Stempel aktualisiert das Cockpit den Pass automatisch, wenn
autoSyncOnStamp=trueund 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
templateFieldsmit den Center-Daten. - Das Passcreator-Template muss diese dynamischen Felder definieren (Feldname = API-Schlüssel):
| Feld | Quelle | Pflicht |
|---|---|---|
centerName | ShoppingCenter.name (Fallback LOOP, wenn leer) | ja |
cardNumber | Kartennummer (auch Barcode-Wert) | ja |
pointsBalance | aktuelle Punkte/Stempel | ja |
storedValue | spiegelt pointsBalance (Passcreator-Standardfeld, Feld im Template aktivieren) | ja |
centerSlug | ShoppingCenter.slug — nur gesendet, wenn das Center einen Slug hat | optional |
recoveryUrl | Besucher-App Reentry /k/<token> (Back-Feld); siehe Session Reentry | optional |
- 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(ausShoppingCenter.baseColor) und optionalurlToLogo(HTTPS auslogoUrl/logo). Passcreator setzt das nur um, wenn am Master-Template*DifferentForEachPassaktiv ist — einmalig per Bootstrap--apply-pilot-branding. Demo-logoText/descriptionam Template werden dort ebenfalls bereinigt. - Sperrbildschirm-Text: Die Pass-
descriptionin 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) odercounter_pin(Modus C, PIN-Feld zeigen), siehe Modus C.cardNumberist kein Geheimnis: Kasse und Wallet-Barcode.codebeim 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)
- Kunde mit voller Karte tippt an den NFC-Tag der Kasse. v0 ruft
…/redemptions/countermit dem Tag-Code auf. - 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. - Das Personal wischt auf dem Kundenhandy „Eingelöst“. v0 ruft
…/redemptions/counter/confirmauf. Genau eine Prämie wird verbraucht, ein zweites Bestätigen liefertCODE_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):
- Kunde tippt an den NFC-Tag der Kasse.
- 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/giftauf.
Regeln (serverseitig):
- Grenzen aus dem Center-Programm:
manualGrantMaxPerAction(Standard 5) undmanualGrantMaxPerShopDay(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)
| Methode | Pfad | Rollen |
|---|---|---|
| GET, PUT | /api/centers/{centerId}/loyalty/program | SUPER_ADMIN, DEVELOPER, PLATFORM_ADMIN, CENTER_ADMIN, ORG_MARKETING_MANAGER, CENTER_MANAGER |
| GET, POST | /api/centers/{centerId}/loyalty/stamp-cards | wie oben (POST legt an oder aktualisiert, eine Karte pro Shop) |
| GET, POST | /api/centers/{centerId}/loyalty/stamp-points | wie 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-config | wie Programm (Passcreator-Template, Sync) |
| GET | /api/centers/{centerId}/loyalty/shops | wie 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
| Methode | Pfad | MCP-Tool |
|---|---|---|
| GET | /api/agencyos/v1/centers/{centerId}/loyalty/program | cockpit_loyalty_program_get |
| PATCH | /api/agencyos/v1/centers/{centerId}/loyalty/program | cockpit_loyalty_program_update |
| GET | /api/agencyos/v1/centers/{centerId}/loyalty/stamp-cards | cockpit_loyalty_stamp_cards_list |
| POST | /api/agencyos/v1/centers/{centerId}/loyalty/stamp-cards | cockpit_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-config | cockpit_loyalty_wallet_config_get |
| PATCH | /api/agencyos/v1/centers/{centerId}/loyalty/wallet-config | cockpit_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? }
code | HTTP | Bedeutung |
|---|---|---|
INVALID_INPUT | 400 | Pflichtfeld fehlt oder ungültig |
INVALID_CARD | 401 | Token fehlt oder Karte unbekannt |
PIN_INVALID | 403 | Laden-PIN falsch |
NOT_FOUND | 404 | Center, Shop, Stempelpunkt, Karte oder Vorgang unbekannt |
PROGRAM_INACTIVE | 409 | LOOP im Center nicht aktiv |
NO_REWARD | 409 | keine Prämie verfügbar |
CODE_USED | 409 | Einlöse-Vorgang schon bestätigt |
PIN_NOT_SET | 409 | für diesen Shop ist keine Laden-PIN hinterlegt |
CODE_EXPIRED | 410 | Einlöse-Vorgang abgelaufen (3 Minuten) |
LIMIT_REACHED | 422 | Grenze für verschenkte Stempel (pro Vorgang oder pro Shop und Tag) |
PIN_LOCKED | 423 | zu viele falsche PINs, details.lockedUntil |
COOLDOWN | 429 | Sperrfrist je Shop läuft, details.nextAllowedAt |
WALLET_DISABLED | 409 | Wallet im Center nicht aktiv |
WALLET_NOT_CONFIGURED | 409 | Passcreator-Template fehlt |
WALLET_NOT_LINKED | 404 | GET Pass ohne vorheriges POST |
WALLET_UNAVAILABLE | 502/503 | Passcreator-Key fehlt oder Provider-Fehler |
POINTS_REWARD_POINT | 409 | POST /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_POINTS | 409 | Punkte-Prämie: Guthaben reicht nicht (details.pointsBalance, pointsCost, missing) |
REENTRY_INVALID | 404 | Wiedereinstieg: 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:
| Spur | Weg | Zustand |
|---|---|---|
| 1 · Cookie | gleicher Browser, loop_card vorhanden | wie bisher, nichts ändert sich |
| 2 · Reentry-Link | https://<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):
| Methode | Pfad | Auth | Antwort |
|---|---|---|---|
| GET | /api/public/loyalty/cards/me/reentry | Bearer cardToken | { reentryToken } — beim ersten Aufruf erzeugen, danach stabil |
| POST | /api/public/loyalty/cards/reentry | keine | { cardToken, card } (200); unbekannt → 404 REENTRY_INVALID |
| POST | /api/public/loyalty/cards/me/reentry/rotate | Bearer | { 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 wiecardToken. Additive Migration: Spaltereentry_token_hashanloyalty_cardsoder 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/reentrypro 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:attributedValuemit<a href>und Roh-URL imvalue; Google:appLinkData.webAppLinkInfo). Origin =visitorAppBaseUrlohne 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>→ CockpitPOST /cards/reentry→ Cookie setzen → 302/loop?wiederhergestellt=ok; Token ungültig →…=invalid; Cockpit-Route fehlt noch (404 ohnecode) →…=unavailable.Referrer-Policy: no-referrer.GET /api/loop/cards/reentry→ CockpitGET /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:
- Besucher tippt den Stempelpunkt des Prämien-Shops an (z. B. Parkhaus-Kasse).
POST /redemptions/pointsmit dem Stempelpunkt-code→PR-…, gilt 3 Minuten; offene Vorgänge derselben Karte werden wiederverwendet. Reicht das Guthaben nicht:409 NOT_ENOUGH_POINTS. - Grüner Live-Bildschirm mit Prämie, Shop und Serveruhr; das Personal wischt.
POST /redemptions/points/confirmmitredemptionCodeziehtpointsCostPunkte genau einmal ab (Kartensperre, Ledger-Buchungreason = 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
- Programm aktivieren:
PUT /api/centers/{centerId}/loyalty/programmit{ "isActive": true }. - Stempelkarte anlegen:
POST …/loyalty/stamp-cardsmit{ "shopId": "…", "rewardTitle": "Gratis-Cappuccino", "stampsRequired": 3, "staffPin": "4711" }→hasStaffPin: true. - Stempelpunkt anlegen:
POST …/loyalty/stamp-pointsmit{ "shopId": "…" }→codemerken. - Karte anlegen:
POST /api/public/loyalty/cardsmit{ "centerId": "…" }→cardTokenmerken. - Stempeln:
POST /api/public/loyalty/stampsmit Bearer und{ "code": "…" }→stampCount: 1,pointsAwarded: 10. Sofort erneut →COOLDOWN(Standard-Sperrfrist 8 Minuten). - Verschenken:
POST /api/public/loyalty/stamps/giftmit{ "code": "…", "stamps": 2, "pin": "4711" }→rewardsEarned: 1,pointsAwarded: 0. Falsche PIN →PIN_INVALID; fünfmal falsch →PIN_LOCKED. - Einlösen:
POST /api/public/loyalty/redemptions/countermit dem Stempelpunkt-code→LR-…, dannPOST …/redemptions/counter/confirmmitredemptionCode. Zweites Confirm →CODE_USED. - Kennzahlen:
GET …/loyalty/statszeigt Stempel je Shop, davon verschenkt, und eine Einlösung.
Wallet (Staging, Passcreator):
PASSCREATOR_API_KEYauf dem Dashboard setzen; Health:GET /api/integrations/passcreator/health(Admin-Session, prüft Passcreator-ListingGET /api/pass-template— nicht/api/v2/pass-template, dort 404).- Master-Template optional:
node scripts/passcreator-bootstrap-loop-master-template.mjs(Dry-Run), mit--applyanlegen — siehe Passcreator Bootstrap. PATCH /api/agencyos/v1/centers/{centerId}/loyalty/wallet-configmit{ "isEnabled": true, "passcreatorTemplateId": "…" }.- Karte wie oben anlegen →
POST /api/public/loyalty/wallet/passmit Bearer →appleWalletUrl/androidWalletUrl. - Stempeln → Pass
storedValue/ Push (wennpushNotificationOnStamp=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):
PATCH …/loyalty/programmit{ "pointsRewardTitle": "1 Stunde gratis parken", "pointsRewardCost": 20, "pointsRewardShopId": "<Parkhaus-Shop>" }, für diesen Shop einen Stempelpunkt anlegen (keine Stempelkarte).- Zwei Stempel in einem anderen Shop sammeln (20 Punkte).
POST /stampsmit dem Parkhaus-Code →409 POINTS_REWARD_POINT,details.available: true. POST /redemptions/pointsmit dem Parkhaus-Code →PR-…;POST /redemptions/points/confirm→pointsSpent: 20,card.pointsBalance: 0; zweites Bestätigen →CODE_USED.GET …/statszeigtpointsRedemptions: 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(siehedb_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 setztAccess-Control-Allow-Originnur für*.cockpit-os.de(und lokal). Weil die Public-Loyalty-Routen einenAuthorization-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
| Modus | Ablauf | Rolle | Stand 2026-10-09 |
|---|---|---|---|
| B — Vor Ort per NFC und Wischen | Kunde tippt NFC-Tag, grüner Live-Bildschirm, Personal wischt auf dem Kundenhandy | Pilot-Standard | Umgesetzt (PR #334, auf main; auf älteren Umgebungen liefern die Routen 404) |
| C — B plus Laden-PIN | gleicher Bildschirm: PIN-Feld, danach Wischen | optional 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-Weg | Kunde fordert LR-…-Code, Partner-Token bestätigt | kein Produktweg | Mit 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:
- 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“). POST /api/public/loyalty/redemptions/countermit BearercardTokenund{ code }→{ code, expiresAt, rewardTitle, shopName, serverTime }. Der Vorgang gilt 3 Minuten; erneuter Aufruf liefert den offenen Vorgang (Neuladen ist unkritisch).- Das Frontend zeigt den grünen Live-Bildschirm (Prämie, Shop, Uhr aus
serverTime, Animation, Restzeit). - Das Personal wischt.
POST /api/public/loyalty/redemptions/counter/confirmmit{ redemptionCode }(im Modus C zusätzlichpin) 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, Standardfalse= Modus B). Pflege im Dashboard (Stempelkarten, Schalter „PIN beim Einlösen verlangen“), perPOST …/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(counterodercounter_pin) je Eintrag incard.stampCards[](GET /cards/me, Stempel-Antworten) und in der Antwort vonPOST …/redemptions/counter. Das Frontend zeigt das PIN-Feld genau dann, wennredemptionMode === 'counter_pin'; keine Env-Variable und kein Raten nötig. - Bestätigen:
POST …/redemptions/counter/confirmmit{ redemptionCode, pin }. Im Modus B wirdpinignoriert. Im Modus C gilt:
| Fall | Antwort |
|---|---|
pin fehlt oder ist leer | 403 PIN_INVALID (zählt nicht als Fehlversuch) |
pin falsch | 403 PIN_INVALID (zählt als Fehlversuch) |
| 5 Fehlversuche | 423 PIN_LOCKED, details.lockedUntil (15 Minuten, gemeinsamer Zähler mit dem Verschenken) |
| Shop hat (nachträglich) keine PIN | 409 PIN_NOT_SET |
| PIN richtig | wie 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
- Erledigt: PR #334 (Modus B, Verschenken) ist auf
main. - P0: Pilot CARRÉ Bad Cannstatt einrichten; Frontend durch SMG in v0 (siehe Integrationsvertrag).
- Erledigt: Modus C (
pinbeicounter/confirm,requireRedeemPinje Stempelkarte,redemptionModeim Public-Read). - P3: Statusabruf
GET …/counter/{code}.
So testen (Modus B, PR #334 ist gemergt)
- Stempelkarte mit
stampsRequired: 2anlegen, Stempelpunkt anlegen, Karte erzeugen. - Zweimal stempeln (Sperrfrist beachten oder
stampCooldownMinutesauf 0 setzen). POST …/redemptions/countermit dem Stempelpunkt-code→code(LR-…) undserverTime.POST …/redemptions/counter/confirmmitredemptionCode→status: 'redeemed'; erneut →CODE_USED.GET …/loyalty/statszeigt eine Einlösung.
So testen (Modus C)
- Stempelkarte mit Laden-PIN (
staffPin: "4711") undrequireRedeemPin: trueanlegen (Dashboard: Stempelkarten, Schalter „PIN beim Einlösen verlangen"). Antwort enthältrequireRedeemPin: true. - Karte füllen,
POST …/redemptions/counter: Antwort hatredemptionMode: "counter_pin". POST …/counter/confirmohnepin→403 PIN_INVALID; mit falscher PIN →403 PIN_INVALID; mit4711→status: 'redeemed'.- Fünf falsche PINs →
423 PIN_LOCKEDmitdetails.lockedUntil; neue PIN am Stempelkarten-Formular hebt die Sperre auf. requireRedeemPin: truebei einer Karte ohne PIN →400 INVALID_INPUT.PUT …/loyalty/programmit{ "redemptionCodeTtlMinutes": 30 }→400 INVALID_INPUT; mit{ "visitorAppBaseUrl": "http://x.de" }→400; mithttps://…/loop/stempel→ gespeichert.
Nutzungsstatistik: Seitenaufrufe werden anonymisiert erfasst. Im Umami-Dashboard nach diesem Pfad filtern: /en/developer-guide/loop-loyalty-api