Ü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.

Wichtig: Validierungsregeln werden auf dem Server atomar ausgeführt. Wenn ein Scan den Pass-Status verändert (etwa
VOIDED_AFTER_SCANoderStoredValueOperation.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-Wert | Verhalten & Statusübergang | Typischer Anwendungsfall |
|---|---|---|
SAVE_ATTENDANCE | Erfasst 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_SCAN | Markiert 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_IN | Setzt 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_TOGGLE | Wechselt 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-Typ | Erlaubte Werte | Zweck |
|---|---|---|
StoredValueOperation | NONE, ADD, SUBTRACT, SET | Legt fest, ob ein Scan das Guthaben unverändert lässt, auflädt (ADD), einen Kaufbetrag abbucht (SUBTRACT) oder überschreibt (SET). |
StoredValueAmountSource | FIXED, OPERATOR, MECHANIC | Bestimmt, ob der Transaktionsbetrag aus einem festen Konfigurationswert (FIXED), einer Kassenpersonal-Eingabe (OPERATOR) oder der Vorlagen-Mechanik (MECHANIC) stammt. |
NfcReaderMode | AUTO, KEYBOARD_WEDGE, APPLE_WALLET, GOOGLE_SMART_TAP | Konfiguriert die Protokollaushandlung kontaktloser Lesegeräte für Apple-VAS- und Google-Smart-Tap-Terminals. |
| scan action | INCREMENT, DECREMENT, VALIDATE, DEBIT, CREDIT, NOOP | Aktion, die bei jeder Pass-Nutzung oder Scan-Ledger-Transaktion protokolliert wird (request payload erlaubt zusätzlich SET). |
| scan status | SUCCESS, FAILED, PENDING, INVALID, EXPIRED, ALREADY_USED, ALREADY_VOIDED, CHECK_IN_SUCCESS, CHECK_OUT_SUCCESS, ALREADY_CHECKED_IN, ALREADY_CHECKED_OUT | Granularer 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):
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
/api/v1/scans/prepare
{
"scannedBarcodeValue": "PI-TKT-992014",
"scannerConfigurationId": "scfg_main_entrance_01"
}
Antwort (201 Created)
{
"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
{
"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).
{
"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.
