Skip to content
Guide du centre d'aide · Mises à jour & notifications
3 min de lectureVérifié 2026-11-16

Mettre à jour des passes existants

Comprenez comment les modifications serveur déclenchent les rafraîchissements APNs Apple et patchs REST Google Wallet.

Dans ce guide

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.

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
PIPELINE DE MISE À JOUR & PROPAGATION WALLET
ÉTAPE 01 SOURCES DE DÉCLENCHEMENT DE MUTATION
MàJ unitaire : PATCH/api/v1/passes/:id ou upsert-by-external-id
MàJ en lot : POST/api/v1/batch-pass-operations/update
Publication modèle : POST/api/v1/templates/:id/publish (propagateUpdates: true)
Scanner / Caisse : POST/api/v1/scans / /v1/pos/redeem / /api/v1/reader/redeem
ÉTAPE 02 VALIDATION EN BASE & TRANSITION D'ÉTAT DE PROPAGATION
1
Incrémenter la révision du passe & enregistrer dans pass audit log
2
Mettre à jour walletVoidStatus (WalletPropagationStatus) : NONEPENDINGQUEUED
3
Mettre en file background job queue (wallet-propagation)
Enregistrements Apple Wallet
ÉTAPE 03A
1
Apple Push Delivery envoie un push H vide {} aux appareils enregistrés
2
iOS se réveille et interroge :GET/v1/devices/.../registrations
3
iOS télécharge le .pkpass mis à jour via GET/v1/passes/:type/:sn
Objet cloud Google Wallet
ÉTAPE 03B /2 | | 1. Google Wallet Sync exécu
un PATCH REST authentifié sur walletobjects/v1/...
2
Google Cloud pousse l'état mis à jour vers Android via Google Play Services
ÉTAPE 04 TÉLÉMÉTRIE FINALE & STATUT DE PROPAGATION
walletVoidStatus (WalletPropagationStatus) : SUCCEEDED ou FAILED

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
NONELe passe vient d'être créé ou aucune propagation visible n'est en file d'attente.
PENDINGUne 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.
QUEUEDLa tâche a été transmise à la file in-memory cache/background job queue pour exécution APNs et Google REST.
SUCCEEDEDLa notification APNs a été acceptée par la passerelle HTTP/2 d'Apple (200 OK) et/ou le PATCH REST Google Wallet a abouti.
FAILEDLa 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/publish avec propagateUpdates: true diffuse les tâches de propagation vers tous les passes actifs liés à ce modèle (filtrable avec activePassesOnly: true). Exécutez toujours GET /api/v1/templates/:id/publish-risk-check au préalable pour inspecter les modifications critiques et leur impact potentiel.

Points d'entrée API pour mettre à jour des passes

MéthodeChemin du point d'entréeDescription
PATCH/api/v1/passes/:idMet à 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-idCré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/updateMet à 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/publishPromeut 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

JSON
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) :

JSON
{
  "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)

JSON
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 VOIDED ou EXPIRED bloquent les notifications marketing courantes sauf si l'option updateVoidedExpiredPasses: true est activée sur le modèle.

Consultez Notifications push, Consulter & modifier les passes et Versions & publication des modèles pour les workflows associés.

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.