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

Scanner-Einrichtung & Konfiguration

Legen Sie Validation Places und Scanner-Konfigurationen (Mobile App oder Web Scanner) an und installieren Sie die Scanner-App.

In dieser Anleitung

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

Vergrößerter UI-Fokus1 / 2
Wichtige UI-Elemente

Assistent „Scanner-Konfiguration erstellen“ (Zoom)

Legen Sie Konfigurationsname, Beschreibung, den Typ Mobile App und die Anzeigedauer der Erfolgsmeldung fest, um ein sicheres Scanner-Profil zu erstellen.

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

Validierungsorte und Konfigurationsoptionen im Scanner
Validierungsorte und Konfigurationsoptionen im Scanner

Voraussetzungen: Sie benötigen eine aktive, veröffentlichte Pass-Vorlage sowie Arbeitsbereich-Berechtigungen zum Verwalten von Validierungskonfigurationen (validation:manage bzw. scans:read fü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)KanalAuthentifizierungsmechanismusTypischer Einsatz
SMART_SCAN_APPPassinstance Scanner-App (iOS / Android) & integrierte POS-SDKsGekoppelter x-scanner-key (from-link oder for-config)Einlass-Handhelds am Gate, Offline-Veranstaltungsorte, Einzelhandelskassen.
VALIDATION_LINKWebbrowser-Checkpoint (/api/v1/public/validation/:configId/validate)Signierter Web-ValidierungslinkPop-up-Event-Desks oder Partnerstände ohne App-Installation.

Schritt-für-Schritt-Einrichtung

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

  1. 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 zu MAX_RETRY_ATTEMPTS = 3 mit clientseitig erzeugten x-idempotency-key-Headern in die Warteschlange und speichert Pass-Snapshots über GET /api/v1/scans/offline-dataset zwischen.

Architektur & Lebenszyklus der Gerätekopplung

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
SCANNER-GERÄTEKOPPLUNG & TELEMETRIE-SYNC
BETEILIGTE SYSTEMKOMPONENTEN
P1 Scanner-Gerät / App
P2 Scanner Keys API
P3 Scan Validation API
SCHRITT 1 ANFRAGE / AKTION POST/scanner-keys/
›
from-link {token, pin?}
SCHRITT 2 ANTWORT 201 Created
›
{ scannerKey,
›
alidationConfig,
›
key: "sk_live_..." }
SCHRITT 3 ANFRAGE / AKTION GET/scanner-keys/verify
›
Headers: x-scanner-key,
›
x-scanner-battery-level,
›
x-scanner-queue-backlog
SCHRITT 4 ANTWORT 200 OK { shouldRotate }
SCHRITT 5 ANFRAGE / AKTION GET/scans/offline-dataset ?cursor=...&limit=500
SCHRITT 6 ANTWORT 200 OK { items, nextCursor, snapshotAt }

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:

MethodeEndpunktAuth / GuardBeschreibung
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-configArbeitsbereich-JWT (scans:read)Stellt einen neuen Scanner-Schlüssel für eine mandanteneigene { configId } aus.
GET/api/v1/scanner-keys/configsx-scanner-keyListet aktive SMART_SCAN_APP-Konfigurationen auf, die an den Mandanten des aufrufenden Schlüssels gebunden sind.
POST/api/v1/scanner-keys/switchx-scanner-keyWechselt den Schlüssel auf eine andere { configId, pin? }, sofern allowChangesViaLink: true gesetzt ist.
POST/api/v1/scanner-keys/unlock-pinx-scanner-keyPrüft { pin } gegen unlockPinHash mit automatischem Brute-Force-Sperrschutz.
GET/api/v1/scanner-keys/verifyx-scanner-keyValidiert den Schlüsselstatus, erfasst Gerätetelemetrie-Header und liefert den Hinweis shouldRotate.
POST/api/v1/scanner-keys/revokex-scanner-keyWiderruft den aufrufenden Scanner-Schlüssel sofort und blockiert alle weiteren Scan-Übermittlungen.
POST/api/v1/scanner-keys/:id/rotateArbeitsbereich-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:

JSON
{
  "token": "sal_9f82b1c4e7a043d19b2e",
  "pin": "4829"
}

Antwort (201 Created):

JSON
{
  "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 key wird nur ein einziges Mal bei der Erstellung oder Rotation zurückgegeben und in der Datenbank als SHA-256-Hash (hashKey) gespeichert. Bewahren Sie key sicher im Geräte-Keychain auf; falls er verloren geht, rufen Sie POST /api/v1/scanner-keys/:id/rotate auf.

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-HeaderFormat / BeispielZweck
x-scanner-app-version2.4.1 (build 108)Erfasst die App-Build-Version über alle eingesetzten Handhelds hinweg.
x-scanner-device-idios-idfv-8841-992aEindeutige Hardware-Kennung für das Bestandsverzeichnis der Geräteflotte.
x-scanner-battery-level0.78 (0–1 oder 0–100)Warnt das Betriebspersonal, wenn Einlass-Scanner unter 15 % Akkustand fallen.
x-scanner-queue-backlog12Anzahl der lokal zwischengespeicherten Offline-Scans, die auf den Upload warten.

Antwort (200 OK):

JSON
{
  "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):

JSON
{
  "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)

GET /api/v1/scans/offline-dataset?limit=500&snapshotAt=2026-11-16T08:00:00.000Z
Header
x-scanner-key sk_live_7d9a2f4b8c1e6039a5d2e8f1
JSON
{
  "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.

Weiterführende Produkt- & Entwicklerdoku

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.