Skip to content
Helpcentrum-gids · Pass-beheerOnboardingfase 4
5 min leestijdGecontroleerd 2026-11-16

Levenscyclus & statussen

Begrijp Aangemaakt, Niet geïnstalleerd, Geïnstalleerd, Verlopen en Ingetrokken plus het effect op facturering en scans.

In deze gids

Interactieve UI-weergaven

Openen in onboardinggids (6 fasen)

Bekijk de exacte dashboardpanelen, knoppen en ingezoomde toelichtingen bij deze gids.

Ingezoomde UI-focus
Belangrijke UI-onderdelen

Live popover voor Wallet-registratiestatus (Ingesneden)

Klik op de Apple Wallet- of Google Wallet-badge in een pasrij om actieve registraties, verwijderingen en registratietijdstippen te verifiëren.

Overzicht

Passinstance beheert elke uitgegeven pas via drie orthogonale toestandsmachines die worden bijgehouden op het Pass-model:

  1. 1
    pass status (11 waarden): Functionele geldigheidsstatus die bepaalt of een pas kan worden geïnstalleerd, gescand of ingewisseld.
  2. 2
    PassLifecycleStatus (5 fasen): Administratief retentie- en intrekkingsverloop van ACTIVE naar DELETED.
  3. 3
    WalletPropagationStatus (5 fasen): Asynchrone status voor cloudsynchronisatie die APNs- en Google Wallet-pushlevering volgt.

Systeemarchitectuur: toestandsmachines voor paslevenscyclus & wallet-propagatie

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
TOESTANDSMACHINE VOOR PASLEVENSCYCLUS & WALLET-PROPAGATIE
FASE 01
1
ZAKELIJKE STATUS (pass status) [DRAFT] / [AWAITING_OPT_IN] / [PENDING_ACTIVATION]
[GENERATING][ACTIVE] <[INACTIVE] / [SUSPENDED] [REDEEMED] [EXPIRED] [CANCELLED] / [VOIDED]
FASE 02
2
LEVENSCYCLUSVERLOOP (PassLifecycleStatus) [ACTIVE][VOIDING][VOIDED][DELETING][DELETED]
FASE 03
3
CLOUDSYNC-PIPELINE (WalletPropagationStatus) [NONE][PENDING][QUEUED][SUCCEEDED] (of [FAILED] + herpoging)

1. Alle 11 zakelijke statussen van pass status

Waarde in pass statusResultaat van scannervalidatieVisuele wallet-weergave & gedrag
DRAFTGeweigerd (INVALID)Pasrecord bestaat in database vóór ondertekening; downloadlink is nog niet actief.
AWAITING_OPT_INGeweigerd (PENDING)Aangemaakt via PassFlow of campagne; wacht op e-mail-/sms-OTP of AVG-toestemming.
PENDING_ACTIVATIONGeweigerd (PENDING)Uitgegeven pas die wacht op externe betaling of activeringsscan aan de kassa.
GENERATINGGeweigerd (PENDING)Cryptografische .pkpass-bundel of Google Wallet-object wordt momenteel door een worker gecompileerd.
ACTIVEGeaccepteerd (SUCCESS)Geldige, actieve pas die geschikt is voor scannen, puntenopbouw, NFC-tikken en pushmeldingen.
INACTIVEGeweigerd (INVALID)Tijdelijk gedeactiveerd door een beheerder (POST /api/v1/batch-pass-operations/deactivate).
SUSPENDEDGeweigerd (INVALID)Bevroren wegens vermoedelijke fraude, betalingsachterstand of beveiligingsblokkade; terug te draaien naar ACTIVE.
REDEEMEDGeweigerd (ALREADY_USED)Eenmalige kortingsbon of evenementticket is gescand en verbruikt (VOIDED_AFTER_SCAN scan mode).
EXPIREDGeweigerd (EXPIRED)Het huidige tijdstip ligt na Pass.expirationDate; de barcode wordt grijs weergegeven op het klantapparaat.
CANCELLEDGeweigerd (ALREADY_VOIDED)Inschrijving of bestelling is geannuleerd (bijv. terugbetaalde ticketbestelling) vóór inwisseling.
VOIDEDGeweigerd (ALREADY_VOIDED)Permanent ongeldig verklaard via Pass Voiding API; zet "voided": true in Apple pass.json en STATE_EXPIRED/INACTIVE in Google Wallet.

2. De 5 fasen van PassLifecycleStatus

De kolom lifecycleStatus coördineert veilige intrekking in meerdere stappen en database-opschoning zonder verweesde wallet-objecten op gebruikersapparaten achter te laten:

FaseBeschrijving
ACTIVENormale operationele status voor actieve, inactieve of verlopen passen.
VOIDINGOvergangsvergrendeling bij het starten van een ongeldigverklaring; plaatst pushupdates met hoge prioriteit voor Apple en Google Wallet in de wachtrij.
VOIDEDDefinitieve intrekking voltooid; het tijdstempel voidedAt en voidReason worden permanent vastgelegd in het pasgrootboek.
DELETINGOvergangsvergrendeling wanneer een beheerder permanente recordverwijdering aanvraagt; trekt downloadtokens in en ontkoppelt opslagassets.
DELETEDZacht verwijderde markeerstatus (tombstone) of definitieve verwijdering voorafgaand aan AVG-opschoning.

