Skip to content
Hilfecenter-Anleitung · Pass-ScanningOnboarding-Phase 4
3 Min. LesezeitGeprüft 2026-11-16

Scan-Modi & Validierungsregeln

Konfigurieren Sie Einmaleinlösung, Check-in/out, Einmal-pro-Tag-Regeln, Meldungstexte und Offline-Cache-Verhalten.

In dieser Anleitung

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

Vergrößerter UI-Fokus
Wichtige UI-Elemente

Nachricht nach dem Scan & Scanner-Konfigurationen (Zoom)

Passen Sie die Bestätigungsmeldung für Mitarbeiter mit Platzhaltern wie {holderName} an und verwalten Sie aktive Scanner-Zugangslinks.

Überblick

Jeder an POST /api/v1/scans übermittelte Scan wird gegen die aktive ScannerConfiguration (ermittelt über den gebundenen x-scanner-key oder scannerConfigurationId / validationConfigId in request payload) sowie eine deterministische 14-Regel-Validation Rules Engine-Pipeline ausgewertet. Gemeinsam legen diese Einstellungen fest, ob ein Pass eine Teilnahme erfasst, bei einmaliger Nutzung entwertet wird, den Check-in-Status am Veranstaltungsort umschaltet, Wertguthaben verändert oder kryptografische Anti-Replay-Nonces erzwingt.

Modal zum Erstellen einer Scanner-Konfiguration
Modal zum Erstellen einer Scanner-Konfiguration

Wichtig: Validierungsregeln werden auf dem Server atomar ausgeführt. Wenn ein Scan den Pass-Status verändert (etwa VOIDED_AFTER_SCAN oder StoredValueOperation.SUBTRACT), werden konkurrierende Mehrfachanfragen mithilfe von Idempotenzsperren (x-idempotency-key) serialisiert, um Race Conditions über mehrere Kassen hinweg zu verhindern.

Konfigurations- & Ergebnis-Enumerationen

Bei der Konfiguration von Validierungsprofilen unter Scanner -> Scanner-Konfigurationen (/scanner/configs) oder über /api/v1/validation/configs steuern fünf Passinstance database-Enumerationen das Terminalverhalten und die persistierten Scan-Ergebnisse:

1. ScanMode-Enum

ScanMode-WertVerhalten & StatusübergangTypischer Anwendungsfall
SAVE_ATTENDANCEErfasst ein gültiges Scan-Ereignis und führt verknüpfte Treue-/Stempelmechaniken aus, ohne den Pass zu entwerten.Mehrfach nutzbare Treuekarten, Fitnessstudio-Mitgliedschaften, Dauerkarten.
VOIDED_AFTER_SCANÜberführt den Pass-Status beim ersten gültigen Scan atomar in VOIDED; nachfolgende Scans liefern ALREADY_VOIDED.Einmal-Coupons, Aktionsgutscheine, Einmaltickets.
INVALIDATE_AFTER_SCANMarkiert den Pass nach der Einlösung als ungültig und blockiert die weitere Akzeptanz unter der Validierungskonfiguration.Einmalig einlösbare Pässe und eingeschränkte Gästegutscheine.
CHECK_INSetzt den Anwesenheitsstatus des Passes auf eingecheckt; lehnt erneute Check-ins ab, falls der Gast bereits eingecheckt ist.Einlass zu Konferenz-Sessions, zugangsbeschränkte Eingänge.
CHECK_OUTÜberführt den Anwesenheitsstatus des Passes von eingecheckt zu ausgecheckt.Ausgangserfassung am Veranstaltungsort, Kapazitätssteuerung.
CHECK_IN_CHECK_OUT_TOGGLEWechselt bei aufeinanderfolgenden Scans automatisch zwischen CHECK_IN und CHECK_OUT.Co-Working-Spaces, mehrtägige Festival-Armbänder und -Pässe.

2. Enumerationen für Wertguthaben, NFC & Scan-Ergebnisse

Enum-TypErlaubte WerteZweck
StoredValueOperationNONE, ADD, SUBTRACT, SETLegt fest, ob ein Scan das Guthaben unverändert lässt, auflädt (ADD), einen Kaufbetrag abbucht (SUBTRACT) oder überschreibt (SET).
StoredValueAmountSourceFIXED, OPERATOR, MECHANICBestimmt, ob der Transaktionsbetrag aus einem festen Konfigurationswert (FIXED), einer Kassenpersonal-Eingabe (OPERATOR) oder der Vorlagen-Mechanik (MECHANIC) stammt.
NfcReaderModeAUTO, KEYBOARD_WEDGE, APPLE_WALLET, GOOGLE_SMART_TAPKonfiguriert die Protokollaushandlung kontaktloser Lesegeräte für Apple-VAS- und Google-Smart-Tap-Terminals.
scan actionINCREMENT, DECREMENT, VALIDATE, DEBIT, CREDIT, NOOPAktion, die bei jeder Pass-Nutzung oder Scan-Ledger-Transaktion protokolliert wird (request payload erlaubt zusätzlich SET).
scan statusSUCCESS, FAILED, PENDING, INVALID, EXPIRED, ALREADY_USED, ALREADY_VOIDED, CHECK_IN_SUCCESS, CHECK_OUT_SUCCESS, ALREADY_CHECKED_IN, ALREADY_CHECKED_OUTGranularer persistierter Status im Scan-Audit-Datensatz (einschließlich expliziter Check-in-/Check-out-Übergänge).

Die 14-stufige Validation Rules Engine-Pipeline

