L'API REST Passinstance est organisée en contrôleurs de domaines modulaires montés principalement sous /api/v1 (avec des points de montage dédiés sans préfixe pour la caisse POS /v1/pos/*, les Pull Webhooks /webhook-payload, les webhooks entrants fournisseurs /webhooks/*, les sondes de santé /health/* ainsi que les liens intelligents /s/:token et /d/:slug). Chaque point d'entrée utilise les verbes HTTP standard (GET, POST, PUT, PATCH, DELETE), applique l'isolation locataire de l'espace depuis votre identifiant API et retourne une charge utile JSON déterministe (API response (T) sur les API d'espace de travail).
Prérequis : Générez une clé API d'espace (pi_live_... ou pi_test_...) dotée des API_KEY_SCOPE_VALUES requis (passes, templates, scans, webhooks, analytics ou *) sous /settings/workspace/developer/api-credentials avant d'appeler les routes /api/v1/*. Une documentation OpenAPI interactive est accessible sur GET /api/public/docs et /docs.
Cycle de vie des requêtes & réponses
FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
CYCLE DE REQUÊTE API REST & ENVELOPPE
ACTEURS SYSTÈME PARTICIPANTS
P1Intégration externe
P2Passinstance /api/v1/*
P3Fournisseurs Wallet & BDD
ÉTAPE 1REQUÊTE / ACTIONPOST/api/v1/passes
ÉTAPE 2REQUÊTE / ACTIONValider DTO & locataire
ÉTAPE 3REQUÊTE / ACTIONSigner .pkpass (bundleId)
›
idempotencyKey
›
& générer JWT Google Wallet
ÉTAPE 4RÉPONSE201 Created
›
API response (request payload)
ÉTAPE 5REQUÊTE / ACTIONPATCH/api/v1/passes/:id
ÉTAPE 6REQUÊTE / ACTIONEnregistrer mise à jour
ÉTAPE 7RÉPONSE200 OK
›
7. Mettre en file Push APNs/Google
[ FLUX ARCHITECTURE SYSTÈME : CYCLE DE REQUÊTE API REST & ENVELOPPE ]
Intégration externe Passinstance /api/v1/* Fournisseurs Wallet & BDD
| | |
|-- 1. POST /api/v1/passes --------->| |
| En-tête : x-api-key: pi_live_ |-- 2. Valider DTO & locataire |
| Corps : externalId, |-- 3. Signer .pkpass (bundleId) |
| idempotencyKey| & générer JWT Google Wallet ->|
|<-- 4. 201 Created -----------------| |
| API response (request payload) | |
| | |
|-- 5. PATCH /api/v1/passes/:id ---->| |
| Corps : { attributes: {...} } |-- 6. Enregistrer mise à jour ----->|
|<-- 7. 200 OK ----------------------|-- 7. Mettre en file Push APNs/Google
Catalogue des points d'entrée REST par domaine
1. Passes, Upserts & opérations en masse
Verbe
Chemin
Description
POST
/api/v1/passes
Émet une instance de passe (request payload : templateId, externalId optionnel, idempotencyKey, attributes) signée avec le certificat du modèle (bundleId = passTypeIdentifier Apple).
POST
/api/v1/passes/upsert-by-external-id
Crée ou met à jour de façon idempotente un passe apparié sur (templateId, externalId) (request payload).
GET
/api/v1/passes
Liste les instances de passes avec pagination, filtrage par statut (pass status) et recherche.
GET
/api/v1/passes/:id
Récupère tous les détails, attributs dynamiques, externalId, serialNumber et statut d'enregistrement.
PATCH / PUT
/api/v1/passes/:id
Met à jour les champs dynamiques, le palier ou la date d'expiration et pousse la mise à jour vers les portefeuilles installés.
POST
/api/v1/passes/voiding/:id/void
Invalide un passe (request payload + VoidingReason) et envoie un push silencieux voided: true.
DELETE
/api/v1/passes/:id
Supprime logiquement un passe et révoque les installations wallet actives.
POST
/api/v1/passes/export
Exporte une liste filtrée d'enregistrements de passes en téléchargement CSV UTF-8 ou JSON.
POST
/api/v1/batch-pass-operations/create
Exécute des créations en masse synchrones/en file via Batch Operations API (ainsi que /update, /upsert, /activate, /deactivate, /delete).
POST
/api/v1/batch-processing
Soumet un traitement asynchrone volumineux CSV/JSON suivi via Batch Processing API.
2. Modèles & mécaniques
Verbe
Chemin
Description
GET
/api/v1/templates
Liste les modèles de l'espace, leurs types (PassKind), liaisons de certificat bundleId et états de publication.
GET
/api/v1/templates/:id
Retourne le schéma du modèle, la configuration visuelle et les mécaniques actives.
POST
/api/v1/templates/:id/publish
Publie les modifications de brouillon (request payload) et diffuse les mises à jour push par lots (GET .../publish-risk-check au préalable).
GET
/api/v1/templates/:templateId/attributes
Liste les clés de champs dynamiques et leurs types attendus à l'émission (prend en charge OAuth templates:read).
POST
/api/v1/mechanics/redeem
Consomme une récompense débloquée de fidélité ou carte à tampons (request payload : UUID passId, mechanicId).
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.