Skip to content
Guide du centre d'aide · Présentation de PassinstancePhase d'intégration 1
5 min de lectureVérifié 2026-11-16

Comment fonctionne Passinstance ?

Suivez l'architecture complète, de la création du modèle et la signature jusqu'au scan, aux mises à jour et aux statistiques.

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é
Éléments clés de l'interface

Tableau de bord — KPI & tendances d'inscription (Zoom)

Une fois en production, surveillez Active in Wallets, Removed, Not Installed ainsi que les tendances de création et d'enregistrement.

Vue d'ensemble

Passinstance automatise l'ensemble du cycle de vie des passes numériques : conception visuelle, empaquetage cryptographique, distribution multicanal, validation en point de vente et synchronisation push silencieuse. En séparant la configuration de la mise en page des mécaniques métier et des protocoles de communication des appareils, la plateforme garantit une expérience homogène sur iOS et Android.

Séquence technique de bout en bout

Le diagramme de séquence suivant détaille le flux complet, de la création du modèle à la synchronisation en temps réel avec les portefeuilles :

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
FLUX D'ARCHITECTURE SYSTÈME : CYCLE DE VIE COMPLET D'UN PASSE
ACTEURS SYSTÈME PARTICIPANTS
P1 Admin / Client API
P2 API Centrale Passinstance
P3 Cloud Apple / Google
P4 Appareil Client
ÉTAPE 1 REQUÊTE / ACTION POST/api/v1/templates
›
(Définir design & mécanique)
ÉTAPE 2 REQUÊTE / ACTION POST/api/v1/passes
ÉTAPE 3 REQUÊTE / ACTION Signer .pkpass(PKCS#7)
ÉTAPE 4 REQUÊTE / ACTION Générer Google JWT
›
Retourne l'URL de téléch.
›
(https://app.passinstance.com/d/:slug ou /p/:passId)
ÉTAPE 5 REQUÊTE / ACTION Le client ouvre le lien intelligent de téléchargement
›
(Navigateur détecte l'OS)
ÉTAPE 6 RÉPONSE Appareil enregistré (POST/v1/devices)
›
(pushToken Apple stocké dans Passinstance database)
ÉTAPE 7 REQUÊTE / ACTION Scan au comptoir POS (POST/api/v1/scans)
›
(En-tête : x-scanner-key, Corps : { scannedBarcodeValue })
ÉTAPE 8 REQUÊTE / ACTION Exécuter mécanique
›
(Incrémenter tampons/pts)
ÉTAPE 9 REQUÊTE / ACTION Envoyer push silenc.
›
(Charge APNs vide)
ÉTAPE 10 REQUÊTE / ACTION Réveil APNs silenc.
ÉTAPE 11 RÉPONSE Récupérer passe à jour (GET/v1/passes)
ÉTAPE 12 REQUÊTE / ACTION Livrer nouveau .pkpass
›
(Alerte native écran verr.
›
"Solde mis à jour : %@")

Cycle de vie technique étape par étape

1. Conception & gestion des versions de modèles

Chaque passe provient d'un enregistrement Template. Passinstance utilise un versionnage en table unique suivi par TemplateRowKind (PRODUCTION, PUBLISHED, ARCHIVED, DRAFT) et template status (DRAFT, PUBLISHED, ARCHIVED, DEPRECATED, UNDER_REVIEW, DELETING, DELETED). Les modifications en cours restent isolées dans une révision DRAFT jusqu'à ce qu'un opérateur ou un appel API exécute POST /api/v1/templates/:id/publish, ce qui promeut le brouillon en ligne de base PRODUCTION canonique tout en conservant les instantanés historiques immuables PUBLISHED / ARCHIVED. Avant publication, la plateforme évalue GET /api/v1/templates/:id/publish-risk-check pour analyser les changements critiques de champs et calculer combien de passes actifs seront mis à jour.

2. Signature cryptographique, état des artefacts & émission du passe

Lorsqu'une fiche de passe est générée (POST /api/v1/passes), la création résout templateId via resolvePassCreationTemplateId vers la ligne de base en production, associe un externalId optionnel unique par locataire, respecte l'en-tête optionnel Idempotency-Key (idempotencyKey) et initialise appleArtifactStatus et googleArtifactStatus (ArtifactStatus : NOT_GENERATED -> GENERATING -> READY \| FAILED \| INVALIDATED) :

  • Apple Wallet : lors du téléchargement, Apple Wallet Packager assemble pass.json, jusqu'à 13 emplacements d'images (image asset slot incluant les variantes Retina @2x et @3x) et les fichiers localisés pass.strings dans une archive zip .pkpass, calcule les empreintes de manifest.json et signe le manifeste par chiffrement détaché PKCS#7 avec vos certificats Apple Pass Type ID et Apple WWDR. Plusieurs passes complémentaires partageant un même bundleId (Pass.bundleId) peuvent être livrés ensemble sous forme d'archive .pkpasses.
  • Google Wallet : le backend synchronise les définitions de classes (LoyaltyClass, EventTicketClass, GenericClass, etc.) avec les API REST Google Wallet et signe une URL d'enregistrement JWT RS256 (https://pay.google.com/gp/v/save/:jwt).

3. Distribution par liens intelligents

Passinstance délivre des URLs de présentation intelligentes canoniques (https://app.passinstance.com/d/:slug, https://app.passinstance.com/p/:passId, ou /s/:token sur l'API ou vos domaines personnalisés). Lorsqu'un utilisateur final y accède :

  • L'endpoint de téléchargement public (GET /d/:slug/download) détecte le User-Agent :

- iOS Safari reçoit une réponse HTTP avec le type MIME application/vnd.apple.pkpass, ouvrant la fenêtre native d'ajout à Apple Wallet. - Android Chrome est redirigé vers https://pay.google.com/gp/v/save/:jwt, lançant Google Wallet. - Les navigateurs sur ordinateur affichent la page de téléchargement PassDownload avec un QR code à fort contraste (GET /d/:slug/qr) ainsi que l'envoi optionnel par e-mail ou SMS.

4. Enregistrement de l'appareil & échange Web Service

Dès l'ajout dans Apple Wallet, l'appareil iOS initie le protocole officiel Apple Wallet Web Service :

  • Il envoie POST /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber avec l'en-tête Authorization: ApplePass <authenticationToken>.
  • Passinstance valide le jeton et enregistre le pushToken de l'appareil en base de données, faisant passer le statut du passe de AWAITING_OPT_IN à ACTIVE.

5. Validation en point de vente & exécution des mécaniques

En caisse ou à l'entrée d'un lieu, un opérateur scanne le passe avec l'application Passinstance Scanner ou un système POS intégré :

  • Une requête est envoyée vers POST /api/v1/scans authentifiée par x-scanner-key.
  • Pass Mechanics Engine évalue les règles actives (ajout de tampons, débit de solde prépayé, validation d'un coupon à usage unique ou contrôle d'accès quotidien).

6. Synchronisation cloud par push silencieux

Lorsque les données d'un passe évoluent :

  • Passinstance envoie une charge utile JSON vide {} sur HTTP/2 vers les serveurs Apple APNs.
  • L'appareil Apple se réveille silencieusement en arrière-plan, interroge GET /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier?passesUpdatedSince=<tag> et télécharge le paquet .pkpass actualisé.
  • Tout champ configuré avec un changeMessage contenant le paramètre %@ déclenche une notification native sur l'écran verrouillé iOS.
  • Simultanément, Passinstance envoie une requête REST PATCH vers l'endpoint walletobjects de Google Wallet, mettant à jour la carte Android en temps réel.
Tendances et KPI de la vue d'ensemble du tableau de bord
Tendances et KPI de la vue d'ensemble du tableau de bord

Principaux endpoints & verbes de l'API

Chemin d'endpointMéthode HTTPAuthentificationFonctionnalité
/api/v1/templatesPOSTBearer / Clé APICréer une nouvelle définition de modèle de passe
/api/v1/templates/:id/publishPOSTBearer / Clé APIPromouvoir un modèle brouillon en version de production
/api/v1/passesPOSTBearer / Clé APIÉmettre un nouveau passe avec ses valeurs de champs
/api/v1/passes/:idPATCHBearer / Clé APIMettre à jour les attributs d'un passe et planifier un push
/api/v1/scansPOSTx-scanner-keyValider le code-barres du passe, appliquer la mécanique, enregistrer le scan
/v1/devices/...POSTApplePass <token>Rappel d'enregistrement d'appareil Apple Wallet

Important : Les mises à jour Apple Wallet fonctionnent sur un mode « pull » : Passinstance n'envoie pas les données de la carte dans la notification APNs. À la place, un signal APNs vide indique à l'appareil Apple de venir récupérer de manière sécurisée le dernier fichier .pkpass signé sur les serveurs Passinstance.

Explorez l'ensemble du guide d'intégration en 6 phases ou consultez notre Architecture API.

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.