Workspace-Status & Live-Telemetrie
Jedes Passinstance-Konto arbeitet in einem strikt getrennten Mandanten-Workspace. Alle innerhalb eines Workspaces erstellten Ressourcen — darunter visuelle Vorlagen, kryptografische Signaturzertifikate, benutzerdefinierte Eigenschaften, Kunden-Pass-Datensätze, API-Secrets und die POS-Scan-Historie — sind an Ihre Workspace-ID (customerId) gebunden und vollständig von anderen Organisationen isoliert.

Mandantenfähige Architektur & Workspace-Hierarchie
Passinstance setzt eine zweistufige Organisationshierarchie um, die die zentrale Abrechnungssteuerung vom täglichen Pass-Betrieb trennt:
Verwaltung von Schwester-Workspaces über die Organization-API
Teams, die mehrere Marken, Kundenkonten oder Sandbox-Umgebungen verwalten, können direkt mit dem Organizations API arbeiten:
| Endpunkt-Pfad | Methode | Auth | Funktion | |
|---|---|---|---|---|
/api/v1/organizations/current | GET | Bearer | Gibt die aktive Organisation, Mitgliederrollen und die Liste erreichbarer Schwester-Workspaces zurück. | |
/api/v1/organizations/current/billing-summary | GET | Bearer | Zusammenfassung der Tariflimits und der kumulierten aktiven Pass-Zahlen über alle Workspaces hinweg. | |
/api/v1/organizations/current/workspaces | POST | Bearer | Erstellt einen neuen Schwester-Workspace (`kind: "production" \ | "sandbox"`). |
/api/v1/organizations/current/workspaces/switch | POST | Bearer | Wechselt den aktiven Mandantenkontext und rotiert die Auth-Session-Cookies. |
Taxonomie der zentralen Telemetrie-Metriken
Für ein präzises Monitoring Ihres Pass-Programms unterscheidet Passinstance zwischen der serverseitigen Datensatzerstellung und der physischen Wallet-Installation:
Pass erstellt (POST /api/v1/passes) ===============> unclaimedPasses (Nicht installiert)
|
| Kundin/Kunde fügt zu Wallet hinzu
v
Gerät registriert (POST /v1/devices/...) ===========> installedDevices (Installiert)
|
| Kundin/Kunde löscht aus Wallet
v
Gerät deregistriert (DELETE /v1/devices/...) =======> inactivePasses / inactiveDeviceRegistrations
Definitionen aus metric-definitions.ts
-
totalPasses(Total Passes Issued): Kumulative Anzahl aller aktiven Pass-Datensätze in Ihrem Workspace, die zum Zeitpunkt des Snapshots nicht gelöscht wurden. -
activePasses(Active Passes): Aktive Pass-Instanzen, für die derzeit mindestens eine erreichbare Geräteregistrierung vorliegt (ausgenommen abgelaufene und entwertete Pässe). -
installedDevices(Active Device Registrations): Erreichbare gespeicherte Pass-Registrierungen über Apple APNs und Google Wallet hinweg. Ist ein Pass auf zwei Geräten gespeichert, zählt dies als zwei aktive Registrierungen und wird auf das Tarifkontingent angerechnet. -
unclaimedPasses(Unclaimed Passes): In Passinstance ausgegebene Pass-Instanzen, die noch nie in einem Wallet gespeichert wurden. -
inactivePasses(Removed Passes): Pass-Instanzen, die zuvor in einem Wallet gespeichert waren, aber keine erreichbaren Geräteregistrierungen mehr besitzen (einschließlich Apple-DELETE /v1/devices/...und Google-del-Callbacks an/api/v1/wallet/callback). -
voidedPasses(Voided Passes) &expiredPasses(Expired Passes): Serverseitig entwertete Pass-Instanzen bzw. Pässe nach Überschreiten vonexpirationDate.
Workspace-Einstellungen & regionale Konfiguration
Jeder Workspace wird unabhängig unter Einstellungen -> Workspace (/settings/workspace/*) konfiguriert:
-
Allgemeine & regionale Einstellungen (
PUT /api/v1/customer/:customerId/regional-settings): Konfiguriert die Standardzeitzone (resolveCustomerTimeZone), den ISO-4217-Standardwährungscode und die Standardsprache. -
Nutzungskontingente (
GET /api/v1/customer/:customerId/usage-summary): Meldet in Echtzeit die Gesamtzahl der Pässe, aktive Pässe im Vergleich zumaxActivePassessowie die Vorlagenanzahl. -
Whitelabel-Vanity-Domains (
/api/v1/white-labeling/vanity-urls): Verbindet eigene Domains (domain surface type:PASS_DOWNLOAD,PASS_FLOW,BACKEND_UIusw.) inklusive automatischer SSL-Bereitstellung für alle Smart-Links und Download-Seiten.
Wichtig: Sandbox-Workspaces bieten eine isolierte Umgebung zum Testen von Vorlagenrevisionen, API-Webhooks und Scanner-Konfigurationen, ohne aktive Pass-Kapazität Ihres Produktivtarifs zu verbrauchen.
