Skip to content
Hilfecenter-Anleitung · Einführung in PassinstanceOnboarding-Phase 2
5 Min. LesezeitGeprüft 2026-11-16

Wichtige Begriffe & Konzepte

Klare Definitionen für Vorlagen, Pässe, Mechaniken, Attribute, Wallet Experiences (Projekte), PassFlow und aktive Registrierungen.

In dieser Anleitung

Prüfen Sie passende Dashboard-Bereiche, Steuerelemente und Zoom-Hinweise zu diesem Thema.

Vergrößerter UI-Fokus
Wichtige UI-Elemente

Benutzerdefinierte Eigenschaften & Attribute (Zoom)

Definieren Sie wiederverwendbare Kundenattribute ({serviceOrDuration}, {holderName}, {passReference}, {validUntil}, {memberQrToken}) sowie Datentypen und Pflichtfelder.

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.

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
ENTITÄTSBEZIEHUNGEN
STUFE 01 Template (Bauplan & Versionierung)
Layout: StoreCard, EventTicket, Coupon, Membership
Farben, Barcode-Symbologie, Feld-Mapping, Bild-Slots
STUFE 02 1:N Ausgabe | 1:1 Regelverknüpfung
Pass (Konkrete Instanz)
SerialNumber & AuthToken
Dynamische Feldwerte
Status & ExpirationDate
1:N Geräteregistrierung (Apple A
pass mechanic (Zustands-Engine)
Typ: STAMP_CARD_ADD, LOYALTY_PROGRAM, PREPAID_CARD,
VALID_ONCE_PER_DAY
Saves)

Backend-Entitätsschema & Passinstance database-Modell-Mapping

Jedes Plattformkonzept entspricht direkt einer strukturierten Passinstance database-Entität in der Datenbankschicht von Passinstance API:

KonzeptPassinstance database-ModellAufgaben & gespeicherte Attribute
Vorlage (Template)TemplateSpeichert 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).
PassPassReprä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-Mechanikpass mechanicKonfiguriert zustandsbehaftete Regeln auf Vorlagenebene. Speichert mechanicType (mechanic type), minimumValue, maximumValue, defaultChangeValue, Stufen (PassTier) und Regeln für Ober-/Untergrenzen.
Prepaid-Kontoprepaid accountVerwaltet 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ündelpass bundleGruppiert bis zu 10 zusammengehörige Pässe über Pass.bundleId (bundle grouping mode: `AUTO \MANUAL, BundleStatus: ACTIVE \CANCELLED) zum Download mehrteiliger .pkpasses`-Archive.
Wallet ExperiencePassProjectOrchestriert eine Hauptvorlage (mainTemplateId) und verknüpfte Vorlagen (PassProjectTemplateRole: `PRIMARY \LINKED \PRIVACY_MODE \INACTIVE \VIP \CUSTOM`), einheitliche Abrufseiten, Bundles, Segmente und visuelle Automatisierungsflüsse.
PassFlowPassFlowSteuert 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-KonfigurationScannerConfigurationKonfiguriert 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:

FeldPassinstance database-Spalte / ScopeÄnderbarkeit & FormatHauptzweck
idUUID-PrimärschlüsselSystemgeneriert, unveränderlichInterne API-Ressourcenreferenz (GET /api/v1/passes/:id).
serialNumberGlobal eindeutige ZeichenketteSystemgeneriert (oder bei Konfiguration benutzerdefiniert), unveränderlichKanonischer Apple-Wallet-.pkpass-Identifikator und Suffix für Google-Objekte.
externalId@unique([customerId, externalId]) bei archivedAt IS NULLVom 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.
bundleIdbundleId (UUID-Fremdschlüssel auf pass bundle)Systemverwaltet über /api/v1/bundles/* oder PassProjectGruppiert 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 / authenticationTokenPass-bezogene SicherheitstokensSystemgenerierte kryptografische ZeichenkettenKurzer ö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: expirationDate ist überschritten; Scanner lehnen mit dem Grund PASS_EXPIRED ab.
  • 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 mit PASS_VOIDED ab.

Pass-Lebenszyklus, Löschmodus & Artefaktbereitschaft

  • PassLifecycleStatus: Steuert unumkehrbare Entwertungs- und Bereinigungsübergänge:
TEXT
ACTIVE  --->  VOIDING  --->  VOIDED  --->  DELETING  --->  DELETED
  • PassDeletionMode: Unterscheidet zwischen Soft-Delete (SOFT — erhält die Prüfhistorie und gibt die externalId-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-PATCH bestä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.

Bereit für Ihr erstes Wallet-Kartenprogramm?

Erstellen Sie Ihren Workspace, konfigurieren Sie Ihre Vorlage und testen Sie eine echte Karte in Apple Wallet und Google Wallet, bevor Sie skalieren.