Overzicht
Voordat kassiers, poortmedewerkers of kassaterminals in de winkel wallet-passen van klanten kunnen valideren, moet u een Validation Place (validatielocatie) configureren en een Scanner Configuration (ScannerConfiguration-model) koppelen in uw werkruimte (/scanner en /scanner/configs in het Dashboard). Passinstance beheert apparaatkoppeling, afdwinging van operator-pincode, sleutelrotatie, telemetrierapportage en offline snapshot-synchronisatie via Scanner Keys API (/api/v1/scanner-keys), Validation Config API (/api/v1/validation) en Scan Validation API (/api/v1/scans).

Vereisten: U hebt een actief gepubliceerd passjabloon en werkruimtemachtigingen nodig voor het beheren van validatieconfiguraties (
validation:manage, ofscans:readvoor sleutelinrichting) voordat u koppelingslinks genereert of ruwe scannersleutels uitgeeft.
Typen scannerconfiguraties & kern-enums
Passinstance scheidt native handheld-scannen van openbare browsergebaseerde controlepuntlinks met behulp van ScannerConfigurationType:
Enum (ScannerConfigurationType) | Kanaal | Authenticatiemechanisme | Typische inzet |
|---|---|---|---|
SMART_SCAN_APP | Passinstance Scanner-app (iOS / Android) & geïntegreerde POS SDK's | Gekoppelde x-scanner-key (from-link of for-config) | Handhelds bij ingangen, locaties zonder internet, winkelkassa's. |
VALIDATION_LINK | Webbrowser-controlepunt (/api/v1/public/validation/:configId/validate) | Ondertekende webvalidatielink | Pop-up evenementbalies of partnerstands zonder app-installatie. |
Stapsgewijze configuratie
-
1
Definieer validatielocaties (Validation Places): maak fysieke of logische controlepunten aan (bijv. Main Entrance, Register 1, VIP Lounge) om scananalyses te segmenteren en te beperken welke passen op elke locatie mogen worden ingewisseld (
validValidationPlaces). -
2
Maak een scannerconfiguratie aan: stel onder Scanner -> Scanner Configurations (
/scanner/configs) de profielnaam,type(ScannerConfigurationType), toegestane sjablonen (templateId/allowedTemplates),ScanMode,StoredValueOperation(NONE | ADD | SUBTRACT | SET),StoredValueAmountSource(FIXED | OPERATOR | MECHANIC), operator-pincode (unlockPinHash) en of medewerkers ter plekke van profiel kunnen wisselen (allowChangesViaLink: true) in. -
3
Koppel het apparaat of richt een sleutel in:
- Mobiele app (SMART_SCAN_APP): scan een QR-koppelingslink (ScannerAccessLink) of voer een toegangstoken in om dit om te wisselen via POST /api/v1/scanner-keys/from-link. - Geauthenticeerde app / POS-terminal: geef na gebruikerslogin + profielselectie rechtstreeks een eigen sleutel uit via POST /api/v1/scanner-keys/for-config.
-
4
Verifieer heartbeat & offline synchronisatie: de scannerapp verifieert de status van de sleutel via
GET /api/v1/scanner-keys/verify, plaatst mislukte offline inzendingen in een wachtrij totMAX_RETRY_ATTEMPTS = 3met door de client gegenereerdex-idempotency-key-headers en cacht pas-snapshots viaGET /api/v1/scans/offline-dataset.
Architectuur & levenscyclus van apparaatkoppeling
Levenscyclus-endpoints voor scannersleutels (Scanner Keys API)
Alle bewerkingen voor sleuteluitgifte aan apparaten, profielwisseling, pincodeverificatie en rotatie zijn beschikbaar onder /api/v1/scanner-keys:
| Methode | Endpoint | Authenticatie / Guard | Beschrijving |
|---|---|---|---|
| POST | /api/v1/scanner-keys/from-link | Openbaar (ScannerAccessLink, CSRF-vrijgesteld) | Wisselt { token, pin? } om voor een blijvende x-scanner-key (key, eenmalig geretourneerd). |
| POST | /api/v1/scanner-keys/for-config | Werkruimte-JWT (scans:read) | Geeft een nieuwe scannersleutel uit voor een { configId } van de tenant. |
| GET | /api/v1/scanner-keys/configs | x-scanner-key | Geeft een overzicht van actieve SMART_SCAN_APP-configuraties gekoppeld aan de tenant van de aanroepende sleutel. |
| POST | /api/v1/scanner-keys/switch | x-scanner-key | Schakelt de sleutel over naar een andere { configId, pin? } wanneer allowChangesViaLink: true. |
| POST | /api/v1/scanner-keys/unlock-pin | x-scanner-key | Verifieert { pin } tegen unlockPinHash met automatische brute-force-blokkering. |
| GET | /api/v1/scanner-keys/verify | x-scanner-key | Valideert de sleutelstatus, registreert apparaatspecifieke telemetrieheaders en retourneert het rotatieadvies shouldRotate. |
| POST | /api/v1/scanner-keys/revoke | x-scanner-key | Trekt de aanroepende scannersleutel direct in en blokkeert alle volgende scanzendingen. |
| POST | /api/v1/scanner-keys/:id/rotate | Werkruimte-JWT (scans:read) | Roteert atomair een bestaande scannersleutel op ID en retourneert eenmalig een nieuwe ruwe geheime sleutel. |
1. Koppelen via toegangslink (POST /api/v1/scanner-keys/from-link)
Wanneer medewerkers een configuratie-QR-code scannen in de Passinstance Scanner-app, wisselt het apparaat het configuratietoken (en een optionele operator-pincode als unlockPinHash is geconfigureerd) om voor een blijvende x-scanner-key:
{
"token": "sal_9f82b1c4e7a043d19b2e",
"pin": "4829"
}
Antwoord (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"
}
Belangrijk: De
key-waarde wordt slechts één keer geretourneerd bij het aanmaken of roteren en als SHA-256-hash (hashKey) opgeslagen in de database. Bewaarkeyveilig in de sleutelhanger (keychain) van het apparaat; als deze verloren gaat, roept uPOST /api/v1/scanner-keys/:id/rotateaan.
2. Heartbeat, telemetrie & rotatieadvies (GET /api/v1/scanner-keys/verify)
Scannerclients roepen periodiek GET /api/v1/scanner-keys/verify aan met x-scanner-key en operationele telemetrieheaders, zodat beheerders de status van hun apparatenpark in realtime kunnen volgen:
| Telemetrieheader | Formaat / voorbeeld | Doel |
|---|---|---|
x-scanner-app-version | 2.4.1 (build 108) | Houdt de app-buildversie bij over alle ingezette handhelds. |
x-scanner-device-id | ios-idfv-8841-992a | Unieke hardware-identifier voor de apparaatinventarisatie. |
x-scanner-battery-level | 0.78 (0–1 of 0–100) | Waarschuwt operationeel personeel wanneer ingangsscanners onder de 15% acculading komen. |
x-scanner-queue-backlog | 12 | Aantal offline scans dat lokaal in de wachtrij staat te wachten op uploadsynchronisatie. |
Antwoord (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."
}
Wanneer daysUntilExpiration < 15, wordt shouldRotate geëvalueerd naar true, wat het apparaat of de beheerder vraagt om de referentie te roteren via POST /api/v1/scanner-keys/:id/rotate.
3. Ter plekke wisselen van profiel (POST /api/v1/scanner-keys/switch)
Als een configuratie allowChangesViaLink: true heeft, kunnen medewerkers één handheldscanner omschakelen tussen verschillende SMART_SCAN_APP-profielen (bijvoorbeeld van Door Check-In naar VIP Merchandise Redemption) zonder opnieuw te koppelen:
{
"configId": "scfg_vip_merch_02",
"pin": "9012"
}
Als de doelconfiguratie een operator-pincode vereist, valideert de server pin tegen unlockPinHash voordat de sleutel opnieuw wordt gekoppeld. Operators kunnen hun pincode ook los valideren via POST /api/v1/scanner-keys/unlock-pin.
Offline datasetsynchronisatie (GET /api/v1/scans/offline-dataset)
Voor locaties met wisselende mobiele of wifi-verbinding synchroniseren mobiele scanners een compacte, aan de sleutel gebonden passnapshot (offline scan dataset) via GET /api/v1/scans/offline-dataset.
Queryparameters
-
cursor(optionele string): paginatiecursor geretourneerd door de vorige pagina (nextCursor). -
limit(optioneel aantal): maximaal aantal records per pagina. -
snapshotAt(optioneel ISO 8601-tijdstempel): incrementeel tijdstempel voor deltasynchronisatie om alleen passen op te halen die sinds de vorige snapshot zijn aangemaakt, bijgewerkt of ongeldig verklaard.
Voorbeeldverzoek & item uit pas-snapshot (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"]
}
]
}
Bekijk hardwarecompatibiliteit en validatieworkflows op de Scanner-productpagina en Scanmodi & validatieregels.
