Überblick
Bevor Kassenpersonal, Einlasskräfte oder POS-Terminals im Einzelhandel digitale Wallet-Pässe von Kunden validieren können, müssen Sie in Ihrem Arbeitsbereich einen Validierungsort (Validation Place) konfigurieren und eine Scanner-Konfiguration (ScannerConfiguration-Modell) im Dashboard unter /scanner und /scanner/configs verknüpfen. Passinstance verwaltet die Gerätekopplung, die Durchsetzung von Bediener-PINs, Schlüsselrotationen, Telemetrieberichte und die Synchronisation von Offline-Snapshots über Scanner Keys API (/api/v1/scanner-keys), Validation Config API (/api/v1/validation) und Scan Validation API (/api/v1/scans).

Voraussetzungen: Sie benötigen eine aktive, veröffentlichte Pass-Vorlage sowie Arbeitsbereich-Berechtigungen zum Verwalten von Validierungskonfigurationen (
validation:managebzw.scans:readfür die Schlüsselbereitstellung), bevor Sie Kopplungslinks generieren oder Rohschlüssel für Scanner ausstellen können.
Scanner-Konfigurationstypen & zentrale Enums
Passinstance unterscheidet über ScannerConfigurationType zwischen nativen Handheld-Scannern und öffentlichen, browserbasierten Checkpoint-Links:
Enum (ScannerConfigurationType) | Kanal | Authentifizierungsmechanismus | Typischer Einsatz |
|---|---|---|---|
SMART_SCAN_APP | Passinstance Scanner-App (iOS / Android) & integrierte POS-SDKs | Gekoppelter x-scanner-key (from-link oder for-config) | Einlass-Handhelds am Gate, Offline-Veranstaltungsorte, Einzelhandelskassen. |
VALIDATION_LINK | Webbrowser-Checkpoint (/api/v1/public/validation/:configId/validate) | Signierter Web-Validierungslink | Pop-up-Event-Desks oder Partnerstände ohne App-Installation. |
Schritt-für-Schritt-Einrichtung
-
1
Validierungsorte definieren: Erstellen Sie physische oder logische Checkpoints (z. B. Haupteingang, Kasse 1, VIP-Lounge), um Scan-Analysen zu segmentieren und einzuschränken, welche Pässe an welchem Standort eingelöst werden dürfen (
validValidationPlaces). -
2
Scanner-Konfiguration erstellen: Definieren Sie unter Scanner -> Scanner-Konfigurationen (
/scanner/configs) den Profilnamen,type(ScannerConfigurationType), zulässige Vorlagen (templateId/allowedTemplates),ScanMode,StoredValueOperation(NONE | ADD | SUBTRACT | SET),StoredValueAmountSource(FIXED | OPERATOR | MECHANIC), die Bediener-PIN (unlockPinHash) sowie ob Personal Profile im laufenden Betrieb wechseln darf (allowChangesViaLink: true). -
3
Gerät koppeln oder Schlüssel bereitstellen:
- Mobile App (SMART_SCAN_APP): Scannen Sie einen QR-Kopplungslink (ScannerAccessLink) oder geben Sie ein Zugriffstoken ein, um es über POST /api/v1/scanner-keys/from-link einzutauschen. - Authentifizierte App / POS-Terminal: Nach Benutzeranmeldung und Profilauswahl stellen Sie über POST /api/v1/scanner-keys/for-config direkt einen dedizierten Schlüssel aus.
-
4
Heartbeat & Offline-Synchronisation prüfen: Die Scanner-App prüft den Schlüsselstatus über
GET /api/v1/scanner-keys/verify, stellt fehlgeschlagene Offline-Übermittlungen bis zuMAX_RETRY_ATTEMPTS = 3mit clientseitig erzeugtenx-idempotency-key-Headern in die Warteschlange und speichert Pass-Snapshots überGET /api/v1/scans/offline-datasetzwischen.
Architektur & Lebenszyklus der Gerätekopplung
Endpunkte für den Scanner-Schlüssel-Lebenszyklus (Scanner Keys API)
Alle Vorgänge zur Bereitstellung von Geräteschlüsseln, Profilumschaltung, PIN-Prüfung und Rotation stehen unter /api/v1/scanner-keys zur Verfügung:
| Methode | Endpunkt | Auth / Guard | Beschreibung |
|---|---|---|---|
| POST | /api/v1/scanner-keys/from-link | Öffentlich (ScannerAccessLink, CSRF-ausgenommen) | Tauscht { token, pin? } gegen einen persistenten x-scanner-key (key, wird einmalig zurückgegeben). |
| POST | /api/v1/scanner-keys/for-config | Arbeitsbereich-JWT (scans:read) | Stellt einen neuen Scanner-Schlüssel für eine mandanteneigene { configId } aus. |
| GET | /api/v1/scanner-keys/configs | x-scanner-key | Listet aktive SMART_SCAN_APP-Konfigurationen auf, die an den Mandanten des aufrufenden Schlüssels gebunden sind. |
| POST | /api/v1/scanner-keys/switch | x-scanner-key | Wechselt den Schlüssel auf eine andere { configId, pin? }, sofern allowChangesViaLink: true gesetzt ist. |
| POST | /api/v1/scanner-keys/unlock-pin | x-scanner-key | Prüft { pin } gegen unlockPinHash mit automatischem Brute-Force-Sperrschutz. |
| GET | /api/v1/scanner-keys/verify | x-scanner-key | Validiert den Schlüsselstatus, erfasst Gerätetelemetrie-Header und liefert den Hinweis shouldRotate. |
| POST | /api/v1/scanner-keys/revoke | x-scanner-key | Widerruft den aufrufenden Scanner-Schlüssel sofort und blockiert alle weiteren Scan-Übermittlungen. |
| POST | /api/v1/scanner-keys/:id/rotate | Arbeitsbereich-JWT (scans:read) | Rotiert einen bestehenden Scanner-Schlüssel anhand seiner ID atomar und gibt einmalig einen neuen geheimen Rohschlüssel zurück. |
1. Kopplung über Zugriffslink (POST /api/v1/scanner-keys/from-link)
Wenn Mitarbeitende in der Passinstance Scanner-App einen Einrichtungs-QR-Code scannen, tauscht das Gerät das Einrichtungs-Token (und optional die Bediener-PIN, falls unlockPinHash konfiguriert ist) gegen einen persistenten x-scanner-key ein:
{
"token": "sal_9f82b1c4e7a043d19b2e",
"pin": "4829"
}
Antwort (201 Created):
{
"scannerKey": {
"id": "skey_01hxyz8912ab",
"createdAt": "2026-11-16T09:00:00.000Z",
"expiresAt": "2027-02-15T00:00:00.000Z"
},
"validationConfig": {
"id": "scfg_main_entrance_01",
"configurationId": "MAIN_ENTRANCE",
"name": "Main Entrance Gate",
"scanMode": "CHECK_IN",
"type": "SMART_SCAN_APP",
"place": "Main Entrance",
"isActive": true,
"allowChangesViaLink": true,
"templateId": "tmpl_event_vip",
"allowedTemplateIds": ["tmpl_event_vip"],
"version": 3
},
"key": "sk_live_7d9a2f4b8c1e6039a5d2e8f1"
}
Wichtig: Der Wert
keywird nur ein einziges Mal bei der Erstellung oder Rotation zurückgegeben und in der Datenbank als SHA-256-Hash (hashKey) gespeichert. Bewahren Siekeysicher im Geräte-Keychain auf; falls er verloren geht, rufen SiePOST /api/v1/scanner-keys/:id/rotateauf.
2. Heartbeat, Telemetrie & Rotationshinweis (GET /api/v1/scanner-keys/verify)
Scanner-Clients rufen periodisch GET /api/v1/scanner-keys/verify mit x-scanner-key sowie betrieblichen Telemetrie-Headern auf, damit Administratoren den Zustand der Geräteflotte in Echtzeit überwachen können:
| Telemetrie-Header | Format / Beispiel | Zweck |
|---|---|---|
x-scanner-app-version | 2.4.1 (build 108) | Erfasst die App-Build-Version über alle eingesetzten Handhelds hinweg. |
x-scanner-device-id | ios-idfv-8841-992a | Eindeutige Hardware-Kennung für das Bestandsverzeichnis der Geräteflotte. |
x-scanner-battery-level | 0.78 (0–1 oder 0–100) | Warnt das Betriebspersonal, wenn Einlass-Scanner unter 15 % Akkustand fallen. |
x-scanner-queue-backlog | 12 | Anzahl der lokal zwischengespeicherten Offline-Scans, die auf den Upload warten. |
Antwort (200 OK):
{
"valid": true,
"scannerKeyId": "skey_01hxyz8912ab",
"scannerConfigurationId": "scfg_main_entrance_01",
"validationConfigId": "scfg_main_entrance_01",
"expiresAt": "2026-11-25T12:00:00.000Z",
"daysUntilExpiration": 9,
"shouldRotate": true,
"message": "Scanner key is approaching expiration. Please rotate soon."
}
Wenn daysUntilExpiration < 15 gilt, wird shouldRotate als true zurückgegeben und fordert das Gerät oder die Administration auf, die Zugangsdaten über POST /api/v1/scanner-keys/:id/rotate zu rotieren.
3. Profilwechsel im laufenden Betrieb (POST /api/v1/scanner-keys/switch)
Wenn eine Konfiguration allowChangesViaLink: true besitzt, kann das Personal ein einzelnes Handheld-Gerät ohne erneute Kopplung zwischen verschiedenen SMART_SCAN_APP-Profilen umschalten (z. B. vom Einlass-Check-in zur VIP-Merchandise-Einlösung):
{
"configId": "scfg_vip_merch_02",
"pin": "9012"
}
Erfordert die Zielkonfiguration eine Bediener-PIN, prüft der Server pin gegen unlockPinHash, bevor der Schlüssel umgebunden wird. Bedienkräfte können ihre PIN außerdem eigenständig über POST /api/v1/scanner-keys/unlock-pin verifizieren.
Offline-Datensatz-Synchronisation (GET /api/v1/scans/offline-dataset)
Für Veranstaltungsorte mit instabiler Mobilfunk- oder WLAN-Verbindung synchronisieren mobile Scanner einen kompakten, schlüsselgebundenen Pass-Snapshot (offline scan dataset) über GET /api/v1/scans/offline-dataset.
Query-Parameter
-
cursor(optionaler String): Paginierungs-Cursor aus der vorherigen Seite (nextCursor). -
limit(optionale Zahl): Maximale Anzahl von Datensätzen pro Seite. -
snapshotAt(optionaler ISO-8601-Zeitstempel): Inkrementeller Delta-Sync-Zeitstempel, um nur Pässe abzurufen, die seit dem letzten Snapshot erstellt, aktualisiert oder entwertet wurden.
Beispielanfrage & Snapshot-Pass-Element (IOfflineDatasetPassResponse)
/api/v1/scans/offline-dataset?limit=500&snapshotAt=2026-11-16T08:00:00.000Z
{
"config": {
"id": "scfg_main_entrance_01",
"customerTimezone": "Europe/Berlin",
"scanMode": "CHECK_IN",
"validValidationPlaces": ["Main Entrance"]
},
"snapshotAt": "2026-11-16T09:00:00.000Z",
"nextCursor": "pass_01hxyz9940",
"hasMore": true,
"items": [
{
"id": "pass_01hxyz9939",
"templateId": "tmpl_event_vip",
"serialNumber": "PI-VIP-00419",
"externalId": "crm_attendee_9012",
"barcodeValue": "PI-VIP-00419",
"status": "ACTIVE",
"voided": false,
"expirationDate": "2026-12-31T23:59:59.000Z",
"storedValue": "50.00",
"mechanicType": "NONE",
"lastSuccessfulScanAt": "2026-11-15T19:04:00.000Z",
"validationPlaces": ["Main Entrance"]
}
]
}
Weitere Informationen zu Hardwarekompatibilität und Validierungsabläufen finden Sie auf der Scanner-Produktseite sowie unter Scan-Modi & Validierungsregeln.
