Skip to content
Guide du centre d'aide · Gestion des passesPhase d'intégration 4
6 min de lectureVérifié 2026-11-16

Cycle de vie & statuts des passes

Comprenez les statuts Créé, Non installé, Installé, Expiré et Annulé ainsi que leur impact sur la facturation et le scan.

Dans ce guide

Visites interactives de l'interface

Ouvrir dans le guide en 6 phases

Inspectez les écrans exacts du tableau de bord et les zooms annotés liés à ce guide.

Focus interface zoomé
Éléments clés de l'interface

Info-bulle d'état d'installation Wallet en direct (Zoom)

Cliquez sur l'icône Apple Wallet ou Google Wallet d'une carte pour vérifier les enregistrements actifs, les suppressions et l'historique d'installation.

Aperçu

Passinstance pilote chaque carte émise à travers trois automates d'état orthogonaux portés par le modèle Pass :

  1. 1
    pass status (11 valeurs) : État de validité métier fonctionnelle déterminant si une carte peut être installée, scannée ou utilisée.
  2. 2
    PassLifecycleStatus (5 étapes) : Progression administrative de rétention et révocation depuis ACTIVE jusqu'à DELETED.
  3. 3
    WalletPropagationStatus (5 étapes) : État de synchronisation cloud asynchrone suivant la diffusion push APNs et Google Wallet.

Architecture système : automates de cycle de vie & propagation Wallet

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
FLUX D'ARCHITECTURE : AUTOMATE DE CYCLE DE VIE & PROPAGATION WALLET
ÉTAPE 01
1
STATUT MÉTIER (pass status) [DRAFT] / [AWAITING_OPT_IN] / [PENDING_ACTIVATION]
[GENERATING][ACTIVE] <[INACTIVE] / [SUSPENDED] [REDEEMED] [EXPIRED] [CANCELLED] / [VOIDED]
ÉTAPE 02
2
PROGRESSION DU CYCLE (PassLifecycleStatus) [ACTIVE][VOIDING][VOIDED][DELETING][DELETED]
ÉTAPE 03
3
PIPELINE SYNCHRO CLOUD (WalletPropagationStatus) [NONE][PENDING][QUEUED][SUCCEEDED] (ou [FAILED] + Retry)

1. Les 11 états métier de pass status

Valeur pass statusRésultat validation scannerRendu visuel Wallet & comportement
DRAFTRejeté (INVALID)L'enregistrement existe en base avant signature ; le lien de téléchargement n'est pas actif.
AWAITING_OPT_INRejeté (PENDING)Créé via PassFlow ou campagne ; en attente de code OTP e-mail/SMS ou consentement RGPD.
PENDING_ACTIVATIONRejeté (PENDING)Carte émise en attente de capture de paiement externe ou scan d'activation en caisse.
GENERATINGRejeté (PENDING)Le bundle cryptographique .pkpass ou l'objet Google Wallet est en cours de compilation par un worker.
ACTIVEAccepté (SUCCESS)Carte active et valide éligible au scan, cumul de points, passage NFC et notifications push.
INACTIVERejeté (INVALID)Désactivé temporairement par l'opérateur (POST /api/v1/batch-pass-operations/deactivate).
SUSPENDEDRejeté (INVALID)Gelé pour suspicion de fraude, impayé ou blocage de sécurité ; réversible vers ACTIVE.
REDEEMEDRejeté (ALREADY_USED)Coupon ou billet à usage unique déjà scanné et consommé (VOIDED_AFTER_SCAN scan mode).
EXPIREDRejeté (EXPIRED)L'horodatage courant a dépassé Pass.expirationDate ; le code-barres s'affiche grisé sur le téléphone.
CANCELLEDRejeté (ALREADY_VOIDED)L'inscription ou la commande a été annulée (ex. billet remboursé) avant utilisation.
VOIDEDRejeté (ALREADY_VOIDED)Invalidé définitivement via Pass Voiding API ; définit "voided": true dans pass.json Apple et STATE_EXPIRED/INACTIVE dans Google Wallet.

2. Les 5 étapes de PassLifecycleStatus

La colonne lifecycleStatus orchestre la révocation multi-étapes sécurisée et le nettoyage en base de données sans laisser d'objets orphelins côté client :

ÉtapeDescription
ACTIVEÉtat opérationnel normal couvrant les cartes actives, inactives ou expirées.
VOIDINGVerrou transitoire acquis dès l'envoi d'une demande d'invalidation ; met en file les mises à jour push prioritaires Apple et Google Wallet.
VOIDEDRévocation terminale achevée ; l'horodatage voidedAt et le motif voidReason sont inscrits définitivement dans le registre.
DELETINGVerrou transitoire acquis lorsqu'un opérateur demande la suppression définitive ; révoque les jetons de téléchargement et délie les médias stockés.
DELETEDÉtat marqueur de suppression logique ou suppression finalisée avant purge RGPD.

3. walletVoidStatus (WalletPropagationStatus), modes de suppression & artefacts

Passinstance suit la propagation push asynchrone, la sémantique de suppression et la compilation des artefacts Wallet via des colonnes et énumérations Passinstance database dédiées sur Pass :

