Skip to main content

LOOP — v0-Integrationsvertrag (SMG)

Diese Seite ist der von SMG festgelegte Vertrag für die Besucher-Oberfläche von LOOP. SMG setzt die Oberfläche in v0 selbst um und legt Routen und UX fest; die Punkte hier sind Entscheidungen, keine Vorschläge. Das v0-Team (und jeder andere, der am System arbeitet) kann sich darauf verlassen und braucht keine Rückfrage, welche URL oder welcher API-Weg gilt.

DokumentRolle
Diese SeiteIntegrationsvertrag: was gilt, wer was pflegt, wie getestet wird
LOOP Loyalty — API-VertragEndpunkte, Felder, Regeln, Rate-Limits, Admin-/AgencyOS-API
LOOP — Session ReentryRecovery-Token, /k/<token>, BFF-Restore, Wallet-Link
v0-Prompt — LOOP Signage und CompanionCopy-Paste-Bauprompt für v0 (verweist auf diesen Vertrag)
LOOP im DashboardEinrichtung durch Center-Betrieb, Prüfliste „Bereit für Besucher“
LOOP — Screen-MapSieben Companion-Screens (Entwurf), alle Zustände und Fehler, offene Lücken, was nur im v0-Repo bleibt

Was​

LOOP ist die Bindungsstufe von NOW!: pseudonyme Karte pro Besucher und Center, Stempelkarten je Shop, centerweite Punkte. Die Besucher-Oberfläche ist ein einziges v0-Projekt mit zwei Bereichen:

  • Companion/NOW! (Handy des Besuchers): Karte, Stempeln, Einlösen.
  • Signage (Display im Center): passive Werbeschleife mit QR zum Companion.

Cockpit liefert Regeln, Daten, Stempelpunkt-Codes und Public-API. Cockpit liefert keine Besucher-Oberfläche.

Warum​

Ohne festen Vertrag entstehen zwei Projekte mit unterschiedlichen URLs, unterschiedlicher Auslegung von Cooldown und Einlösen und am Ende gedruckte QR-Codes, die nicht mehr passen. Die NFC-/QR-URLs liegen an Kassen und lassen sich nicht ohne Aufwand ändern, deshalb sind sie hier fest.

Wer ist betroffen​

WerBetroffen durch
Besucher-App (v0-Integration)Routen, BFF, Cookie, Einlöse-Screen bauen und pflegen
Center-BetriebStempelpunkte anlegen, QR/NFC mit der festen URL beschreiben
LadenpersonalBedient nur das Kundenhandy (Wischen, optional PIN), kein Gerät, kein Login
Cockpit-BackendRegeln, Public-API, Fehlercodes stabil halten

Wo​

1. Produktentscheidungen (fest)​

  1. Eine App. Signage und Companion/NOW! liegen im selben v0-Projekt und teilen Design-Tokens und Komponenten.
  2. Keine weiteren Apps. Keine Partner-App, keine Händler-App, keine eigene Signage-App für LOOP (apps/digital-signage ist für LOOP kein Ziel). Das Ladenpersonal hat keinen Login.
  3. Einlösen ohne Shop-Login: Modus B (Pilot-Standard) und optional Modus C (PIN auf demselben Screen), siehe Abschnitt 5.
  4. Shop-Status ohne Login über signierte Links (Abschnitt 7): Philosophie „Link statt Konto“.
  5. Cockpit ist Wahrheit. Prämie, Stempelanzahl, Sperrfrist, Aktiv/Inaktiv, Branding und Texte kommen aus API-Antworten, nichts davon hardcodieren.

2. Kanonische URLs (feste Pfade, SMG-definiert)​

RouteBereichZweck
/loopCompanionKarte, Onboarding, Shop-Liste mit Fortschritt, Hilfe
/loop/stempel?code=<Code>&src=nfc|qrCompanionZiel von NFC-Tag und QR-Code am Stempelpunkt. Stempeln, bei voller Karte Wahl „Einlösen“
/loop/einloesenCompanionGrüner Live-Screen (Modus B), mit PIN-Feld bei Modus C
/k/<recoveryToken>CompanionSession-Reentry (Wallet-Link, QR). v0-BFF → Cockpit POST …/session/restore, Cookie loop_card, Redirect /loop
/loop/hilfeCompanionFAQ
/loop/schenken?code=<Code>CompanionStempel verschenken (Laden-PIN), hinter Flag, nicht verlinkt
/signage/loop?display=<touchscreenId>SignageWerbeschleife, display wird in alle internen Links mitgeführt

