Überblick
Passinstance steuert jeden ausgegebenen Pass über drei orthogonale Zustandsautomaten direkt auf dem Pass-Modell:
-
1
pass status (11 Werte): Fachlicher Gültigkeitsstatus, der bestimmt, ob ein Pass installiert, gescannt oder eingelöst werden kann.
-
2
PassLifecycleStatus(5 Phasen): Administrative Aufbewahrungs- und Widerrufsabfolge vonACTIVEbisDELETED. -
3
WalletPropagationStatus(5 Phasen): Asynchroner Cloud-Synchronisierungsstatus für die Zustellung von APNs- und Google-Wallet-Pushs.
Systemarchitektur: Pass-Lebenszyklus & Wallet-Propagation
1. Alle 11 fachlichen pass status-Zustände
| pass status-Wert | Ergebnis der Scanner-Prüfung | Visuelle Darstellung & Verhalten im Wallet |
|---|---|---|
DRAFT | Abgelehnt (INVALID) | Pass-Datensatz existiert vor Signierung in der DB; Download-Link ist noch nicht aktiv. |
AWAITING_OPT_IN | Abgelehnt (PENDING) | Über PassFlow oder Kampagne erstellt; wartet auf E-Mail-/SMS-OTP oder DSGVO-Einwilligung. |
PENDING_ACTIVATION | Abgelehnt (PENDING) | Ausgegebener Pass wartet auf externe Zahlungsbestätigung oder POS-Aktivierungsscan. |
GENERATING | Abgelehnt (PENDING) | Kryptografisches .pkpass-Paket oder Google-Wallet-Objekt wird gerade durch einen Worker kompiliert. |
ACTIVE | Akzeptiert (SUCCESS) | Gültiger Live-Pass, berechtigt für Scans, Punktegutschriften, NFC-Tap und Push-Mitteilungen. |
INACTIVE | Abgelehnt (INVALID) | Vorübergehend durch Administration deaktiviert (POST /api/v1/batch-pass-operations/deactivate). |
SUSPENDED | Abgelehnt (INVALID) | Eingefroren wegen Betrugsverdacht, Zahlungsrückstand oder Sicherheitssperre; wieder auf ACTIVE rücksetzbar. |
REDEEMED | Abgelehnt (ALREADY_USED) | Einmal-Coupon oder Event-Ticket wurde gescannt und verbraucht (VOIDED_AFTER_SCAN scan mode). |
EXPIRED | Abgelehnt (EXPIRED) | Aktueller Zeitstempel liegt hinter Pass.expirationDate; Barcode wird auf dem Kundengerät ausgegraut. |
CANCELLED | Abgelehnt (ALREADY_VOIDED) | Anmeldung oder Bestellung wurde vor Einlösung storniert (z. B. erstattetes Ticket). |
VOIDED | Abgelehnt (ALREADY_VOIDED) | Dauerhaft über Pass Voiding API entwertet; setzt "voided": true in Apple pass.json und STATE_EXPIRED/INACTIVE in Google Wallet. |
2. Die 5 PassLifecycleStatus-Phasen
Die Spalte lifecycleStatus koordiniert sichere mehrstufige Sperrungen und Datenbankbereinigungen, ohne verwaiste Wallet-Objekte auf Endgeräten zu hinterlassen:
| Phase | Beschreibung |
|---|---|
ACTIVE | Normaler Betriebszustand über aktive, inaktive oder abgelaufene Pässe hinweg. |
VOIDING | Übergangssperre bei Eingang einer Entwertungsanfrage; reiht priorisierte Entwertungs-Pushs an Apple und Google Wallet ein. |
VOIDED | Abschließender Widerruf abgeschlossen; Zeitstempel voidedAt und voidReason werden dauerhaft am Pass-Datensatz vermerkt. |
DELETING | Übergangssperre bei Anforderung dauerhafter Löschung; widerruft Download-Tokens und trennt Speicher-Assets. |
DELETED | Soft-Delete-Markierung oder abgeschlossene Löschung vor der DSGVO-Bereinigung. |
3. walletVoidStatus (WalletPropagationStatus), Löschmodi & Artefakte
Passinstance verfolgt asynchrone Cloud-Push-Auslieferung, Löschsemantik und Wallet-Artefakt-Kompilierung über eigene Passinstance database-Spalten und Enums auf Pass:
walletVoidStatus (WalletPropagationStatus)
Sobald ein Entwertungs- oder Statuswechsel an Apple APNs oder Google Wallet gesendet wird, dokumentiert Pass.walletVoidStatus den Auslieferungsfortschritt:
Phase (WalletPropagationStatus) | Beschreibung |
|---|---|
NONE | Pass wurde neu erstellt oder es steht kein Entwertungs-/Ausbreitungsvorgang in der Queue. |
PENDING | Eine Feldänderung oder ein Lebenszyklusübergang wurde in database festgeschrieben und wartet auf die Übergabe an den Dispatcher. |
QUEUED | Ein background job queue-Wallet-Sync-Job ist aktiv eingereiht, um den APNs-HTTP/2-Push bzw. die Google-Wallet-PATCH-Anfrage auszuführen. |
SUCCEEDED | Alle registrierten Geräte bzw. Cloud-Objekte haben das Update bestätigt (bei Apple Wallet hat das Gerät das aktuelle .pkpass-Paket über GET /v1/passes/... abgerufen). |
FAILED | Die Zustellung stieß auf einen Upstream-Fehler (z. B. abgemeldetes APNs-Token oder Google-API-Kontingentfehler); für erneute Versuche berechtigt. |
PassDeletionMode & ArtifactStatus
-
PassDeletionMode(SOFT|HARD):DELETE /api/v1/passes/:idführt einSOFT-Delete aus (setztarchivedAt, gibt die Mandanten-Eindeutigkeit(customerId, externalId)für Neuausgaben frei und bewahrt Audit-Logs), währendDELETE /api/v1/passes/:id/hardeine endgültigeHARD-Löschung durchführt. -
ArtifactStatus(appleArtifactStatus,googleArtifactStatus):NOT_GENERATED | GENERATING | READY | FAILED | INVALIDATEDzeigt an, ob das kryptografische Paket bzw. Cloud-Objekt je Plattform kompiliert und aktuell ist.
Wichtige Invariante für Abrechnung & Wallet-Lebenszyklus
Wichtig: Das Entwerten oder Ablaufenlassen eines Passes weist künftige Scanner-Prüfungen ab und kennzeichnet die Karte im Wallet des Nutzers visuell als ungültig/ausgegraut — Apple iOS und Google Android erlauben es Drittanbieter-Servern jedoch nicht, einen Pass ohne Zutun der Nutzerin oder des Nutzers zwangsweise vom Gerät zu löschen. In Apple Wallet unterdrücken entwertete Pässe Sperrbildschirm-Meldungen, sofern auf der Vorlage nicht
updateVoidedExpiredPasses: trueaktiviert ist. Ein installierter Pass zählt weiterhin als aktive Geräteregistrierung, bis die Kundin oder der Kunde ihn aus dem Wallet entfernt oder die Gerätederegistrierung abgeschlossen ist.
API für Deaktivierung & Entwertung (Passes API / Pass Voiding API)
Passinstance stellt sowohl eine umkehrbare Deaktivierung (POST /api/v1/passes/:id/deactivate) als auch formelle Entwertungs-Endpunkte unter /api/v1/passes/voiding bereit (akzeptiert VoidingReason: EXPIRED, CANCELLED, LOST, STOLEN, DUPLICATE, FRAUD, TECHNICAL_ISSUE, CUSTOMER_REQUEST, ADMIN_ACTION, SYSTEM_AUTO, OTHER):
| Endpunkt | Geltungsbereich | Beschreibung |
|---|---|---|
POST /api/v1/passes/:id/deactivate | Einzelner Pass | Setzt den Pass-Status vorübergehend von ACTIVE auf INACTIVE. |
POST /api/v1/passes/voiding/:id/void | Einzelner Pass | Entwertet (voided: true) oder reaktiviert (voided: false) einen einzelnen Pass (204 No Content). |
POST /api/v1/passes/voiding/batch-void | Array von Pässen | Entwertet oder reaktiviert mehrere passIds in einer Anfrage (request payload). |
POST /api/v1/passes/voiding/template-void | Gesamte Vorlage | Entwertet massenhaft alle aktiven Pässe unter einer templateId (request payload). |
GET /api/v1/passes/voiding/:id/voiding-history | Audit-Protokoll | Gibt chronologische Entwertungs- und Reaktivierungsereignisse für den Pass zurück. |
Beispiel: Einzelnen Pass entwerten (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
}
}
HTTP-Status: Gibt bei Erfolg
204 No Contentzurück, setzt umgehendstatus = "VOIDED"undlifecycleStatus = "VOIDED"und aktualisiertwalletVoidStatus(WalletPropagationStatus:NONE->PENDING->QUEUED->SUCCEEDED) während die Hintergrund-Pushs laufen.
Beispiel: Mehrere Pässe im Batch entwerten (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
}
}
Beispiel: Alle Pässe einer Vorlage entwerten (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
}
}
Lesen Sie Massenaktionen für Array-basierte Aktivierungs-, Deaktivierungs- und Löschabläufe oder Aktive Pässe & Nutzungslimits für Regeln zur Kapazitätsbemessung.
