Aperçu
Ouvrez Passes dans le tableau de bord (dans le répertoire global de l'espace de travail ou directement dans l'onglet Passes d'un modèle) ou interrogez /api/v1/passes pour inspecter, filtrer, auditer, mettre à jour et migrer les cartes émises en temps réel. Chaque modification des champs ou du modèle assigné se synchronise automatiquement vers les appareils Apple Wallet et Google Wallet enregistrés.

Architecture système : requêtes, mutations & changement de modèle
1. Rechercher & filtrer des passes (GET /api/v1/passes)
Dans le tableau de bord, ouvrez Filtres pour combiner des groupes de conditions ET / OU entre colonnes système et attributs structured JSON personnalisés, puis enregistrez vos requêtes récurrentes en Vues enregistrées :
-
Identité & clés :
serialNumber,externalId,bundleId,idempotencyKeyouiddu passe. -
Cycle de vie & statut :
status(pass status),lifecycleStatus(PassLifecycleStatus),walletVoidStatus(WalletPropagationStatus) et disponibilité des artefacts (appleArtifactStatus,googleArtifactStatus). -
État d'installation Wallet :
Installed,Not InstalledouRemovedsur les enregistrements Apple Wallet (iOS) et Google Wallet (Android). -
Fenêtres temporelles : Plages de dates
createdAt,updatedAt,expirationDateetlastScannedAt. -
Attributs structured JSON personnalisés (
attribute search index) : Filtres rapides de contenance et comparaison sur toute clé depass.attributes(par exempleattributes.memberTier = "VIP"ouattributes.pointsBalance >= 1000).

Exemple : Rechercher des passes & consulter par External ID
-
GET /api/v1/passes?templateId=tmpl_01hxyz987654321&status=ACTIVE&externalId=crm_usr_44910&page=1&limit=25 -
GET /api/v1/passes/by-external-id/crm_usr_44910(retourne directement le passe actif non supprimé correspondant àexternalIdsans nécessiter de stocker nos UUID internes)
2. Mettre à jour un passe individuel (PATCH /api/v1/passes/:id)
La mise à jour d'un passe fusionne les nouvelles valeurs dans attributes, ajuste expirationDate ou barcodeValue, et place immédiatement en file une notification push vers tous les appareils où le passe est installé. Si un champ modifié possède un changeMessage contenant %@ sur le modèle, Apple Wallet affiche une bannière native sur l'écran verrouillé.
Requête HTTP
PATCH /api/v1/passes/pass_01j8k9m2n3p4q5r6 En-têtes : X-API-Key: <API_KEY> | Content-Type: application/json
{
"attributes": {
"pointsBalance": 1450,
"memberTier": "Platinum"
},
"barcodeAltText": "44910-PLATINUM",
"expirationDate": "2028-12-31 23:59"
}
Réponse HTTP (200 OK)
{
"success": true,
"data": {
"id": "pass_01j8k9m2n3p4q5r6",
"serialNumber": "PI-GOLD-2026-44910",
"externalId": "crm_usr_44910",
"bundleId": null,
"status": "ACTIVE",
"lifecycleStatus": "ACTIVE",
"walletVoidStatus": "QUEUED",
"attributes": {
"firstName": "Marcus",
"lastName": "Vance",
"email": "marcus.vance@example.com",
"pointsBalance": 1450,
"memberTier": "Platinum"
},
"updatedAt": "2026-11-15T17:30:00.000Z"
},
"statusCode": 200
}
3. Consulter l'historique d'audit & la chronologie
Passinstance maintient deux flux d'audit complémentaires pour chaque enregistrement :
| Endpoint | Portée & données retournées | |||
|---|---|---|---|---|
GET /api/v1/passes/:id/history | Retourne la chronologie des mutations de champs et d'attributs (previousValue, newValue, changedBy, `source: 'API' \ | 'SCANNER' \ | 'DASHBOARD' \ | 'WORKFLOW', timestamp`). |
GET /api/v1/passes/:id/timeline | Retourne le flux unifié cycle de vie et engagement, combinant émission, envois e-mail/SMS, installations Apple/Google, validations scanner, variations de solde et notifications push. |
Exemple : Récupérer la chronologie d'un passe
/api/v1/passes/pass_01j8k9m2n3p4q5r6/timeline
{
"success": true,
"data": {
"passId": "pass_01j8k9m2n3p4q5r6",
"events": [
{
"eventId": "evt_03",
"type": "ATTRIBUTE_UPDATED",
"summary": "pointsBalance changed from 500 to 1450",
"actor": "api_key:pi_live_99a8",
"createdAt": "2026-11-15T17:30:00.000Z"
},
{
"eventId": "evt_02",
"type": "WALLET_INSTALLED",
"platform": "APPLE_WALLET",
"deviceLibraryIdentifier": "dlib_8841209a",
"createdAt": "2026-11-15T15:10:05.000Z"
},
{
"eventId": "evt_01",
"type": "PASS_CREATED",
"summary": "Pass issued via REST API",
"createdAt": "2026-11-15T15:04:12.000Z"
}
]
},
"statusCode": 200
}
4. Migration de modèle en direct (POST /api/v1/passes/:id/switch-template/:targetTemplateId)
Lorsqu'un client accède à un nouveau palier ou change de programme saisonnier, vous pouvez migrer une carte existante vers un autre modèle PUBLISHED sans modifier l'id, le serialNumber, l'authenticationToken ni les enregistrements d'appareils actifs.
POST /api/v1/passes/pass_01j8k9m2n3p4q5r6/switch-template/tmpl_platinum_vip_999 En-têtes : X-API-Key: <API_KEY> | Content-Type: application/json
{
"preserveAttributes": true,
"attributeOverrides": {
"vipLoungeAccess": "Unlimited"
},
"pushUpdateImmediately": true
}
Important : Pour basculer un passe vers
:targetTemplateIdde manière transparente sur les appareils Apple Wallet, le modèle source et le modèle cible doivent partager le mêmepassTypeIdentifierApple (certificat Pass Type ID). Si le modèle cible utilise un autre Pass Type ID, iOS traitera le passe comme une nouvelle carte distincte au lieu de remplacer l'existante sur place.
Pour les transitions d'état et règles d'invalidation, consultez Cycle de vie & statuts des passes. Pour les mises à jour multi-enregistrements, consultez Opérations en masse.
