Zentrale Plattformarchitektur & Entitäten
Um zuverlässige Wallet-Workflows aufzubauen, sollten Entwickler und Administratorinnen verstehen, wie Passinstance Vorlagen, dynamische Pass-Datensätze, Geschäftslogik-Mechaniken und Geräteregistrierungen strukturiert.
Backend-Entitätsschema & Passinstance database-Modell-Mapping
Jedes Plattformkonzept entspricht direkt einer strukturierten Passinstance database-Entität in der Datenbankschicht von Passinstance API:
| Konzept | Passinstance database-Modell | Aufgaben & gespeicherte Attribute | |||||
|---|---|---|---|---|---|---|---|
| Vorlage (Template) | Template | Speichert die visuelle Konfiguration, Layout-Art (pass type), Asset-Verknüpfungen (image asset slot), Barcode-Regeln, benutzerdefinierte ID-Regex-Muster und Single-Table-Versionierung (groupId, versionNumber, rowKind: `PRODUCTION \ | PUBLISHED \ | ARCHIVED \ | DRAFT, status`: template status). | ||
| Pass | Pass | Repräsentiert eine individuell ausgegebene Karte. Enthält id, eindeutige serialNumber, authenticationToken, downloadCode, optionale mandanteneindeutige externalId, optionale bundleId (bundleId), optionalen idempotencyKey, structured JSON-attributes, expirationDate, Artefaktstatus (appleArtifactStatus, googleArtifactStatus) sowie Lebenszyklus-/Storno-Flags. | |||||
| Pass-Mechanik | pass mechanic | Konfiguriert zustandsbehaftete Regeln auf Vorlagenebene. Speichert mechanicType (mechanic type), minimumValue, maximumValue, defaultChangeValue, Stufen (PassTier) und Regeln für Ober-/Untergrenzen. | |||||
| Prepaid-Konto | prepaid account | Verwaltet hinterlegtes Geldguthaben für Geschenk- und Prepaid-Karten. Führt Salden als Ganzzahlen in kleinster Einheit und verknüpft unveränderliche prepaid ledger entry-Buchungssätze. | |||||
| Pass-Bündel | pass bundle | Gruppiert bis zu 10 zusammengehörige Pässe über Pass.bundleId (bundle grouping mode: `AUTO \ | MANUAL, BundleStatus: ACTIVE \ | CANCELLED) zum Download mehrteiliger .pkpasses`-Archive. | |||
| Wallet Experience | PassProject | Orchestriert eine Hauptvorlage (mainTemplateId) und verknüpfte Vorlagen (PassProjectTemplateRole: `PRIMARY \ | LINKED \ | PRIVACY_MODE \ | INACTIVE \ | VIP \ | CUSTOM`), einheitliche Abrufseiten, Bundles, Segmente und visuelle Automatisierungsflüsse. |
| PassFlow | PassFlow | Steuert mehrstufige Self-Service-Aufnahmeseiten (/f/:url, PassFlowType, PassFlowStatus) mit konfigurierbaren Formularen, SMS-/E-Mail-OTP-Verifizierung, Bot-Schutz (SpamProtectionMode), Zahlungs-Gateways und direkter Wallet-Übergabe. | |||||
| Scanner-Konfiguration | ScannerConfiguration | Konfiguriert physische Einlass- und Kassenorte (ValidationPlace), berechtigungsbegrenzte ScannerKey-Tokens, Validierungsmodi (ScanMode), NFC-Reader-Einstellungen (NfcReaderMode) und Offline-Datensynchronisierung. |
Zentrale Pass-Identifikatoren & Korrelationsschlüssel
Bei der Integration von CRM-Systemen, E-Commerce-Checkouts oder Ticketing-Backends ist die genaue Rolle jedes Identifikators auf einem Pass entscheidend:
| Feld | Passinstance database-Spalte / Scope | Änderbarkeit & Format | Hauptzweck |
|---|---|---|---|
id | UUID-Primärschlüssel | Systemgeneriert, unveränderlich | Interne API-Ressourcenreferenz (GET /api/v1/passes/:id). |
serialNumber | Global eindeutige Zeichenkette | Systemgeneriert (oder bei Konfiguration benutzerdefiniert), unveränderlich | Kanonischer Apple-Wallet-.pkpass-Identifikator und Suffix für Google-Objekte. |
externalId | @unique([customerId, externalId]) bei archivedAt IS NULL | Vom Aufrufer gelieferter String (max. 255 Zeichen) | Fachlicher Schlüssel Ihres CRM-, POS- oder Ticketing-Systems für idempotentes POST /api/v1/passes/upsert-by-external-id und den Abruf über GET /api/v1/passes/by-external-id/:externalId. |
bundleId | bundleId (UUID-Fremdschlüssel auf pass bundle) | Systemverwaltet über /api/v1/bundles/* oder PassProject | Gruppiert bis zu 10 Pässe zu einem mehrteiligen .pkpasses-Apple-Bundle oder einer einheitlichen Claim-Experience. |
idempotencyKey | @unique([customerId, idempotencyKey]) | Übergeben per HTTP-Header Idempotency-Key (<=128 Zeichen [A-Za-z0-9._:-]+) | Verhindert doppelte Pass-Ausgaben bei Wiederholung einer POST /api/v1/passes-Anfrage; abgesichert über einen SHA-256-Hash des Request-Bodys. |
downloadCode / authenticationToken | Pass-bezogene Sicherheitstokens | Systemgenerierte kryptografische Zeichenketten | Kurzer öffentlicher Download-Code sowie Shared Secret für Apple Web Service Authorization: ApplePass <token>. |
Zustandsautomaten (Enums) & Lebenszyklus-Zuordnung
Pass-Datensätze durchlaufen bei Erstellung, Wallet-Synchronisierung und Entwertung/Löschung strikte Zustandsautomaten über mehrere Passinstance database-Enums:
Pass-Status (pass status)
-
DRAFT: Als noch nicht ausgegebener Entwurf angelegt und noch nicht öffentlich installierbar. -
AWAITING_OPT_IN: Im Rahmen eines Opt-in-/OTP-Registrierungsflusses erstellt; wartet vor der Aktivierung auf die Bestätigung. -
GENERATING: Durchläuft derzeit eine asynchrone Pass- oder Artefaktgenerierung. -
ACTIVE: Ausgegeben und gültig. Steht für die Wallet-Installation und die Scanner-Validierung bereit. -
INACTIVE: Vorübergehend pausiert bzw. deaktiviert; Scanner lehnen die Validierung bis zur Reaktivierung ab. -
EXPIRED:expirationDateist überschritten; Scanner lehnen mit dem GrundPASS_EXPIREDab. -
REDEEMED: Einmaliger Coupon oder Gutschein, der bereits eingelöst wurde. -
CANCELLED,SUSPENDED,PENDING_ACTIVATION: Spezielle Abrechnungs-, Verwaltungs- und Voraktivierungszustände. -
VOIDED: Durch Administration oder Scan-Regel widerrufen bzw. entwertet; Scanner lehnen mitPASS_VOIDEDab.
Pass-Lebenszyklus, Löschmodus & Artefaktbereitschaft
-
PassLifecycleStatus: Steuert unumkehrbare Entwertungs- und Bereinigungsübergänge:
ACTIVE ---> VOIDING ---> VOIDED ---> DELETING ---> DELETED
-
PassDeletionMode: Unterscheidet zwischen Soft-Delete (SOFT— erhält die Prüfhistorie und gibt dieexternalId-Eindeutigkeit für aktive Pässe frei) und dauerhafter Entfernung (HARD,DELETE /api/v1/passes/:id/hard). -
ArtifactStatus(appleArtifactStatus&googleArtifactStatus): Protokolliert den Generierungsstatus je Ökosystem (NOT_GENERATED,GENERATING,READY,FAILED,INVALIDATED).
Wallet-Storno- & Ausbreitungsstatus (walletVoidStatus / WalletPropagationStatus)
Verfolgt die asynchrone Weitergabe von Entwertungs- oder Aktualisierungszuständen an Apple APNs und Google Wallet im Feld Pass.walletVoidStatus:
-
NONE: Keine Weitergabe ausstehend. -
PENDING: Zustand in der Datenbank erfasst; wartet auf Einreihung in die Queue. -
QUEUED: An die background job queue-Wallet-Sync-Worker übergeben. -
SUCCEEDED: Apple-APNs-Wake-up oder Google-REST-PATCHbestätigt. -
FAILED: Downstream-Wallet-Push fehlgeschlagen (kann automatisch erneut versucht oder manuell neu angestoßen werden).
Benutzerdefinierte Eigenschaften & dynamische Token-Ersetzung
Passinstance nutzt die geschweifte Klammer-Syntax {propertyName}, um Kundendaten in Kartenfelder einzubinden:
-
Syntax: Platzieren Sie
{firstName},{pointsBalance}oder{membershipTier}in der Beschriftung oder dem Wert eines beliebigen Header-, Primary-, Secondary-, Auxiliary- oder Rückseitenfelds. -
Änderungsmeldungen (
changeMessage): Konfigurieren Sie z. B.changeMessage: "Sie haben einen Stempel erhalten! Aktueller Stand: %@ Stempel."auf Apple-Wallet-Feldern. Bei einer Aktualisierung wird der Platzhalter%@durch den neuen Wert ersetzt und erzeugt sofort eine native iOS-Sperrbildschirm-Meldung. -
Formatierte Werte (
attributedValue): Rückseitenfelder in Apple Wallet unterstützen HTML-Anchor-Tags (<a href="https://example.com">Nutzungsbedingungen</a>) für anklickbare Weblinks, Telefonnummern und E-Mail-Adressen.
Wichtig: Die Abrechnungskapazität bemisst aktive Wallet-Pässe (die Gesamtzahl der Geräte, die aktuell über Apple APNs oder Google-Wallet-Objekte registriert sind) — nicht unausgegebene Entwürfe oder abgelaufene Pässe.