walletVoidStatus (WalletPropagationStatus)

Lorsqu'une invalidation ou transition d'état est envoyée vers Apple APNs ou Google Wallet, Pass.walletVoidStatus trace sa progression :

Étape (WalletPropagationStatus)Description
NONELa carte vient d'être créée ou aucune propagation d'invalidation n'a encore été mise en file.
PENDINGUne mise à jour de champ ou transition de cycle a été validée dans database et attend le répartiteur de propagation.
QUEUEDUne tâche background job queue est activement en file pour transmettre la notification HTTP/2 APNs ou le PATCH Google Wallet.
SUCCEEDEDTous les appareils enregistrés / objets cloud ont acquitté la mise à jour (côté Apple Wallet, l'appareil a téléchargé le nouveau .pkpass via GET /v1/passes/...).
FAILEDLa livraison a rencontré une erreur amont (ex. jeton APNs désinscrit ou quota Google API) ; éligible à une relance.

PassDeletionMode & ArtifactStatus

  • PassDeletionMode (SOFT | HARD) : DELETE /api/v1/passes/:id applique une suppression logique SOFT (renseigne archivedAt et libère immédiatement l'unicité (customerId, externalId) pour réémission tout en conservant les journaux d'audit), alors que DELETE /api/v1/passes/:id/hard exécute une purge HARD.
  • ArtifactStatus (appleArtifactStatus, googleArtifactStatus) : NOT_GENERATED | GENERATING | READY | FAILED | INVALIDATED indique si le paquet cryptographique ou l'objet cloud de chaque plateforme est compilé et à jour.

Invariant important de facturation & cycle de vie Wallet

Important : Invalider ou expirer un passe rejette les validations futures au scanner et grise visuellement la carte dans le Wallet du client, mais Apple iOS et Google Android interdisent aux serveurs tiers de supprimer de force une carte sur le téléphone sans action de l'utilisateur. Sur Apple Wallet, les cartes invalidées masquent les bannières sur écran verrouillé sauf si updateVoidedExpiredPasses: true est activé sur le modèle. Une carte installée reste comptabilisée comme enregistrement d'appareil actif tant que le client ne l'a pas retirée de son Wallet ou que la désinscription n'est pas finalisée.

API de désactivation & invalidation (Passes API / Pass Voiding API)

Passinstance expose une désactivation réversible (POST /api/v1/passes/:id/deactivate) et des endpoints dédiés d'invalidation sous /api/v1/passes/voiding (acceptant VoidingReason : EXPIRED, CANCELLED, LOST, STOLEN, DUPLICATE, FRAUD, TECHNICAL_ISSUE, CUSTOMER_REQUEST, ADMIN_ACTION, SYSTEM_AUTO, OTHER) :

EndpointPortéeDescription
POST /api/v1/passes/:id/deactivatePasse uniqueFait passer temporairement le passe de ACTIVE à INACTIVE.
POST /api/v1/passes/voiding/:id/voidPasse uniqueInvalide (voided: true) ou réactive (voided: false) un passe unique (204 No Content).
POST /api/v1/passes/voiding/batch-voidTableau de passesInvalide ou active plusieurs passIds en une seule requête (request payload).
POST /api/v1/passes/voiding/template-voidModèle completInvalide en masse tous les passes actifs émis sous un même templateId (request payload).
GET /api/v1/passes/voiding/:id/voiding-historyJournal d'auditRetourne la chronologie des événements d'invalidation et réactivation du passe.

Exemple : Invalider un passe unique (request payload)

POST /api/v1/passes/voiding/pass_01j8k9m2n3p4q5r6/void En-têtes : X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "voided": true,
  "options": {
    "reason": "CANCELLED",
    "customReason": "Order refunded via Shopify webhook #SH-99412",
    "sendPushNotification": true,
    "pushNotificationMessage": "This pass has been voided following your order refund.",
    "updateGoogleWallet": true
  }
}

Statut HTTP : Retourne 204 No Content en cas de succès, positionnant immédiatement status = "VOIDED", lifecycleStatus = "VOIDED" et mettant à jour walletVoidStatus (WalletPropagationStatus : NONE -> PENDING -> QUEUED -> SUCCEEDED) au fil des envois Wallet en arrière-plan.

Exemple : Invalider plusieurs passes par lot (request payload)

POST /api/v1/passes/voiding/batch-void En-têtes : X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "passIds": [
    "pass_01j8k9m2n3p4q5r6",
    "pass_01j8k9m2n3p4q5r7"
  ],
  "voided": true,
  "options": {
    "reason": "EXPIRED",
    "customReason": "Expired seasonal VIP cohort",
    "sendPushNotification": true
  }
}

Exemple : Invalider tous les passes d'un modèle (request payload)

POST /api/v1/passes/voiding/template-void En-têtes : X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "templateId": "tmpl_01hxyz987654321",
  "voided": true,
  "options": {
    "reason": "CANCELLED",
    "customReason": "Summer 2026 promotional campaign concluded",
    "sendPushNotification": true
  }
}

Consultez Opérations en masse pour l'activation, la désactivation et la suppression par tableau, ou Passes actifs & limites d'utilisation pour les règles de décompte de capacité.

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.