Panoramica
Passinstance gestisce ogni pass emesso attraverso tre macchine a stati ortogonali tracciate sul modello Pass:
-
1
pass status (11 valori): Stato funzionale di validità applicativa che stabilisce se un pass può essere installato, scansionato o riscattato.
-
2
PassLifecycleStatus(5 stadi): Progressione amministrativa di conservazione e revoca daACTIVEaDELETED. -
3
WalletPropagationStatus(5 stadi): Stato di sincronizzazione cloud asincrona che traccia la consegna push verso APNs e Google Wallet.
Architettura di sistema: macchine a stati di ciclo di vita e propagazione Wallet
1. Tutti gli 11 stati applicativi di pass status
| Valore pass status | Risultato validazione Scanner | Rendering visivo e comportamento nel Wallet |
|---|---|---|
DRAFT | Rifiutato (INVALID) | Il record del pass esiste nel DB prima della firma; il link di download non è ancora attivo. |
AWAITING_OPT_IN | Rifiutato (PENDING) | Creato tramite PassFlow o campagna; in attesa di OTP via e-mail/SMS o conferma del consenso GDPR. |
PENDING_ACTIVATION | Rifiutato (PENDING) | Pass emesso in attesa della cattura di un pagamento esterno o di una scansione di attivazione al POS. |
GENERATING | Rifiutato (PENDING) | Il bundle crittografico .pkpass o l'oggetto Google Wallet è attualmente in compilazione presso un worker. |
ACTIVE | Accettato (SUCCESS) | Pass valido e attivo, idoneo per scansioni, accumulo punti, tap NFC e notifiche push. |
INACTIVE | Rifiutato (INVALID) | Temporaneamente disattivato dall'operatore (POST /api/v1/batch-pass-operations/deactivate). |
SUSPENDED | Rifiutato (INVALID) | Sospeso per sospetta frode, insoluto nei pagamenti o blocco di sicurezza; reversibile a ACTIVE. |
REDEEMED | Rifiutato (ALREADY_USED) | Coupon monouso o biglietto evento già scansionato e consumato (VOIDED_AFTER_SCAN scan mode). |
EXPIRED | Rifiutato (EXPIRED) | Il timestamp corrente ha superato Pass.expirationDate; il codice a barre appare oscurato sul dispositivo del cliente. |
CANCELLED | Rifiutato (ALREADY_VOIDED) | Iscrizione o ordine annullato (ad esempio ordine biglietto rimborsato) prima del riscatto. |
VOIDED | Rifiutato (ALREADY_VOIDED) | Invalidato in modo permanente tramite Pass Voiding API; imposta "voided": true in pass.json Apple e STATE_EXPIRED/INACTIVE in Google Wallet. |
2. I 5 stadi di PassLifecycleStatus
La colonna lifecycleStatus coordina revoche in più passaggi e pulizia sicura dal database senza lasciare oggetti orfani nei Wallet dei dispositivi utente:
| Stadio | Descrizione |
|---|---|
ACTIVE | Stato operativo normale valido per pass attivi, inattivi o scaduti. |
VOIDING | Lock transitorio acquisito all'avvio di una richiesta di annullamento; accoda aggiornamenti push ad alta priorità verso Apple e Google Wallet. |
VOIDED | Revoca terminale completata; timestamp voidedAt e motivazione voidReason sono registrati permanentemente sul ledger del pass. |
DELETING | Lock transitorio acquisito quando un operatore richiede l'eliminazione permanente del record; revoca i token di download e scollega gli asset di storage. |
DELETED | Stato tombstone di eliminazione logica o rimozione finalizzata prima della cancellazione definitiva GDPR. |
3. walletVoidStatus (WalletPropagationStatus), modalità di eliminazione e artefatti
Passinstance traccia la consegna asincrona dei push cloud, la semantica di eliminazione e la compilazione degli artefatti Wallet tramite colonne ed enum Passinstance database dedicati su Pass:
walletVoidStatus (WalletPropagationStatus)
Ogni volta che una transizione di annullamento o di stato viene inviata ad Apple APNs o Google Wallet, Pass.walletVoidStatus traccia l'avanzamento della consegna:
Stadio (WalletPropagationStatus) | Descrizione |
|---|---|
NONE | Il pass è appena stato creato oppure nessuna propagazione di stato/annullamento è stata accodata. |
PENDING | Un aggiornamento di campo o una transizione del ciclo di vita è stata salvata su database ed è in attesa di essere presa in carico dal dispatcher di propagazione. |
QUEUED | Un job di sincronizzazione Wallet su background job queue è attualmente in coda per trasmettere il push HTTP/2 APNs o la richiesta PATCH a Google Wallet. |
SUCCEEDED | Tutti i dispositivi registrati e gli oggetti cloud hanno confermato l'aggiornamento (per Apple Wallet, il dispositivo ha scaricato l'ultimo bundle .pkpass tramite GET /v1/passes/...). |
FAILED | La consegna ha incontrato un errore upstream (es. token APNs non più registrato o quota API Google); idoneo al retry. |
PassDeletionMode e ArtifactStatus
-
PassDeletionMode(SOFT|HARD):DELETE /api/v1/passes/:idesegue un'eliminazioneSOFT(impostaarchivedAt, liberando il vincolo di univocità(customerId, externalId)per la riemissione pur conservando i log di audit), mentreDELETE /api/v1/passes/:id/hardesegue una rimozione definitivaHARD. -
ArtifactStatus(appleArtifactStatus,googleArtifactStatus):NOT_GENERATED | GENERATING | READY | FAILED | INVALIDATEDtraccia se il pacchetto crittografico / oggetto cloud di ciascuna piattaforma è compilato e aggiornato.
Invariante importante su fatturazione e ciclo di vita nel Wallet
Importante: Annullare o far scadere un pass blocca le future validazioni tramite scanner e contrassegna visivamente la tessera come non valida/oscurata nel Wallet dell'utente, ma Apple iOS e Google Android non consentono a server di terze parti di eliminare forzatamente un pass dal dispositivo del cliente senza un'azione dell'utente. In Apple Wallet, i pass annullati sopprimono gli aggiornamenti sulla schermata di blocco a meno che
updateVoidedExpiredPasses: truenon sia abilitato sul modello. Un pass installato continua a contare come registrazione dispositivo attiva finché il cliente non lo rimuove dal proprio Wallet o non si completa la deregistrazione del dispositivo.
API di disattivazione e annullamento pass (Passes API / Pass Voiding API)
Passinstance espone la disattivazione reversibile (POST /api/v1/passes/:id/deactivate) e gli endpoint formali di annullamento sotto /api/v1/passes/voiding (accettando VoidingReason: EXPIRED, CANCELLED, LOST, STOLEN, DUPLICATE, FRAUD, TECHNICAL_ISSUE, CUSTOMER_REQUEST, ADMIN_ACTION, SYSTEM_AUTO, OTHER):
| Endpoint | Ambito | Descrizione |
|---|---|---|
POST /api/v1/passes/:id/deactivate | Singolo pass | Porta temporaneamente lo stato del pass da ACTIVE a INACTIVE. |
POST /api/v1/passes/voiding/:id/void | Singolo pass | Annulla (voided: true) o riattiva (voided: false) un singolo pass (204 No Content). |
POST /api/v1/passes/voiding/batch-void | Array di pass | Annulla o attiva più passIds in un'unica richiesta (request payload). |
POST /api/v1/passes/voiding/template-void | Intero modello | Annulla in blocco tutti i pass attivi emessi sotto un templateId (request payload). |
GET /api/v1/passes/voiding/:id/voiding-history | Storico di audit | Restituisce in ordine cronologico gli eventi di annullamento/attivazione del pass. |
Esempio: annullare un singolo pass (request payload)
POST /api/v1/passes/voiding/pass_01j8k9m2n3p4q5r6/void Header: 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
}
}
Stato HTTP: Restituisce
204 No Contentin caso di successo, impostando immediatamentestatus = "VOIDED",lifecycleStatus = "VOIDED"e aggiornandowalletVoidStatus(WalletPropagationStatus:NONE->PENDING->QUEUED->SUCCEEDED) man mano che vengono eseguiti i push Wallet in background.
Esempio: annullamento batch di più pass (request payload)
POST /api/v1/passes/voiding/batch-void Header: 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
}
}
Esempio: annullare tutti i pass di un modello (request payload)
POST /api/v1/passes/voiding/template-void Header: 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
}
}
Consulti Operazioni di massa per i flussi basati su array di attivazione, disattivazione ed eliminazione, oppure Pass attivi e limiti di utilizzo per le regole di misurazione della capacità.
