Überblick
Wenn Ihr Unternehmen über saisonale Kampagnen, regionale Filialen sowie Staging- und Produktionsumgebungen hinweg wächst, stellt Passinstance mehrschichtige Werkzeuge für die Workspace-Organisation bereit: Kategorisierung & Tagging von Vorlagen, Vorlagen-Klonen (Template Duplication Wizard), rowKind-Lebenszyklusfilterung (DRAFT, PUBLISHED, PRODUCTION, ARCHIVED), zusammengesetzte External-ID-Eindeutigkeit, GIN-indizierte Datenbank-Attributsuche (attribute search index) sowie projektübergreifende Vorlagenzuordnung.
Systemarchitektur: Workspace-Taxonomie, Klonen & gespeicherte Ansichten
1. Eine Vorlage kopieren: Bestehende Vorlage duplizieren (Vorlagen-Klonen)
Statt Farben, Feldlayouts, Barcodes und Schemata für benutzerdefinierte Eigenschaften bei jedem neuen Kartenprogramm von Grund auf neu zu konfigurieren, können Sie jede bestehende Vorlage in Sekunden duplizieren.
Klonen im Dashboard
Sie können das Klonen einer Vorlage an zwei Stellen starten:
-
1
Im Vorlagenverzeichnis: Klicken Sie auf einer beliebigen Vorlagenkarte auf das Drei-Punkte-Menü (...) und wählen Sie Duplizieren.
-
2
Im Visuellen Editor: Klicken Sie in der oberen CommandBar auf Aktionen -> Vorlage duplizieren.
Der 4-stufige Workflow des Template Duplication Wizard
Der Template Duplication Wizard führt Sie Schritt für Schritt durch das Duplizieren einer Vorlage:
-
1
Schritt 1: Quellvorlage auswählen: Bestätigt die Quellvorlage und zeigt Pass-Art, Feldanzahl sowie verknüpfte Bilder an.
-
2
Schritt 2: Name & Beschreibung: Belegt den neuen Vorlagennamen mit
${sourceTemplate.name} (Copy)vor und ermöglicht das Eintragen einer eigenen Beschreibung. -
3
Schritt 3: Anpassung:
- Verknüpfte PassFlow-Registrierungsseite: Entscheiden Sie, ob das zugehörige öffentliche Registrierungsformular über duplicatePassFlow mitgeklont werden soll (wodurch eine eigenständige /f/:newUrl-PassFlow-Seite entsteht) oder ob die neue Vorlage ohne verknüpftes Formular angelegt wird. - Markenfarben: Passen Sie backgroundColor, foregroundColor und labelColor an. Der Assistent führt eine Echtzeit-WCAG-AA-Kontrastprüfung durch, um gute Lesbarkeit sicherzustellen. - Visuelle Assets: Wählen Sie, ob die Bilder der Quellvorlage (icon, logo, strip, thumbnail) übernommen oder neue Marken-Assets hochgeladen werden sollen.
-
4
Schritt 4: Zertifikatszuweisung: Wählen Sie ein bestehendes Apple-Pass-Type-ID-Signaturzertifikat aus den Workspace-Einstellungen oder laden Sie ein neues
.p12- /.cer-Zertifikat hoch.
2. Workspace-Isolierung & saubere Vorlagenbenennung
Passinstance trennt Vorlagen, Pässe, Zertifikate und API-Schlüssel strikt an der Customer-Workspace-Grenze innerhalb Ihrer übergeordneten Organization (POST /api/v1/organizations/current/workspaces):
-
1
Umgebungen nach Workspace trennen: Halten Sie experimentelle Entwürfe und Integrationstests in einem
sandbox-Workspace und reservieren Sie Ihrenproduction-Workspace ausschließlich für produktive Kundenprogramme. -
2
Vorlagennamen & Tags standardisieren: Nehmen Sie Programmbereich, Region und Version in Vorlagentitel auf (z. B.
Loyalty-CoffeeClub-EU-v2) und vergeben Sie strukturiertetags(z. B.["retail", "q4-2026", "dach"]), um den Katalog sofort filtern zu können. -
3
Abgelöste Vorlagen archivieren (
rowKind: ARCHIVED): Statt historische Aktionsvorlagen mit noch zugeordneten Pass-Datensätzen zu löschen, überführen Sie diese in den Status Archiviert. Archivierte Vorlagen werden in standardmäßigen aktiven Auswahlmenüs ausgeblendet, während historische Analysen und Scan-Protokolle unter dem Filter Alle / Archiviert vollständig erhalten bleiben.
3. External-ID-Eindeutigkeit, benutzerdefinierte Kennungen & Bundle-Gruppierung
Um doppelte Pass-Ausgaben über Webformulare, Kassenterminals und CRM-Webhooks hinweg zu verhindern, konfigurieren Sie Kennungs- und Bündelungsrichtlinien in den Vorlageneinstellungen:
| Einstellung / Modelleigenschaft | Durchsetzung in Datenbank & API | |
|---|---|---|
externalId (Pass.externalId) | Vom Aufrufer übergebene Zeichenkette (max. 255 Zeichen), eindeutig indiziert pro aktivem, nicht gelöschtem Mandanten-Pass (@@unique([customerId, externalId]) WHERE archivedAt IS NULL). Doppelte POST /api/v1/passes-Aufrufe werden abgelehnt, während POST /api/v1/passes/upsert-by-external-id direkt aktualisiert. | |
Regeln für benutzerdefinierte Kennungen (Template) | Konfigurieren Sie customIdentifiersEnabled, externalIdentifierPattern und customIdentifierValidationPattern in den Vorlageneinstellungen, um unternehmensweite Regex-Formate für generierte oder importierte externe Kennungen durchzusetzen. | |
Mehrfachkarten-Gruppierung (Pass.bundleId) | Fremdschlüssel bundleId, der bis zu 10 Pässe in einem pass bundle (bundle grouping mode: AUTO \ | MANUAL) für die Auslieferung als .pkpasses zusammenfasst. |
Einzelgeräte-Bindung (limitToOneActivePerPass) | Beschränkt Smart-Download-Links, sodass ein einzelner Pass nicht gleichzeitig geteilt und auf unbefugten Geräten installiert werden kann. |
Wichtig: Das Erzwingen der
externalId-Eindeutigkeit wird für Treue-, Mitgliedschafts- und Prepaid-Geschenkkartenvorlagen ausdrücklich empfohlen. Ein Soft-Delete eines Test-Passes (SOFT-Löschung) setztarchivedAtund gibt dieseexternalIdsofort wieder für eine erneute Verwendung frei.
4. Strukturierte JSON-Attributindizierung (attribute search index) & gespeicherte Ansichten
Jede benutzerdefinierte Eigenschaft innerhalb von Pass.attributes wird automatisch durch den Generalized Inverted Index der Datenbank (attribute search index) indiziert. So können Teams und API-Clients Millionen von Pässen ohne Datenbank-Schemamigrationen organisieren und abfragen:
-
Gespeicherte Ansichten für Operatoren: Kombinieren Sie im Verzeichnis Pässe (
/passes) UND/ODER-Filterbedingungen überstatus(Pass-Status),lifecycleStatus,walletVoidStatus(WalletPropagationStatus),bundleId,externalId, Geräteplattform (APPLE_WALLETvs.GOOGLE_WALLET) sowie benutzerdefinierte strukturierte JSON-Schlüssel (attributes.tier,attributes.storeId) und speichern Sie die Abfrage als Gespeicherte Ansicht. -
Projektübergreifende Vorlagenzuordnung: Gruppieren Sie zusammengehörige Vorlagen in Wallet Experiences (
PassProject), statt isolierte Vorlagen zu klonen. Eine einzelne Vorlage kann über mehrerePassProject-Container hinweg alsLINKED-,VIP-,CUSTOM- oderPRIVACY_MODE-Vorlage fungieren (PassProjectTemplateRole) und dabei eine zentrale Steuerung von Assets und Mechaniken beibehalten.
API-Referenz: Vorlagen duplizieren & filtern
1. Vorlage per API duplizieren (POST /api/v1/templates/:id/duplicate)
Klont eine bestehende Vorlage einschließlich ihrer Layoutfelder, Farben, Barcodes und Definitionen benutzerdefinierter Eigenschaften:
POST /api/v1/templates/tmpl_01hxyz987654321/duplicate Header: X-API-Key: <API_KEY> | Content-Type: application/json
{
"name": "Artisan Coffee Club - Platinum Tier (Copy)",
"duplicatePassFlow": true,
"certificateId": "cert_01j7k8m9n2p3"
}
HTTP-Antwort (201 Created)
{
"success": true,
"data": {
"id": "tmpl_new_clone_01h987",
"name": "Artisan Coffee Club - Platinum Tier (Copy)",
"kind": "storeCard",
"status": "PUBLISHED",
"versionNumber": 1,
"rowKind": "PRODUCTION",
"createdAt": "2026-11-16T21:20:00.000Z"
},
"statusCode": 201
}
2. Vorlagen nach Status, Art & Tags filtern
/api/v1/templates?rowKind=PRODUCTION&kind=storeCard&tag=retail&search=Coffee&page=1&limit=20
{
"success": true,
"data": {
"items": [
{
"id": "tmpl_01hxyz987654321",
"groupId": "grp_01hxyz987654321",
"name": "Loyalty-CoffeeClub-EU-v2",
"kind": "storeCard",
"rowKind": "PRODUCTION",
"status": "PUBLISHED",
"versionNumber": 2,
"tags": ["retail", "q4-2026", "dach"],
"activePassesCount": 14820
}
],
"total": 1,
"page": 1,
"limit": 20
},
"statusCode": 200
}
Erfahren Sie unter Projekte verwalten, wie Sie Pässe aus mehreren Vorlagen zusammenführen, oder lesen Sie Ihren Workspace verstehen für die Regeln der Mandantenfähigkeit über mehrere Workspaces hinweg.
