Skip to content
Guida del Centro assistenza · Gestione passFase di onboarding 4
6 min di letturaVerificato 2026-11-16

Ciclo di vita e stati del pass

Comprendi gli stati Creato, Non installato, Installato, Scaduto e Annullato con impatti su fatturazione e scan.

In questa guida

Guide visive interattive UI

Apri nella guida in 6 fasi

Esplora schermate reali della dashboard e dettagli ingranditi collegati a questa guida.

Focus UI ingrandito
Elementi chiave dell'interfaccia

Popover stato di registrazione Wallet dal vivo (Zoom)

Clicca sul badge Apple Wallet o Google Wallet su qualsiasi riga per verificare registrazioni attive, rimozioni e cronologia di installazione.

Panoramica

Passinstance gestisce ogni pass emesso attraverso tre macchine a stati ortogonali tracciate sul modello Pass:

  1. 1
    pass status (11 valori): Stato funzionale di validità applicativa che stabilisce se un pass può essere installato, scansionato o riscattato.
  2. 2
    PassLifecycleStatus (5 stadi): Progressione amministrativa di conservazione e revoca da ACTIVE a DELETED.
  3. 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

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
CICLO DI VITA PASS E PROPAGAZIONE WALLET
FASE 01
1
STATO APPLICATIVO (pass status) [DRAFT] / [AWAITING_OPT_IN] / [PENDING_ACTIVATION]
[GENERATING][ACTIVE] <[INACTIVE] / [SUSPENDED] [REDEEMED] [EXPIRED] [CANCELLED] / [VOIDED]
FASE 02
2
PROGRESSIONE CICLO DI VITA (PassLifecycleStatus) [ACTIVE][VOIDING][VOIDED][DELETING][DELETED]
FASE 03
3
PIPELINE SYNC CLOUD (WalletPropagationStatus) [NONE][PENDING][QUEUED][SUCCEEDED] (o [FAILED] + Retry)

1. Tutti gli 11 stati applicativi di pass status

Valore pass statusRisultato validazione ScannerRendering visivo e comportamento nel Wallet
DRAFTRifiutato (INVALID)Il record del pass esiste nel DB prima della firma; il link di download non è ancora attivo.
AWAITING_OPT_INRifiutato (PENDING)Creato tramite PassFlow o campagna; in attesa di OTP via e-mail/SMS o conferma del consenso GDPR.
PENDING_ACTIVATIONRifiutato (PENDING)Pass emesso in attesa della cattura di un pagamento esterno o di una scansione di attivazione al POS.
GENERATINGRifiutato (PENDING)Il bundle crittografico .pkpass o l'oggetto Google Wallet è attualmente in compilazione presso un worker.
ACTIVEAccettato (SUCCESS)Pass valido e attivo, idoneo per scansioni, accumulo punti, tap NFC e notifiche push.
INACTIVERifiutato (INVALID)Temporaneamente disattivato dall'operatore (POST /api/v1/batch-pass-operations/deactivate).
SUSPENDEDRifiutato (INVALID)Sospeso per sospetta frode, insoluto nei pagamenti o blocco di sicurezza; reversibile a ACTIVE.
REDEEMEDRifiutato (ALREADY_USED)Coupon monouso o biglietto evento già scansionato e consumato (VOIDED_AFTER_SCAN scan mode).
EXPIREDRifiutato (EXPIRED)Il timestamp corrente ha superato Pass.expirationDate; il codice a barre appare oscurato sul dispositivo del cliente.
CANCELLEDRifiutato (ALREADY_VOIDED)Iscrizione o ordine annullato (ad esempio ordine biglietto rimborsato) prima del riscatto.
VOIDEDRifiutato (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:

StadioDescrizione
ACTIVEStato operativo normale valido per pass attivi, inattivi o scaduti.
VOIDINGLock transitorio acquisito all'avvio di una richiesta di annullamento; accoda aggiornamenti push ad alta priorità verso Apple e Google Wallet.
VOIDEDRevoca terminale completata; timestamp voidedAt e motivazione voidReason sono registrati permanentemente sul ledger del pass.
DELETINGLock transitorio acquisito quando un operatore richiede l'eliminazione permanente del record; revoca i token di download e scollega gli asset di storage.
DELETEDStato 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
NONEIl pass è appena stato creato oppure nessuna propagazione di stato/annullamento è stata accodata.
PENDINGUn 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.
QUEUEDUn 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.
SUCCEEDEDTutti 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/...).
FAILEDLa 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/:id esegue un'eliminazione SOFT (imposta archivedAt, liberando il vincolo di univocità (customerId, externalId) per la riemissione pur conservando i log di audit), mentre DELETE /api/v1/passes/:id/hard esegue una rimozione definitiva HARD.
  • ArtifactStatus (appleArtifactStatus, googleArtifactStatus): NOT_GENERATED | GENERATING | READY | FAILED | INVALIDATED traccia 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: true non 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):

EndpointAmbitoDescrizione
POST /api/v1/passes/:id/deactivateSingolo passPorta temporaneamente lo stato del pass da ACTIVE a INACTIVE.
POST /api/v1/passes/voiding/:id/voidSingolo passAnnulla (voided: true) o riattiva (voided: false) un singolo pass (204 No Content).
POST /api/v1/passes/voiding/batch-voidArray di passAnnulla o attiva più passIds in un'unica richiesta (request payload).
POST /api/v1/passes/voiding/template-voidIntero modelloAnnulla in blocco tutti i pass attivi emessi sotto un templateId (request payload).
GET /api/v1/passes/voiding/:id/voiding-historyStorico di auditRestituisce 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

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 Content in caso di successo, impostando immediatamente status = "VOIDED", lifecycleStatus = "VOIDED" e aggiornando walletVoidStatus (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

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

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à.

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.