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 :
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 Packagerassemblepass.json, jusqu'à 13 emplacements d'images (image asset slot incluant les variantes Retina@2xet@3x) et les fichiers localiséspass.stringsdans une archive zip.pkpass, calcule les empreintes demanifest.jsonet 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êmebundleId(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 JWTRS256(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/:serialNumberavec l'en-têteAuthorization: ApplePass <authenticationToken>. -
Passinstance valide le jeton et enregistre le
pushTokende l'appareil en base de données, faisant passer le statut du passe deAWAITING_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/scansauthentifiée parx-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.pkpassactualisé. -
Tout champ configuré avec un
changeMessagecontenant le paramètre%@déclenche une notification native sur l'écran verrouillé iOS. -
Simultanément, Passinstance envoie une requête REST
PATCHvers l'endpointwalletobjectsde Google Wallet, mettant à jour la carte Android en temps réel.

Principaux endpoints & verbes de l'API
| Chemin d'endpoint | Méthode HTTP | Authentification | Fonctionnalité |
|---|---|---|---|
/api/v1/templates | POST | Bearer / Clé API | Créer une nouvelle définition de modèle de passe |
/api/v1/templates/:id/publish | POST | Bearer / Clé API | Promouvoir un modèle brouillon en version de production |
/api/v1/passes | POST | Bearer / Clé API | Émettre un nouveau passe avec ses valeurs de champs |
/api/v1/passes/:id | PATCH | Bearer / Clé API | Mettre à jour les attributs d'un passe et planifier un push |
/api/v1/scans | POST | x-scanner-key | Valider le code-barres du passe, appliquer la mécanique, enregistrer le scan |
/v1/devices/... | POST | ApplePass <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
.pkpasssigné sur les serveurs Passinstance.
Explorez l'ensemble du guide d'intégration en 6 phases ou consultez notre Architecture API.
