Skip to content
Helpcentrum-gids · Passen scannenOnboardingfase 4
5 min leestijdGecontroleerd 2026-11-16

Scanner instellen & configureren

Maak validatieplekken en scannerprofielen aan (Mobiele app of Webscanner) en installeer de Passinstance Scanner-app.

In deze gids

Interactieve UI-weergaven

Openen in onboardinggids (6 fasen)

Bekijk de exacte dashboardpanelen, knoppen en ingezoomde toelichtingen bij deze gids.

Ingezoomde UI-focus1 / 2
Belangrijke UI-onderdelen

Wizard 'Scannerconfiguratie aanmaken' (Ingesneden)

Stel een configuratienaam, beschrijving, het type Mobile App en de weergaveduur van het succesbericht in om een veilig scannerprofiel aan te maken.

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

Bediening voor scannervalidatielocaties en configuratie
Bediening voor scannervalidatielocaties en configuratie

Vereisten: U hebt een actief gepubliceerd passjabloon en werkruimtemachtigingen nodig voor het beheren van validatieconfiguraties (validation:manage, of scans:read voor 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)KanaalAuthenticatiemechanismeTypische inzet
SMART_SCAN_APPPassinstance Scanner-app (iOS / Android) & geïntegreerde POS SDK'sGekoppelde x-scanner-key (from-link of for-config)Handhelds bij ingangen, locaties zonder internet, winkelkassa's.
VALIDATION_LINKWebbrowser-controlepunt (/api/v1/public/validation/:configId/validate)Ondertekende webvalidatielinkPop-up evenementbalies of partnerstands zonder app-installatie.

Stapsgewijze configuratie

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

  1. 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 tot MAX_RETRY_ATTEMPTS = 3 met door de client gegenereerde x-idempotency-key-headers en cacht pas-snapshots via GET /api/v1/scans/offline-dataset.

Architectuur & levenscyclus van apparaatkoppeling

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
KOPPELING VAN SCANNERAPPARATEN & TELEMETRIESYNCHRONISATIE
DEELNEMENDE SYSTEEMACTOREN
P1 Scannerapparaat / App
P2 Scanner Keys API
P3 Scan Validation API
STAP 1 VERZOEK / ACTIE POST/scanner-keys/
›
from-link {token, pin?}
STAP 2 ANTWOORD 201 Created
›
{ scannerKey,
›
alidationConfig,
›
key: "sk_live_..." }
STAP 3 VERZOEK / ACTIE GET/scanner-keys/verify
›
Headers: x-scanner-key,
›
x-scanner-battery-level,
›
x-scanner-queue-backlog
STAP 4 ANTWOORD 200 OK { shouldRotate }
STAP 5 VERZOEK / ACTIE GET/scans/offline-dataset ?cursor=...&limit=500
STAP 6 ANTWOORD 200 OK { items, nextCursor, snapshotAt }

Levenscyclus-endpoints voor scannersleutels (Scanner Keys API)

Alle bewerkingen voor sleuteluitgifte aan apparaten, profielwisseling, pincodeverificatie en rotatie zijn beschikbaar onder /api/v1/scanner-keys:

MethodeEndpointAuthenticatie / GuardBeschrijving
POST/api/v1/scanner-keys/from-linkOpenbaar (ScannerAccessLink, CSRF-vrijgesteld)Wisselt { token, pin? } om voor een blijvende x-scanner-key (key, eenmalig geretourneerd).
POST/api/v1/scanner-keys/for-configWerkruimte-JWT (scans:read)Geeft een nieuwe scannersleutel uit voor een { configId } van de tenant.
GET/api/v1/scanner-keys/configsx-scanner-keyGeeft een overzicht van actieve SMART_SCAN_APP-configuraties gekoppeld aan de tenant van de aanroepende sleutel.
POST/api/v1/scanner-keys/switchx-scanner-keySchakelt de sleutel over naar een andere { configId, pin? } wanneer allowChangesViaLink: true.
POST/api/v1/scanner-keys/unlock-pinx-scanner-keyVerifieert { pin } tegen unlockPinHash met automatische brute-force-blokkering.
GET/api/v1/scanner-keys/verifyx-scanner-keyValideert de sleutelstatus, registreert apparaatspecifieke telemetrieheaders en retourneert het rotatieadvies shouldRotate.
POST/api/v1/scanner-keys/revokex-scanner-keyTrekt de aanroepende scannersleutel direct in en blokkeert alle volgende scanzendingen.
POST/api/v1/scanner-keys/:id/rotateWerkruimte-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:

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

Antwoord (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"
}

Belangrijk: De key-waarde wordt slechts één keer geretourneerd bij het aanmaken of roteren en als SHA-256-hash (hashKey) opgeslagen in de database. Bewaar key veilig in de sleutelhanger (keychain) van het apparaat; als deze verloren gaat, roept u POST /api/v1/scanner-keys/:id/rotate aan.

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:

TelemetrieheaderFormaat / voorbeeldDoel
x-scanner-app-version2.4.1 (build 108)Houdt de app-buildversie bij over alle ingezette handhelds.
x-scanner-device-idios-idfv-8841-992aUnieke hardware-identifier voor de apparaatinventarisatie.
x-scanner-battery-level0.78 (0–1 of 0–100)Waarschuwt operationeel personeel wanneer ingangsscanners onder de 15% acculading komen.
x-scanner-queue-backlog12Aantal offline scans dat lokaal in de wachtrij staat te wachten op uploadsynchronisatie.

Antwoord (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."
}

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:

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

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"]
    }
  ]
}

Bekijk hardwarecompatibiliteit en validatieworkflows op de Scanner-productpagina en Scanmodi & validatieregels.

Gerelateerde product- en ontwikkelaarsdocs

Klaar om uw eerste kaartprogramma te lanceren?

Maak uw workspace aan, configureer uw sjabloon en test een echte kaart in Apple Wallet en Google Wallet voordat u opschaalt.