Overzicht
Passinstance beheert elke uitgegeven pas via drie orthogonale toestandsmachines die worden bijgehouden op het Pass-model:
-
1
pass status (11 waarden): Functionele geldigheidsstatus die bepaalt of een pas kan worden geïnstalleerd, gescand of ingewisseld.
-
2
PassLifecycleStatus(5 fasen): Administratief retentie- en intrekkingsverloop vanACTIVEnaarDELETED. -
3
WalletPropagationStatus(5 fasen): Asynchrone status voor cloudsynchronisatie die APNs- en Google Wallet-pushlevering volgt.
Systeemarchitectuur: toestandsmachines voor paslevenscyclus & wallet-propagatie
1. Alle 11 zakelijke statussen van pass status
| Waarde in pass status | Resultaat van scannervalidatie | Visuele wallet-weergave & gedrag |
|---|---|---|
DRAFT | Geweigerd (INVALID) | Pasrecord bestaat in database vóór ondertekening; downloadlink is nog niet actief. |
AWAITING_OPT_IN | Geweigerd (PENDING) | Aangemaakt via PassFlow of campagne; wacht op e-mail-/sms-OTP of AVG-toestemming. |
PENDING_ACTIVATION | Geweigerd (PENDING) | Uitgegeven pas die wacht op externe betaling of activeringsscan aan de kassa. |
GENERATING | Geweigerd (PENDING) | Cryptografische .pkpass-bundel of Google Wallet-object wordt momenteel door een worker gecompileerd. |
ACTIVE | Geaccepteerd (SUCCESS) | Geldige, actieve pas die geschikt is voor scannen, puntenopbouw, NFC-tikken en pushmeldingen. |
INACTIVE | Geweigerd (INVALID) | Tijdelijk gedeactiveerd door een beheerder (POST /api/v1/batch-pass-operations/deactivate). |
SUSPENDED | Geweigerd (INVALID) | Bevroren wegens vermoedelijke fraude, betalingsachterstand of beveiligingsblokkade; terug te draaien naar ACTIVE. |
REDEEMED | Geweigerd (ALREADY_USED) | Eenmalige kortingsbon of evenementticket is gescand en verbruikt (VOIDED_AFTER_SCAN scan mode). |
EXPIRED | Geweigerd (EXPIRED) | Het huidige tijdstip ligt na Pass.expirationDate; de barcode wordt grijs weergegeven op het klantapparaat. |
CANCELLED | Geweigerd (ALREADY_VOIDED) | Inschrijving of bestelling is geannuleerd (bijv. terugbetaalde ticketbestelling) vóór inwisseling. |
VOIDED | Geweigerd (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:
| Fase | Beschrijving |
|---|---|
ACTIVE | Normale operationele status voor actieve, inactieve of verlopen passen. |
VOIDING | Overgangsvergrendeling bij het starten van een ongeldigverklaring; plaatst pushupdates met hoge prioriteit voor Apple en Google Wallet in de wachtrij. |
VOIDED | Definitieve intrekking voltooid; het tijdstempel voidedAt en voidReason worden permanent vastgelegd in het pasgrootboek. |
DELETING | Overgangsvergrendeling wanneer een beheerder permanente recordverwijdering aanvraagt; trekt downloadtokens in en ontkoppelt opslagassets. |
DELETED | Zacht 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 |
|---|---|
NONE | De pas is aangemaakt of er is geen ongeldigmaking/propagatie in de wachtrij geplaatst. |
PENDING | Een veld update of levenscyclustransitie is opgeslagen in database en wacht om te worden opgepikt door de propagatie-dispatcher. |
QUEUED | Een background job queue wallet-synctaak staat actief in de wachtrij om het APNs HTTP/2-pushbericht of Google Wallet PATCH-verzoek te verzenden. |
SUCCEEDED | Alle geregistreerde apparaten/cloudobjecten hebben de update bevestigd (voor Apple Wallet heeft het apparaat de nieuwste .pkpass-bundel opgehaald via GET /v1/passes/...). |
FAILED | De 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/:idvoert eenSOFTdelete uit (zetarchivedAten geeft de tenant-unieke(customerId, externalId)weer vrij voor heruitgifte met behoud van auditlogboeken), terwijlDELETE /api/v1/passes/:id/hardeen permanenteHARDopschoning uitvoert. -
ArtifactStatus(appleArtifactStatus,googleArtifactStatus):NOT_GENERATED | GENERATING | READY | FAILED | INVALIDATEDhoudt 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: trueop 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):
| Endpoint | Bereik | Beschrijving |
|---|---|---|
POST /api/v1/passes/:id/deactivate | Enkele pas | Zet de passtatus tijdelijk van ACTIVE naar INACTIVE. |
POST /api/v1/passes/voiding/:id/void | Enkele pas | Verklaart één pas ongeldig (voided: true) of heractiveert deze (voided: false) (204 No Content). |
POST /api/v1/passes/voiding/batch-void | Array van passen | Verklaart meerdere passIds ongeldig of activeert ze in één verzoek (request payload). |
POST /api/v1/passes/voiding/template-void | Volledig sjabloon | Verklaart alle actieve passen onder een templateId in één keer ongeldig (request payload). |
GET /api/v1/passes/voiding/:id/voiding-history | Auditspoor | Retourneert 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
{
"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 Contentbij succes, zet directstatus = "VOIDED",lifecycleStatus = "VOIDED"en werktwalletVoidStatusbij (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
{
"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
{
"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.
