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

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, ouscans:readpour 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) | Canal | Mécanisme d'auth | Déploiement type |
|---|---|---|---|
SMART_SCAN_APP | Application Passinstance Scanner (iOS / Android) & SDK caisse intégrés | Clé appairée x-scanner-key (from-link ou for-config) | Contrôle d'entrée mobile, sites hors ligne, caisses enregistreuses en boutique. |
VALIDATION_LINK | Point 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
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
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
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.
-
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 = 3avec des en-têtesx-idempotency-keygénérés côté client, et met en cache les instantanés de passes viaGET /api/v1/scans/offline-dataset.
Architecture & cycle de vie d'appairage des appareils
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éthode | Point d'entrée | Auth / Garde | Description |
|---|---|---|---|
| POST | /api/v1/scanner-keys/from-link | Public (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-config | JWT espace (scans:read) | Émet une nouvelle clé scanner pour un { configId } appartenant au locataire. |
| GET | /api/v1/scanner-keys/configs | x-scanner-key | Liste les configurations SMART_SCAN_APP actives rattachées à l'espace de la clé appelante. |
| POST | /api/v1/scanner-keys/switch | x-scanner-key | Bascule la clé vers un autre { configId, pin? } lorsque allowChangesViaLink: true. |
| POST | /api/v1/scanner-keys/unlock-pin | x-scanner-key | Vérifie { pin } face à unlockPinHash avec blocage automatique contre le brute-force. |
| GET | /api/v1/scanner-keys/verify | x-scanner-key | Valide 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/revoke | x-scanner-key | Révoque immédiatement la clé appelante, bloquant toute soumission de scan ultérieure. |
| POST | /api/v1/scanner-keys/:id/rotate | JWT 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 :
{
"token": "sal_9f82b1c4e7a043d19b2e",
"pin": "4829"
}
Réponse (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"
}
Important : La valeur
keyn'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. Stockezkeydans le trousseau sécurisé de l'appareil ; en cas de perte, appelezPOST /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étrie | Format / Exemple | Rôle |
|---|---|---|
x-scanner-app-version | 2.4.1 (build 108) | Suit la version de l'application déployée sur les terminaux. |
x-scanner-device-id | ios-idfv-8841-992a | Identifiant matériel unique pour l'inventaire du parc d'appareils. |
x-scanner-battery-level | 0.78 (0–1 ou 0–100) | Alerte les opérations lorsque la batterie d'un lecteur descend sous 15 %. |
x-scanner-queue-backlog | 12 | Nombre de scans hors ligne en file locale en attente d'envoi. |
Réponse (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."
}
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 :
{
"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)
/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"]
}
]
}
Explorez la compatibilité matérielle et les workflows de validation sur la Page produit Scanner et dans Modes de scan & règles de validation.
