Aperçu
Passinstance pilote chaque carte émise à travers trois automates d'état orthogonaux portés par le modèle Pass :
-
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
PassLifecycleStatus(5 étapes) : Progression administrative de rétention et révocation depuisACTIVEjusqu'àDELETED. -
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
1. Les 11 états métier de pass status
| Valeur pass status | Résultat validation scanner | Rendu visuel Wallet & comportement |
|---|---|---|
DRAFT | Rejeté (INVALID) | L'enregistrement existe en base avant signature ; le lien de téléchargement n'est pas actif. |
AWAITING_OPT_IN | Rejeté (PENDING) | Créé via PassFlow ou campagne ; en attente de code OTP e-mail/SMS ou consentement RGPD. |
PENDING_ACTIVATION | Rejeté (PENDING) | Carte émise en attente de capture de paiement externe ou scan d'activation en caisse. |
GENERATING | Rejeté (PENDING) | Le bundle cryptographique .pkpass ou l'objet Google Wallet est en cours de compilation par un worker. |
ACTIVE | Accepté (SUCCESS) | Carte active et valide éligible au scan, cumul de points, passage NFC et notifications push. |
INACTIVE | Rejeté (INVALID) | Désactivé temporairement par l'opérateur (POST /api/v1/batch-pass-operations/deactivate). |
SUSPENDED | Rejeté (INVALID) | Gelé pour suspicion de fraude, impayé ou blocage de sécurité ; réversible vers ACTIVE. |
REDEEMED | Rejeté (ALREADY_USED) | Coupon ou billet à usage unique déjà scanné et consommé (VOIDED_AFTER_SCAN scan mode). |
EXPIRED | Rejeté (EXPIRED) | L'horodatage courant a dépassé Pass.expirationDate ; le code-barres s'affiche grisé sur le téléphone. |
CANCELLED | Rejeté (ALREADY_VOIDED) | L'inscription ou la commande a été annulée (ex. billet remboursé) avant utilisation. |
VOIDED | Rejeté (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 :
| Étape | Description |
|---|---|
ACTIVE | État opérationnel normal couvrant les cartes actives, inactives ou expirées. |
VOIDING | Verrou transitoire acquis dès l'envoi d'une demande d'invalidation ; met en file les mises à jour push prioritaires Apple et Google Wallet. |
VOIDED | Révocation terminale achevée ; l'horodatage voidedAt et le motif voidReason sont inscrits définitivement dans le registre. |
DELETING | Verrou 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 |
|---|---|
NONE | La carte vient d'être créée ou aucune propagation d'invalidation n'a encore été mise en file. |
PENDING | Une mise à jour de champ ou transition de cycle a été validée dans database et attend le répartiteur de propagation. |
QUEUED | Une tâche background job queue est activement en file pour transmettre la notification HTTP/2 APNs ou le PATCH Google Wallet. |
SUCCEEDED | Tous 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/...). |
FAILED | La 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/:idapplique une suppression logiqueSOFT(renseignearchivedAtet libère immédiatement l'unicité(customerId, externalId)pour réémission tout en conservant les journaux d'audit), alors queDELETE /api/v1/passes/:id/hardexécute une purgeHARD. -
ArtifactStatus(appleArtifactStatus,googleArtifactStatus) :NOT_GENERATED | GENERATING | READY | FAILED | INVALIDATEDindique 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: trueest 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) :
| Endpoint | Portée | Description |
|---|---|---|
POST /api/v1/passes/:id/deactivate | Passe unique | Fait passer temporairement le passe de ACTIVE à INACTIVE. |
POST /api/v1/passes/voiding/:id/void | Passe unique | Invalide (voided: true) ou réactive (voided: false) un passe unique (204 No Content). |
POST /api/v1/passes/voiding/batch-void | Tableau de passes | Invalide ou active plusieurs passIds en une seule requête (request payload). |
POST /api/v1/passes/voiding/template-void | Modèle complet | Invalide en masse tous les passes actifs émis sous un même templateId (request payload). |
GET /api/v1/passes/voiding/:id/voiding-history | Journal d'audit | Retourne 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
{
"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 Contenten cas de succès, positionnant immédiatementstatus = "VOIDED",lifecycleStatus = "VOIDED"et mettant à jourwalletVoidStatus(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
{
"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
{
"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é.
