Skip to content
Guide du centre d'aide · Scan de passesPhase d'intégration 4
6 min de lectureVérifié 2026-11-16

Installation & configuration du scanner

Définissez vos lieux de validation, créez des configurations Scanner (App mobile ou Web) et équipez vos équipes.

Dans ce guide

Visites interactives de l'interface

Ouvrir dans le guide en 6 phases

Inspectez les écrans exacts du tableau de bord et les zooms annotés liés à ce guide.

Focus interface zoomé1 / 2
Éléments clés de l'interface

Assistant de création de configuration Scanner (Zoom)

Définissez le nom de la configuration, la description, le type Mobile App et la durée du message de succès pour générer un profil de scan sécurisé.

Aperçu

Avant que vos caissiers, agents d'accueil ou terminaux de point de vente puissent valider les cartes Wallet des clients, vous devez configurer un Lieu de validation (Validation Place) et associer une Configuration Scanner (modèle ScannerConfiguration) au sein de votre espace de travail (/scanner et /scanner/configs dans le tableau de bord). Passinstance gère l'appairage des terminaux, le code PIN opérateur, la rotation des clés, la remontée de télémétrie et la synchronisation hors ligne via Scanner Keys API (/api/v1/scanner-keys), Validation Config API (/api/v1/validation) et Scan Validation API (/api/v1/scans).

Lieux de validation et réglages de configuration du scanner
Lieux de validation et réglages de configuration du scanner

Prérequis : Vous devez disposer d'un modèle de passe publié actif ainsi que des permissions d'espace pour gérer les configurations de validation (validation:manage, ou scans:read pour provisionner les clés) avant de générer des liens d'appairage ou d'émettre des clés scanner brutes.

Types de configuration Scanner & énumérations principales

Passinstance sépare le scan natif sur terminal mobile des liens publics de contrôle sur navigateur grâce à ScannerConfigurationType :

Énumération (ScannerConfigurationType)CanalMécanisme d'authDéploiement type
SMART_SCAN_APPApplication Passinstance Scanner (iOS / Android) & SDK caisse intégrésClé appairée x-scanner-key (from-link ou for-config)Contrôle d'entrée mobile, sites hors ligne, caisses enregistreuses en boutique.
VALIDATION_LINKPoint de contrôle navigateur web (/api/v1/public/validation/:configId/validate)Lien web de validation signéStands éphémères ou guichets partenaires sans installation d'application.

Configuration étape par étape

  1. 1
    Définir les lieux de validation : Créez des points de contrôle physiques ou logiques (par exemple Main Entrance, Register 1, VIP Lounge) pour segmenter vos analyses de scan et restreindre les lieux autorisés pour chaque passe (validValidationPlaces).
  2. 2
    Créer une configuration Scanner : Dans Scanner -> Scanner Configurations (/scanner/configs), renseignez le nom du profil, type (ScannerConfigurationType), les modèles autorisés (templateId / allowedTemplates), ScanMode, StoredValueOperation (NONE \| ADD \| SUBTRACT \| SET), StoredValueAmountSource (FIXED \| OPERATOR \| MECHANIC), le code PIN opérateur (unlockPinHash) et la possibilité pour le personnel de changer de profil à la volée (allowChangesViaLink: true).
  3. 3
    Appairer l'appareil ou provisionner une clé :

- Application mobile (SMART_SCAN_APP) : Scannez un QR code d'appairage (ScannerAccessLink) ou saisissez un jeton d'accès pour l'échanger via POST /api/v1/scanner-keys/from-link. - Application authentifiée / terminal POS : Après connexion utilisateur et choix du profil, émettez directement une clé dédiée via POST /api/v1/scanner-keys/for-config.

  1. 4
    Vérifier le signal de vie & la synchro hors ligne : L'application scanner contrôle la validité de sa clé via GET /api/v1/scanner-keys/verify, met en file les scans effectués hors ligne jusqu'à MAX_RETRY_ATTEMPTS = 3 avec des en-têtes x-idempotency-key générés côté client, et met en cache les instantanés de passes via GET /api/v1/scans/offline-dataset.

Architecture & cycle de vie d'appairage des appareils

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
APPAIRAGE DES APPAREILS SCANNER & SYNCHRO TÉLÉMÉTRIQUE
ACTEURS SYSTÈME PARTICIPANTS
P1 Appareil / App Scanner
P2 Scanner Keys API
P3 Scan Validation API
ÉTAPE 1 REQUÊTE / ACTION POST/scanner-keys/
›
from-link {token, pin?}
ÉTAPE 2 RÉPONSE 201 Created
›
{ scannerKey,
›
alidationConfig,
›
key: "sk_live_..." }
ÉTAPE 3 REQUÊTE / ACTION GET/scanner-keys/verify
›
Headers: x-scanner-key,
›
x-scanner-battery-level,
›
x-scanner-queue-backlog
ÉTAPE 4 RÉPONSE 200 OK { shouldRotate }
ÉTAPE 5 REQUÊTE / ACTION GET/scans/offline-dataset ?cursor=...&limit=500
ÉTAPE 6 RÉPONSE 200 OK { items, nextCursor, snapshotAt }

Points d'entrée du cycle de vie des clés Scanner (Scanner Keys API)

