Skip to content
Référence API REST & SDKs

Documentation Développeur Passinstance

Créez des intégrations Apple Wallet (.pkpass) et Google Wallet à grande échelle. Émettez, mettez à jour, validez et diffusez des notifications en direct via des API REST prêtes pour la production.

Obtenir les clés API
Atelier docs en direct — les extraits se mettent à jour en temps réel
Sécurité

Aperçu — Fonctionnement de la validation des cartes

Chaque scan de code-barres ou NFC exécute un pipeline déterministe de validation en 14 règles (statut, expiration, créneaux horaires, géorepérage, mécaniques, quotas, anti-rejeu) avec nonces cryptographiques optionnels et synchronisation hors ligne.

Nonce anti-rejeu

POST /api/v1/scans/prepare émet un nonce cryptographique anti-rejeu éphémère lié au code-barres

Pipeline à 14 règles

PassStatus → Expiration → TimeWindow → Geofencing → Mechanics → RateLimit → AntiReplay

Synchronisation hors ligne

GET /api/v1/scans/offline-dataset fournit des instantanés paginés par curseur pour terminaux hors ligne

Appairage de clé scanner

POST /api/v1/scanner-keys/from-link échange un jeton d'appairage + PIN contre une clé x-scanner-key

Configuration du scanner

3 points de terminaison
GEThttps://api.passinstance.com/api/v1/validation/configsClé API
Configuration du scanner

Lister les configurations de scanner

Listez tous les profils de configuration de scanner (application mobile, scanner web, TPV) et leurs permissions de modèles.

En-têtes1 requis
X-API-Keystring
Requis

Clé API secrète de l'espace de travail (pi_live_... ou pi_test_...). Vous pouvez également envoyer Authorization: ApiKey <key>.

Exemple : pi_live_98a7b6c5d4e3f2a1
Paramètres de requête2 optionnel(s)

Codes de statut de réponse

GEThttps://api.passinstance.com/api/v1/validation/configs/{id}Clé API
Configuration du scanner

Obtenir la configuration du scanner

Obtenez les détails d'une configuration de scanner spécifique, incluant les modèles autorisés, le message après scan et les règles.

En-têtes1 requis
X-API-Keystring
Requis

Clé API secrète de l'espace de travail (pi_live_... ou pi_test_...). Vous pouvez également envoyer Authorization: ApiKey <key>.

Exemple : pi_live_98a7b6c5d4e3f2a1
Paramètres de chemin1 requis
idstring (UUID)
Requis

UUID de la configuration de scanner.

Exemple : 7a8b9c0d-1e2f-4a3b-8c9d-0e1f2a3b4c5d

Codes de statut de réponse

POSThttps://api.passinstance.com/api/v1/validation/configsClé API
Configuration du scanner

Créer une configuration de scanner

Créez un nouveau profil de configuration de scanner avec modèles autorisés, action de scan par défaut et message de confirmation.

En-têtes1 requis
X-API-Keystring
Requis

Clé API secrète de l'espace de travail (pi_live_... ou pi_test_...). Vous pouvez également envoyer Authorization: ApiKey <key>.

Exemple : pi_live_98a7b6c5d4e3f2a1

Scanner configuration profile name, allowed template UUIDs, scan mode, and optional cooldown window.

Corps de la requête2 requis • 2 optionnel(s)
namestring
Requis

Nom lisible pour la configuration du scanner.

Exemple : Main Entrance Gate Scanners
templateIdsstring[] (UUID)
Requis

UUID des modèles autorisés pour la validation sous ce profil.

Exemple : ["8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b"]

Codes de statut de réponse

Opérations de scan

4 points de terminaison
GEThttps://api.passinstance.com/api/v1/validation/scansClé API
Opérations de scan

Lister les enregistrements de scan

Consultez le journal d'audit paginé des scans de cartes avec filtrage par modèle, carte, configuration de scanner, décision et période.

En-têtes1 requis
X-API-Keystring
Requis

Clé API secrète de l'espace de travail (pi_live_... ou pi_test_...). Vous pouvez également envoyer Authorization: ApiKey <key>.

Exemple : pi_live_98a7b6c5d4e3f2a1
Paramètres de requête3 optionnel(s)

Codes de statut de réponse

POSThttps://api.passinstance.com/api/v1/scansClé Scanner
Opérations de scan

Traiter un scan code-barres / NFC

Valider un code-barres optique, QR code ou scan NFC Apple VAS / Google Smart Tap depuis un terminal ou scanner mobile via le moteur à 14 règles.

En-têtes2 requis • 2 optionnel(s)
x-scanner-keystring
Requis

Clé de configuration de scanner provisionnée dans le tableau de bord ou via un lien d'appairage.

Exemple : scan_key_77a8b9c0d1e2f3a4b5c6d7e8
Content-Typestring
Requis

Doit être application/json.

Exemple : application/json

Charge utile Charge utile de requête contenant le code-barres scanné, un nonce anti-rejeu optionnel, les métadonnées canal/protocole et le contexte opérateur.

Corps de la requête1 requis • 8 optionnel(s)
scannedBarcodeValuestring
Requis

Chaîne brute lue depuis le QR code, PDF417, CODE128, AZTEC ou tap NFC.

Exemple : PI-8891-JD-VIP

Codes de statut de réponse

POSThttps://api.passinstance.com/api/v1/scans/prepareClé Scanner
Opérations de scan

Préparer un nonce de scan anti-rejeu

Émettre un nonce cryptographique anti-rejeu éphémère lié à un code-barres de carte avant d'exécuter POST /api/v1/scans.

En-têtes1 requis
x-scanner-keystring
Requis

Clé de configuration de scanner provisionnée dans le tableau de bord ou via un lien d'appairage.

Exemple : scan_key_77a8b9c0d1e2f3a4b5c6d7e8

Charge utile de requête contenant la valeur du code-barres scanné à associer au nonce cryptographique.

Corps de la requête1 requis
scannedBarcodeValuestring
Requis

Chaîne de code-barres ou jeton NFC à associer au nonce anti-rejeu.

Exemple : PI-8891-JD-VIP

Codes de statut de réponse

GEThttps://api.passinstance.com/api/v1/scans/offline-datasetClé Scanner
Opérations de scan

Télécharger le jeu de données scanner hors ligne

Télécharger un instantané paginé par curseur des cartes autorisées pour la clé x-scanner-key afin de permettre la validation locale hors ligne.

En-têtes1 requis
x-scanner-keystring
Requis

Clé de configuration de scanner provisionnée dans le tableau de bord ou via un lien d'appairage.

Exemple : scan_key_77a8b9c0d1e2f3a4b5c6d7e8
Paramètres de requête3 optionnel(s)

Codes de statut de réponse