Regeln:

  • Die Stempelpunkt-URL für QR und NFC ist immer https://<v0-Domain>/loop/stempel?code=<Code> (NFC-Tags zusätzlich &src=nfc, QR &src=qr oder ohne src). Das Dashboard hängt nur ?code= an die Basis-URL an; die Basis (https://<v0-Domain>/loop/stempel) trägt das Team einmal je Center im Dashboard ein (Bonus & Loyalität, Programm oder Stempelpunkte). Sie liegt im Programm (visitorAppBaseUrl), gilt für das ganze Team und jedes Gerät und ist per AgencyOS/MCP setzbar.
  • Der code ist vertraulich (je Kasse): nicht loggen, nicht in Analytics, nach Verarbeitung per router.replace aus der Adresszeile entfernen.
  • Diese Pfade nur ändern, wenn gleichzeitig alle gedruckten QR-Codes und NFC-Tags neu beschrieben werden. Neue Routen dürfen ergänzt werden; die vier Pfade /loop, /loop/stempel, /loop/einloesen, /signage/loop bleiben stabil.

3. BFF-Muster (/api/loop/* → Public-Loyalty-API)​

Der Browser spricht nur mit der eigenen Domain. Route Handlers im v0-Projekt rufen die Public-API serverseitig auf.

BFF-Route (v0)Cockpit-Route (/api/public/loyalty/…)Status Cockpit
POST /api/loop/cardsPOST /cards { centerId }auf main
POST /api/loop/session/restorePOST /session/restore { recoveryToken }Cockpit umgesetzt — BFF setzt Cookie, Client sieht nur card
GET /api/loop/cards/meGET /cards/meauf main
POST /api/loop/stampsPOST /stamps { code, source? }auf main
POST /api/loop/redemptions/startPOST /redemptions/counter { code }Umgesetzt (PR #334, auf main)
POST /api/loop/redemptions/confirmPOST /redemptions/counter/confirm { redemptionCode, pin? }Umgesetzt: redemptionCode (PR #334), pin im Modus C (0.1.654)
POST /api/loop/stamps/giftPOST /stamps/gift { code, stamps, pin, reason? }Umgesetzt (PR #334, auf main)
GET|POST /api/loop/wallet/…GET /wallet/capabilities, GET|POST /wallet/passauf main (Phase 2 im UI)
POST /api/loop/redemptions/points/startPOST /redemptions/points { code }Umgesetzt (0.1.682): Punkte-Prämie, z. B. „1 Stunde gratis parken“
POST /api/loop/redemptions/points/confirmPOST /redemptions/points/confirm { redemptionCode }Umgesetzt (0.1.682)
GET /api/loop/cards/reentryGET /cards/me/reentry → { url }Frontend fertig, Cockpit offen (Wiedereinstieg, siehe API-Vertrag)
GET /k/<reentryToken> (keine BFF-Route, Seite)POST /cards/reentry { reentryToken } → Cookie + 302 /loopFrontend fertig, Cockpit offen

Gründe:

  • CORS: Das Cockpit erlaubt Browser-Aufrufe mit Authorization nur für *.cockpit-os.de (und lokal).
  • Das Karten-Token (cardToken) darf nicht im Client-JavaScript liegen.
  • Der BFF reicht HTTP-Status, code, details und Retry-After 1:1 durch und validiert Eingaben (Code 1–64 Zeichen [A-Za-z0-9_-], stamps 1–50, pin 4–6 Ziffern, JSON only, Origin-Check bei Schreibrouten).
  • Nie aufrufen aus dem Besucher-Frontend: /api/agencyos/*, /api/partner/*, GET …/website-config, Dashboard-Routen /api/centers/{id}/loyalty/* (alle brauchen Auth).

Öffentliche Lese-Quellen für Branding (serverseitig, mit Cache):

  • GET /api/centers/by-slug/carre-bad-cannstatt
  • GET /api/centers/{centerId}/public-visitor-surface → branding, design, legal, apiHints
  • Signage optional: GET /api/centers/{centerId}/signage-surface (Notfall- und Wartungsmodus)

Pilot: CARRÉ Bad Cannstatt

FeldWert
Slugcarre-bad-cannstatt
centerIde6deaa57-8a5f-4ff6-8790-c538cf068d16
Cockpit-APIhttps://dashboard.cockpit-os.de

Cookie loop_card (nur vom BFF gesetzt und gelesen):

EigenschaftWert
InhaltcardToken aus POST /cards; Wiedereinstieg in anderen Browsern über /k/<reentryToken> (Spur 2, siehe API-Vertrag „Wiedereinstieg“)
FlagshttpOnly, Secure, SameSite=Lax, Path=/
Lebensdauer400 Tage
Rückgabe an Clientnie; der BFF liefert nur card
Bei INVALID_CARDCookie löschen, neue Karte anbieten

cardNumber (z. B. LP-7K3M-9QX2) ist kein Geheimnis und darf angezeigt werden (Kasse, Barcode).

Env im v0-Projekt (keine Secrets):

VariableZweckDefault Pilot
COCKPIT_API_BASE (nur Server)Cockpit-Basis-URLhttps://dashboard.cockpit-os.de
NEXT_PUBLIC_LOOP_CENTER_IDCentere6deaa57-8a5f-4ff6-8790-c538cf068d16
NEXT_PUBLIC_LOOP_CENTER_SLUGSlug für Brandingcarre-bad-cannstatt
NEXT_PUBLIC_LOOP_REDEMPTION_MODEOptionaler Notfall-Override. Normalfall: Das Cockpit liefert redemptionMode je Stempelkarte, die Env wird nicht gebrauchtnicht setzen
NEXT_PUBLIC_LOOP_GIFT_ENABLEDVerschenken-Flow sichtbarfalse
LOOP_STATUS_LINK_BASE (geplant, nur Server)Basis für Status-Links, Abschnitt 7—

Auf dem Cockpit-Server (nicht in v0): PASSCREATOR_API_KEY (Wallet). Details: API-Vertrag, Betrieb.

5. Einlösen: Modus B und C ohne Shop-Login​

Prinzip: Der NFC-Tag an der Kasse (Stempelpunkt) belegt den Aufenthalt im Laden. Das Personal handelt am Kundenhandy, ohne Login und ohne Gerät.

Modus B (Pilot-Standard):

  1. Kunde mit voller Karte tippt den NFC-Tag/QR (/loop/stempel?code=…). Bei rewardsAvailable > 0 bietet die Seite „Prämie einlösen“ vor „Stempel sammeln“ an.
  2. BFF POST /api/loop/redemptions/start → Cockpit …/redemptions/counter → { code, expiresAt, rewardTitle, shopName, serverTime, redemptionMode }. Vorgang gilt 3 Minuten, idempotent bei Neuladen.
  3. /loop/einloesen: grüner Vollbild-Screen mit laufender Uhr aus serverTime (Offset-Berechnung), dauerhafter Animation und Restzeit. Das ist der Screenshot-Schutz.
  4. Personal wischt (Swipe-to-confirm; Tastatur- und Long-Press-Alternative) → BFF …/confirm mit { redemptionCode }. Genau eine Prämie, danach Erfolgs-Screen.

Modus C (optional je Shop, derselbe Screen):

  • Fordert der Shop eine PIN, erscheint das PIN-Feld auf /loop/einloesen über dem Wisch-Regler. Wischen ist erst nach vollständiger PIN möglich. Kein zweiter Screen, kein zusätzlicher Klick.
  • Request: POST …/redemptions/counter/confirm mit { redemptionCode, pin? }; pin nur, wenn der Shop sie fordert.
  • PIN-Fehlerzustände wie beim Verschenken: PIN_INVALID, PIN_NOT_SET, PIN_LOCKED.
  • Das Frontend schaltet C über redemptionMode je Stempelkarte: counter_pin = PIN-Feld zeigen, counter = nur wischen. Der Wert steht in card.stampCards[] (GET /cards/me) und in der Antwort von POST …/redemptions/counter. Das Center-Betrieb-Team stellt C je Stempelkarte im Dashboard ein (Schalter „PIN beim Einlösen verlangen“).
  • Es gilt dieselbe Laden-PIN wie beim Verschenken. Fehlt pin oder ist sie falsch, antwortet die API PIN_INVALID (fehlendes pin zählt nicht als Fehlversuch); nach 5 Fehlversuchen PIN_LOCKED für 15 Minuten.

Stand, 2026-10-09:

BausteinStand
POST …/redemptions/counter und …/counter/confirm (Body { redemptionCode })Umgesetzt (PR #334, auf main). Antworten die Routen auf einer Umgebung noch mit 404, ist der Deploy noch nicht durch; das Frontend zeigt dann „Einlösen ist gerade noch nicht verfügbar“
Verschenken …/stamps/gift mit Laden-PINUmgesetzt (PR #334, auf main)
Modus C: pin im Body von …/counter/confirm, redemptionMode (counter | counter_pin) je StempelkarteUmgesetzt (0.1.654, additiv, Standard counter). Voraussetzung auf der Ziel-Umgebung: Migration 20261009220000_loop_redeem_pin_SAFE.sql
Statusabruf GET …/redemptions/counter/{code}Geplant (niedrige Priorität)
Partner-App und Partner-RoutenKein Produktweg. Mit PR #334 entfernt, es gibt keine Partner-Route für LOOP

Frontend-Vorgabe: Das PIN-Feld erscheint genau dann, wenn redemptionMode === 'counter_pin'. Ältere Umgebungen ohne die Migration liefern kein redemptionMode; das Frontend behandelt ein fehlendes Feld wie counter.

6. Wer pflegt was​

ThemaBesucher-App / Frontend (v0)Cockpit (Dashboard, API, MCP)
Routen, Layout, Animation, Texte der UIja—
BFF-Routen, Cookie, Validierung, Zod-Schemasja—
Grüner Live-Screen, Swipe, PIN-Feldja—
Signage-Folien, Notfall-OverlayjaNotfall-/Wartungsflags in signage-surface
Programm aktiv/inaktiv, Punkte pro Stempel, Sperrfrist—ja (Dashboard oder MCP)
Stempelkarten je Shop, Prämie, Stempelanzahl, Laden-PIN—ja
Stempelpunkte und Codes, Deaktivieren, QR-Code—ja (Basis-URL = v0-Pfad)
Branding, Logo, Farben, Rechtstexteliest nurja (public-visitor-surface)
Wallet-Template und Passcreatorzeigt Links an (Phase 2)ja (PASSCREATOR_API_KEY)
Regeln, Fehlercodes, Rate-Limitshält sich daranja

Das v0-Frontend editiert nie Regeln, Stempelanzahlen oder Prämien im Code. Fehlt ein API-Feld, zeigt das Frontend einen neutralen Zustand und erfindet nichts.

7. Shop- und Center-Status ohne Login (Philosophie und Architektur)​

Status: Architekturnotiz, nicht implementiert. Routen und Endpunkte unten sind Platzhalter.

Philosophie: Ladenpersonal und Center-Betrieb sollen den LOOP-Stand ihres Shops ansehen können, ohne Konto, ohne Passwort und ohne Partner-App. Zugriff entsteht über einen Link, den nur berechtigte Personen kennen. Das ist dieselbe Linie wie bei Kundenkarten: kein Login, Besitz des Links bzw. Tokens ist die Berechtigung.

Muster:

EigenschaftFestlegung
URL (Platzhalter)/loop/status/<token> im v0-Projekt, GET /api/loop/status/<token> (BFF)
Cockpit-Quelle (Platzhalter)GET /api/public/loyalty/status?token=… oder Header, nie mit Karten-Token vermischt
TokenSigniert (HMAC) oder zufällig mit Hash in der DB; enthält Scope (shopId oder centerId), Aussteller, Ablauf
Berechtigungnur lesen, keine Schreibaktionen, keine PIN-Eingabe, kein Einlösen
InhaltAggregierte Kennzahlen: Stempel heute und letzte 7/30 Tage, Einlösungen, offene Vorgänge zählen; keine Einzelkarten, keine cardNumber
AusgabeCockpit erzeugt den Link (Dashboard oder MCP), zeigt ihn einmalig; Widerruf und Neuausstellung (Rotation) möglich
SicherheitRate-Limit je IP und Token, noindex, Referrer-Policy: no-referrer, kurze Caches, Token nie in Logs/Analytics, Ablauf (z. B. 90 Tage) und Sofort-Widerruf
GranularitätEin Link pro Shop; Center-Link für Management getrennt

Warum so: Ein Konto je Shop erzeugt Passwort-Vergessen, Mitarbeiterwechsel und Support. Ein widerrufbarer Lese-Link ist für Aggregatdaten ausreichend und passt zur Regel „Händler sehen keine Einzelkarten“.

Offen vor Umsetzung: Token-Format (HMAC vs. Zufall + Hash), Speicherort (neue Tabelle, additiv, _SAFE-Migration), Dashboard-Ausstellung, MCP-Hints und Tool-Export (siehe Regel zur MCP-Parität). Bis dahin keine Status-Links bauen, die Daten ohne Cockpit-seitige Signatur ausliefern.

8. Fehlercodes​

Antwort: { success: false, error, code, details? }. Das Frontend mappt code auf eigene deutsche Texte und zeigt error nie ungefiltert an.

codeHTTPBedeutungUI-Reaktion
INVALID_INPUT400Pflichtfeld fehlt oder ungültig„Code ungültig, Tag erneut antippen“
INVALID_CARD401Token fehlt oder Karte unbekanntCookie löschen, neue Karte anbieten
PIN_INVALID403Laden-PIN falsch oder (Modus C) nicht mitgesendetFeld leeren, Hinweis
NOT_FOUND404Center, Shop, Stempelpunkt, Karte oder Vorgang unbekannt„Stempelpunkt nicht aktiv“; 404 auf Einlöse-Routen = noch nicht verfügbar
PROGRAM_INACTIVE409LOOP im Center nicht aktivSeite „LOOP derzeit nicht aktiv“, keine Karte anlegen
NO_REWARD409keine Prämie verfügbar„Keine Prämie bereit“, Button „Stattdessen stempeln“
CODE_USED409Einlöse-Vorgang schon bestätigt„Bereits eingelöst“, Karte neu laden
PIN_NOT_SET409für den Shop ist keine Laden-PIN hinterlegtHinweis ans Personal/Center
WALLET_DISABLED409Wallet im Center nicht aktivWallet-Button ausblenden
WALLET_NOT_CONFIGURED409Passcreator-Template fehltWallet-Button ausblenden
WALLET_NOT_LINKED404GET Pass ohne vorheriges POSTPass anlegen anbieten
CODE_EXPIRED410Einlöse-Vorgang abgelaufen (3 Minuten)„Erneut starten“ (Tag erneut antippen)
LIMIT_REACHED422Grenze für verschenkte StempelHinweis
PIN_LOCKED423zu viele falsche PINs, details.lockedUntil„PIN bis hh:mm gesperrt“
COOLDOWN429Sperrfrist je Shop, details.nextAllowedAtCountdown mm:ss, kein Fehler-Rot
(kein Code)429Rate-Limit, Header Retry-After„Zu viele Versuche, in n Sekunden erneut“
WALLET_UNAVAILABLE502/503Passcreator-Key fehlt oder Provider-FehlerWallet ausblenden, Hinweis
POINTS_REWARD_POINT409Stempelpunkt des Prämien-Shops angetipptStatt Stempel: „Punkte einlösen“ anbieten (details.available), sonst fehlende Punkte zeigen
NOT_ENOUGH_POINTS409Guthaben reicht nicht für die Punkte-Prämie„Noch {missing} Punkte“
REENTRY_INVALID404Wiedereinstiegs-Token unbekannt oder rotiert„Link ungültig“, Link aus dem Wallet-Pass nutzen oder neue Karte
(Netzwerk)502/503Cockpit nicht erreichbar„Verbindung gestört“, Erneut-versuchen-Button

COOLDOWN und Rate-Limit sind beide HTTP 429 und müssen getrennt dargestellt werden. Rate-Limits pro IP: Karte anlegen 20/h, Karte lesen 120/min, Stempeln 60/15 min, Einlösen 30/15 min, Verschenken 20/15 min, Wallet 30/h. Kein Polling von /cards/me; nur beim Öffnen, nach Aktionen und über „Aktualisieren“.

So testen​

Voraussetzung: Programm aktiv, Stempelkarte mit stampsRequired: 2, Stempelpunkt angelegt (Dashboard, Bereich Bonus und Loyalität). Einlöse-Schritte brauchen die Routen aus PR #334 (auf main) auf der Ziel-API.

  1. Karte: /loop aufrufen, „Karte anlegen“. Cookie loop_card ist httpOnly; kein cardToken in Antwort-JSON, localStorage oder URL.
  2. Stempeln: https://<v0-Domain>/loop/stempel?code=<Code>&src=nfc öffnen. Stempel 1 von 2, Adresszeile ohne code.
  3. Cooldown: gleiche URL sofort erneut. Countdown (COOLDOWN), kein Rot, nach Ablauf aktiver Button.
  4. Rate-Limit: getrennte Darstellung bei 429 ohne COOLDOWN (nur lokal provozierbar).
  5. Karte voll: zweiter Stempel. Abzeichen „Prämie bereit“, Auswahl „Einlösen / Stempel sammeln“ am Tag.
  6. Einlösen B: Tag antippen, Einlösen wählen. Grüner Screen: Uhr läuft sekundengenau, Animation läuft, Restzeit zählt. Wischen → genau ein Confirm, Erfolgs-Screen. Zweiter Confirm → CODE_USED.
  7. Ablauf: 3 Minuten warten, wischen → CODE_EXPIRED, „Erneut starten“ funktioniert.
  8. Ohne die Routen aus #334 (ältere Umgebung): Einlöse-Routen liefern 404 → freundlicher Hinweis, Karte bleibt nutzbar.
  9. Inaktiv: Programm im Dashboard deaktivieren → PROGRAM_INACTIVE, keine Karte wird angelegt.
  10. Signage: /signage/loop?display=<id> auf 1920x1080 und 1080x1920; keine Karten- oder Stempel-Requests im Netzwerk-Tab, keine Cookies mit Karten-Token.
  11. Sicherheit: Im Netzwerk-Tab gibt es keine Requests an dashboard.cockpit-os.de; Logs enthalten keine Codes, Tokens oder PINs.
  12. Modus C: Im Dashboard an der Stempelkarte „PIN beim Einlösen verlangen“ einschalten. redemptionMode ist counter_pin, PIN-Feld über dem Regler, Wischen erst nach vollständiger PIN. Falsche PIN → PIN_INVALID, fünfmal → PIN_LOCKED. Ausschalten: Feld verschwindet, Wischen genügt.

Betrieb​

  • v0-Projekt: Env wie in Abschnitt 4, keine Secrets, .env.example mitführen.
  • Stempelpunkt-QR/NFC: Adresse der LOOP-Anwendung im Dashboard (Programm oder Stempelpunkte) auf https://<v0-Domain>/loop/stempel setzen; bei Domain-Wechsel Adresse ändern und gedruckte Codes neu erzeugen. Die Prüfliste in der Übersicht zeigt, ob die Adresse fehlt.
  • Migrationen vor dem Deploy: 20261009210000_loop_visitor_app_base_url_SAFE.sql, 20261009220000_loop_redeem_pin_SAFE.sql (beide additiv).
  • Cockpit: keine neuen Env-Variablen für dieses Dokument. Rate-Limits und Wallet-Betrieb siehe LOOP Loyalty — API-Vertrag.
  • Reihenfolge: Pilot einrichten (PR #334 ist gemergt, Modus C ist umgesetzt), Frontend freischalten. Status-Links sind eine eigene Lieferung mit Dashboard-Reiter, Speicher, Public-Read und MCP-Hints (siehe Cockpit steuert Frontends).

Nutzungsstatistik: Seitenaufrufe werden anonymisiert erfasst. Im Umami-Dashboard nach diesem Pfad filtern: /en/developer-guide/loop-v0-integration-contract