Toutes les opérations de provisionnement de clés, bascule de profil, vérification de PIN et rotation sont exposées sous /api/v1/scanner-keys :

MéthodePoint d'entréeAuth / GardeDescription
POST/api/v1/scanner-keys/from-linkPublic (ScannerAccessLink, sans CSRF)Échange { token, pin? } contre une clé persistante x-scanner-key (key, retournée une seule fois).
POST/api/v1/scanner-keys/for-configJWT espace (scans:read)Émet une nouvelle clé scanner pour un { configId } appartenant au locataire.
GET/api/v1/scanner-keys/configsx-scanner-keyListe les configurations SMART_SCAN_APP actives rattachées à l'espace de la clé appelante.
POST/api/v1/scanner-keys/switchx-scanner-keyBascule la clé vers un autre { configId, pin? } lorsque allowChangesViaLink: true.
POST/api/v1/scanner-keys/unlock-pinx-scanner-keyVérifie { pin } face à unlockPinHash avec blocage automatique contre le brute-force.
GET/api/v1/scanner-keys/verifyx-scanner-keyValide le statut de la clé, enregistre les en-têtes de télémétrie et retourne l'indicateur shouldRotate.
POST/api/v1/scanner-keys/revokex-scanner-keyRévoque immédiatement la clé appelante, bloquant toute soumission de scan ultérieure.
POST/api/v1/scanner-keys/:id/rotateJWT espace (scans:read)Effectue une rotation atomique d'une clé scanner par ID et retourne la nouvelle clé secrète brute une seule fois.

1. Appairage via lien d'accès (POST /api/v1/scanner-keys/from-link)

Lorsque l'équipe scanne un QR code de configuration dans l'application Passinstance Scanner, l'appareil échange le jeton de configuration (et le code PIN opérateur optionnel si unlockPinHash est configuré) contre une clé x-scanner-key persistante :

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

Réponse (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"
}

Important : La valeur key n'est retournée qu'une seule fois à la création ou lors d'une rotation et est conservée sous forme d'empreinte SHA-256 (hashKey) en base de données. Stockez key dans le trousseau sécurisé de l'appareil ; en cas de perte, appelez POST /api/v1/scanner-keys/:id/rotate.

2. Signal de vie, télémétrie & conseil de rotation (GET /api/v1/scanner-keys/verify)

Les clients scanner appellent périodiquement GET /api/v1/scanner-keys/verify avec x-scanner-key et des en-têtes opérationnels afin que les administrateurs surveillent l'état du parc en temps réel :

En-tête de télémétrieFormat / ExempleRôle
x-scanner-app-version2.4.1 (build 108)Suit la version de l'application déployée sur les terminaux.
x-scanner-device-idios-idfv-8841-992aIdentifiant matériel unique pour l'inventaire du parc d'appareils.
x-scanner-battery-level0.78 (0–1 ou 0–100)Alerte les opérations lorsque la batterie d'un lecteur descend sous 15 %.
x-scanner-queue-backlog12Nombre de scans hors ligne en file locale en attente d'envoi.

Réponse (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."
}

Lorsque daysUntilExpiration < 15, shouldRotate passe à true, invitant l'appareil ou l'administrateur à renouveler l'identifiant via POST /api/v1/scanner-keys/:id/rotate.

3. Changement de profil à la volée (POST /api/v1/scanner-keys/switch)

Si une configuration autorise allowChangesViaLink: true, les opérateurs peuvent basculer un même terminal mobile entre différents profils SMART_SCAN_APP (par exemple passer de Contrôle d'entrée à Remise boutique VIP) sans réappairer l'appareil :

JSON
{
  "configId": "scfg_vip_merch_02",
  "pin": "9012"
}

Si la configuration cible exige un code PIN opérateur, le serveur vérifie pin face à unlockPinHash avant de réaffecter la clé. Les opérateurs peuvent également vérifier leur PIN séparément via POST /api/v1/scanner-keys/unlock-pin.

Synchronisation du jeu de données hors ligne (GET /api/v1/scans/offline-dataset)

Pour les sites à connectivité cellulaire ou Wi-Fi intermittente, les scanners mobiles synchronisent un instantané compact limité à leur clé (offline scan dataset) via GET /api/v1/scans/offline-dataset.

Paramètres de requête

  • cursor (chaîne optionnelle) : Curseur de pagination retourné par la page précédente (nextCursor).
  • limit (nombre optionnel) : Nombre maximal d'enregistrements par page.
  • snapshotAt (horodatage ISO 8601 optionnel) : Horodatage de synchronisation incrémentale pour ne récupérer que les passes créés, mis à jour ou invalidés depuis le dernier instantané.

Exemple de requête & élément d'instantané (IOfflineDatasetPassResponse)

GET /api/v1/scans/offline-dataset?limit=500&snapshotAt=2026-11-16T08:00:00.000Z
En-tête
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"]
    }
  ]
}

Explorez la compatibilité matérielle et les workflows de validation sur la Page produit Scanner et dans Modes de scan & règles de validation.

Documentation produit et développeur associée

Prêt à lancer votre premier programme de cartes Wallet ?

Créez votre espace de travail, configurez votre modèle et testez une vraie carte dans Apple Wallet et Google Wallet avant de déployer à grande échelle.