Aperçu : fonctionnement de la synchronisation en direct
Contrairement aux billets PDF statiques ou aux images de codes-barres, les passes numériques gérés par Passinstance restent reliés au cloud après leur installation. Dès qu'un attribut du passe, un solde de mécanique (tampons, points de fidélité, solde prépayé), un palier ou le design du modèle change, Passinstance exécute un pipeline asynchrone de propagation wallet qui actualise en direct la carte sur l'iPhone, l'Apple Watch et le smartphone Android du client.
Cycle de vie de propagation wallet (walletVoidStatus / WalletPropagationStatus)
Chaque enregistrement de passe suit l'état de propagation de ses mises à jour ou invalidations sur les réseaux Apple et Google via Pass.walletVoidStatus (WalletPropagationStatus) :
État (WalletPropagationStatus) | Signification & état opérationnel |
|---|---|
NONE | Le passe vient d'être créé ou aucune propagation visible n'est en file d'attente. |
PENDING | Une modification de champ, de solde, d'invalidation ou de modèle a été enregistrée en base et attend sa mise en file background job queue. |
QUEUED | La tâche a été transmise à la file in-memory cache/background job queue pour exécution APNs et Google REST. |
SUCCEEDED | La notification APNs a été acceptée par la passerelle HTTP/2 d'Apple (200 OK) et/ou le PATCH REST Google Wallet a abouti. |
FAILED | La propagation a rencontré une erreur en amont (ex. certificat Apple Pass Type expiré, jeton APNs révoqué 410 Gone ou quota Google API). |
Important : La publication d'un brouillon de modèle via
POST /api/v1/templates/:id/publishavecpropagateUpdates: truediffuse les tâches de propagation vers tous les passes actifs liés à ce modèle (filtrable avecactivePassesOnly: true). Exécutez toujoursGET /api/v1/templates/:id/publish-risk-checkau préalable pour inspecter les modifications critiques et leur impact potentiel.
Points d'entrée API pour mettre à jour des passes
| Méthode | Chemin du point d'entrée | Description |
|---|---|---|
| PATCH | /api/v1/passes/:id | Met à jour les attributs personnalisés, le statut, la date d'expiration ou le code-barres d'un passe individuel et déclenche la propagation wallet. |
| POST | /api/v1/passes/upsert-by-external-id | Crée ou met à jour de façon idempotente un passe existant identifié par (customerId, externalId) (PUT /api/v1/passes/by-external-id/:externalId également pris en charge). |
| POST | /api/v1/batch-pass-operations/update | Met à jour les passIds sélectionnés en une requête groupée (request payload) et met en file les tâches de propagation. |
| POST | /api/v1/templates/:id/publish | Promeut un brouillon de modèle (request payload avec propagateUpdates: true) et rafraîchit les passes actifs associés. |
Exemple : mise à jour d'un passe individuel & déclenchement de propagation
PATCH /api/v1/passes/c41a8d20-6e11-4f3b-9a81-0029d81a4f10
{
"attributes": {
"points": 1450,
"tier": "Platinum",
"nextReward": "Free Espresso"
},
"expirationDate": "2027-12-31 23:59"
}
Réponse (200 OK) :
{
"id": "c41a8d20-6e11-4f3b-9a81-0029d81a4f10",
"externalId": "cust_884910",
"serialNumber": "PI-8849-2026-X9",
"status": "ACTIVE",
"lifecycleStatus": "ACTIVE",
"walletVoidStatus": "QUEUED",
"updatedAt": "2026-11-15T14:22:10.114Z"
}
Exemple : mise à jour groupée par tableau d'identifiants (request payload)
POST /api/v1/batch-pass-operations/update
{
"operation": "update",
"passIds": [
"c41a8d20-6e11-4f3b-9a81-0029d81a4f10",
"9b2f1e44-8a10-4c92-a711-5530e91b2c01"
],
"updateData": {
"attributes": {
"seasonalOffer": "Winter Bonus Points"
}
}
}
Pourquoi les délais de synchronisation varient selon les appareils
-
Mode Avion & Mode Faibles données : Les appareils iOS en mode Avion ou en économie d'énergie diffèrent les téléchargements APNs en arrière-plan jusqu'au retour d'une connexion Wi-Fi ou cellulaire.
-
Interrupteur de mise à jour manuelle : Si le client a désactivé Mises à jour automatiques au verso de sa carte dans Apple Wallet, il doit tirer l'écran vers le bas manuellement dans Apple Wallet pour récupérer la dernière archive
.pkpass. -
Filtrage des passes invalidés : Par défaut, les passes au statut
VOIDEDouEXPIREDbloquent les notifications marketing courantes sauf si l'optionupdateVoidedExpiredPasses: trueest activée sur le modèle.
Consultez Notifications push, Consulter & modifier les passes et Versions & publication des modèles pour les workflows associés.