Sobald POST /api/v1/scans ein Payload empfängt, führt Validation Rules Engine 14 priorisierte Validierungsregeln in vier Phasen aus (Core -> Mechanics -> Security -> Fallback):

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
14-REGEL-BUSINESS-VALIDATION-ENGINE-PIPELINE
STUFE 01 POST/api/v1/scans (request payload + x-scanner-key)
STUFE 02 Phase 1: Core-Regeln
1
PassStatusRulePrüfen, ob Pass ACTIVE ist (nicht VOIDED / SUSPENDED)
2
ExpirationRulePrüfen, ob now() < expirationDate
3
TimeWindowRulePrüfen, ob Scan innerhalb erlaubter Zeiten liegt
4
GeofencingRulePrüfen, ob Scanner-GPS {lat, lng} im Radius liegt
STUFE 03 Phase 2: Mechanik-Regeln
5
OncePerDayRuleAblehnen, falls Pass im Zeitfenster bereits gescannt
6
StampCardAddRuleStempelzähler erhöhen & Meilenstein prüfen
7
StampCardDeductRuleStempel für Prämieneinlösung abziehen
8
PrepaidCardRuleADD / SUBTRACT / SET auf Wertguthaben ausführen
9
LoyaltyProgramRulepointsDelta berechnen & anwenden
10
TierEvaluationRulePass-Stufe bei Überschreiten einer Schwelle anheben
STUFE 04 Phase 3: Sicherheits-Regeln
11
RateLimitRuleSchnelles Scan-Flooding auf einem Pass verhindern
12
AntiReplayRuleKryptografische scan nonce von /scans/prepare prüfen
13
DeviceValidationRuleScanner-Schlüssel & Terminalbindung prüfen
STUFE 05 Phase 4: Fallback
14
DefaultAcceptanceRuleAusgabe decision: "SUCCESS", status: "ACCEPTED"

Jede während eines Scans geprüfte Regel hängt ihr Ausführungsergebnis an das Array ruleTrace in request payload an und liefert so einen vollständigen Diagnosepfad.

Anti-Replay-Nonces (POST /api/v1/scans/prepare)

Um hochwertige Tickets und Gutscheine vor statischen Barcode-Screenshots zu schützen, können Terminals vor der endgültigen Ausführung eine kurzlebige kryptografische scan nonce anfordern:

Anfrage

POST /api/v1/scans/prepare
Header
x-scanner-key sk_live_7d9a2f4b8c1e6039a5d2e8f1
JSON
{
  "scannedBarcodeValue": "PI-TKT-992014",
  "scannerConfigurationId": "scfg_main_entrance_01"
}

Antwort (201 Created)

JSON
{
  "success": true,
  "data": {
    "nonce": "snonce_8841a9c2f01e4b72",
    "expiresAt": "2026-11-15T22:35:30.000Z"
  }
}

Die Übergabe von "nonce": "snonce_8841a9c2f01e4b72" im anschließenden POST /api/v1/scans-Payload erfüllt AntiReplayRule und entwertet die Nonce sofort, sodass sie nicht erneut verwendet werden kann.

Schema zur Scan-Ausführung (POST /api/v1/scans)

request payload-Payload

JSON
{
  "scannedBarcodeValue": "PI-LOY-449102",
  "scannerConfigurationId": "scfg_register_01",
  "nonce": "snonce_8841a9c2f01e4b72",
  "timestamp": "2026-11-15T22:35:10.000Z",
  "location": {
    "lat": 52.520008,
    "lng": 13.404954
  },
  "channel": "NFC",
  "protocol": "VAS",
  "validationData": {
    "amount": 18.50,
    "place": "Flagship Berlin Store"
  },
  "operatorId": "emp_cashier_07",
  "terminalId": "pos_term_berlin_02",
  "configurationVersion": 4
}

request payload-Payload & Entscheidungscodes

Die Engine liefert einen von sieben kanonischen decision-Werten zurück: SUCCESS, FAILED, ALREADY_USED, ALREADY_VOIDED, EXPIRED, INVALID oder PENDING (sofern über scanForm eine Bedienereingabe erforderlich ist).

JSON
{
  "decision": "SUCCESS",
  "status": "ACCEPTED",
  "reasonCode": "RULE_ACCEPTED",
  "ruleTrace": [
    { "rule": "PassStatusRule", "passed": true },
    { "rule": "ExpirationRule", "passed": true },
    { "rule": "LoyaltyProgramRule", "passed": true, "pointsDelta": 185 },
    { "rule": "TierEvaluationRule", "passed": true, "upgradedTo": "GOLD" }
  ],
  "passSnapshot": {
    "id": "pass_loy_449102",
    "templateId": "tmpl_loyalty_01",
    "serialNumber": "PI-LOY-449102",
    "externalId": "crm_cust_44910",
    "status": "ACTIVE",
    "tier": "GOLD",
    "barcodeValue": "PI-LOY-449102",
    "storedValue": "42.00"
  },
  "remainingBalance": "42.00",
  "effects": {
    "oldBalance": "42.00",
    "newBalance": "42.00",
    "pointsDelta": 185,
    "transactionAmount": 18.50,
    "currency": "EUR"
  },
  "display": {
    "title": "Scan Accepted — Gold Tier!",
    "subtitle": "+185 Points awarded",
    "color": "success"
  },
  "configurationVersion": 4,
  "configurationStale": false
}

Informationen zur Prüfung abgeschlossener Scans und zum Export von CSV-Protokollen finden Sie unter Scan-Verlauf & Ergebnisse.

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.