3. walletVoidStatus (WalletPropagationStatus), verwijdermodi & artefacten

Passinstance volgt asynchrone cloud-pushbezorging, verwijdersemantiek en compilatie van wallet-artefacten met specifieke Passinstance database-kolommen en enums op Pass:

walletVoidStatus (WalletPropagationStatus)

Telkens wanneer een ongeldigmaking of statusovergang naar Apple APNs of Google Wallet wordt verzonden, volgt Pass.walletVoidStatus de bezorgingsvoortgang:

Fase (WalletPropagationStatus)Beschrijving
NONEDe pas is aangemaakt of er is geen ongeldigmaking/propagatie in de wachtrij geplaatst.
PENDINGEen veld update of levenscyclustransitie is opgeslagen in database en wacht om te worden opgepikt door de propagatie-dispatcher.
QUEUEDEen background job queue wallet-synctaak staat actief in de wachtrij om het APNs HTTP/2-pushbericht of Google Wallet PATCH-verzoek te verzenden.
SUCCEEDEDAlle geregistreerde apparaten/cloudobjecten hebben de update bevestigd (voor Apple Wallet heeft het apparaat de nieuwste .pkpass-bundel opgehaald via GET /v1/passes/...).
FAILEDDe bezorging is gestuit op een upstreamfout (bijv. afgemeld APNs-token of Google API-quotafout); komt in aanmerking voor automatische herpoging.

PassDeletionMode & ArtifactStatus

  • PassDeletionMode (SOFT | HARD): DELETE /api/v1/passes/:id voert een SOFT delete uit (zet archivedAt en geeft de tenant-unieke (customerId, externalId) weer vrij voor heruitgifte met behoud van auditlogboeken), terwijl DELETE /api/v1/passes/:id/hard een permanente HARD opschoning uitvoert.
  • ArtifactStatus (appleArtifactStatus, googleArtifactStatus): NOT_GENERATED | GENERATING | READY | FAILED | INVALIDATED houdt bij of het cryptografische pakket of cloudobject voor elk platform gecompileerd en actueel is.

Belangrijke facturatie- & wallet-levenscyclusinvariant

Belangrijk: Het ongeldig verklaren of laten verlopen van een pas blokkeert toekomstige scannervalidaties en markeert de kaart visueel als ongeldig/grijs in de wallet van de gebruiker, maar Apple iOS en Google Android staan servers van derden niet toe een pas zonder actie van de gebruiker geforceerd van het apparaat van een klant te verwijderen. In Apple Wallet onderdrukken ongeldig verklaarde passen toegangsschermmeldingen, tenzij updateVoidedExpiredPasses: true op het sjabloon is ingeschakeld. Een geïnstalleerde pas blijft meetellen als actieve apparaatregistratie totdat de klant de pas uit zijn wallet verwijdert of apparaatafmelding voltooid is.

API voor deactiveren & ongeldig verklaren van passen (Passes API / Pass Voiding API)

Passinstance biedt omkeerbare deactivering (POST /api/v1/passes/:id/deactivate) en formele endpoints voor ongeldigmaking onder /api/v1/passes/voiding (met ondersteuning voor VoidingReason: EXPIRED, CANCELLED, LOST, STOLEN, DUPLICATE, FRAUD, TECHNICAL_ISSUE, CUSTOMER_REQUEST, ADMIN_ACTION, SYSTEM_AUTO, OTHER):

EndpointBereikBeschrijving
POST /api/v1/passes/:id/deactivateEnkele pasZet de passtatus tijdelijk van ACTIVE naar INACTIVE.
POST /api/v1/passes/voiding/:id/voidEnkele pasVerklaart één pas ongeldig (voided: true) of heractiveert deze (voided: false) (204 No Content).
POST /api/v1/passes/voiding/batch-voidArray van passenVerklaart meerdere passIds ongeldig of activeert ze in één verzoek (request payload).
POST /api/v1/passes/voiding/template-voidVolledig sjabloonVerklaart alle actieve passen onder een templateId in één keer ongeldig (request payload).
GET /api/v1/passes/voiding/:id/voiding-historyAuditspoorRetourneert chronologische ongeldigmakings- en activeringsgebeurtenissen voor de pas.

Voorbeeld: een enkele pas ongeldig verklaren (request payload)

POST /api/v1/passes/voiding/pass_01j8k9m2n3p4q5r6/void Headers: 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
  }
}

HTTP-status: Retourneert 204 No Content bij succes, zet direct status = "VOIDED", lifecycleStatus = "VOIDED" en werkt walletVoidStatus bij (WalletPropagationStatus: NONE -> PENDING -> QUEUED -> SUCCEEDED) terwijl achtergrondpushes naar wallets worden verzonden.

Voorbeeld: meerdere passen in batch ongeldig verklaren (request payload)

POST /api/v1/passes/voiding/batch-void Headers: 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
  }
}

Voorbeeld: alle passen voor een sjabloon ongeldig verklaren (request payload)

POST /api/v1/passes/voiding/template-void Headers: 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
  }
}

Bekijk Bulkacties voor array-gebaseerde activering, deactivering en verwijdering, of Actieve passen & gebruikslimieten voor regels rond capaciteitsmeting.

Klaar om uw eerste kaartprogramma te lanceren?

Maak uw workspace aan, configureer uw sjabloon en test een echte kaart in Apple Wallet en Google Wallet voordat u opschaalt.