Skip to content
Hilfecenter-Anleitung · Projekte & OrganisationOnboarding-Phase 3
4 Min. LesezeitGeprüft 2026-11-16

Vorlagen & Pässe strukturieren

Halten Sie Kataloge durch einheitliche Benennung, Archivfilter, externe ID-Eindeutigkeit und gespeicherte Ansichten sauber.

In dieser Anleitung

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

Vergrößerter UI-Fokus
Wichtige UI-Elemente

Template Settings — Signierung & External IDs (Zoom)

Signaturzertifikat, Wallet-Sortierung, Veröffentlichungsstatus und Eindeutigkeitsregeln für External IDs in Settings prüfen.

Ü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

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
WORKSPACE-TAXONOMIE, KLONEN & GESPEICHERTE ANSICHTEN
STUFE 01 ORGANISATION (Organization-Modell)
+-- Produktions-Workspace (Customer: kind = 'production')
+-- Sandbox-Workspace (Customer: kind = 'sandbox')
STUFE 02 VORLAGENKATALOG & PROJEKT-CLUSTER (Template / PassProject)
Filter nach rowKind: PUBLISHED | PRODUCTION | DRAFT | ARCHIVED
Kategorisierung: Programm-tags[], passType & PassProjectTemplate-Links
Klon-Engine: POST/api/v1/templates/:id/duplicate (Template Duplication Wizard)
External-ID-Richtlinie: Unique-Constraint auf (customerId, externalId)
STUFE 03 HOCHGESCHWINDIGKEITS-PASSVERZEICHNIS & GESPEICHERTE ANSICHTEN (Pass)
B-Tree-Indizes: (customerId, templateId, status, serialNumber, externalId)
Strukturierter JSON-Suchindex (attribute search index): Sofort-Attributsuche
Gespeicherte Ansichten: Gespeicherte UND/ODER-Filterbäume je Nutzer/Workspace

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. 1
    Im Vorlagenverzeichnis: Klicken Sie auf einer beliebigen Vorlagenkarte auf das Drei-Punkte-Menü (...) und wählen Sie Duplizieren.
  2. 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. 1
    Schritt 1: Quellvorlage auswählen: Bestätigt die Quellvorlage und zeigt Pass-Art, Feldanzahl sowie verknüpfte Bilder an.
  2. 2
    Schritt 2: Name & Beschreibung: Belegt den neuen Vorlagennamen mit ${sourceTemplate.name} (Copy) vor und ermöglicht das Eintragen einer eigenen Beschreibung.
  3. 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.

  1. 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. 1
    Umgebungen nach Workspace trennen: Halten Sie experimentelle Entwürfe und Integrationstests in einem sandbox-Workspace und reservieren Sie Ihren production-Workspace ausschließlich für produktive Kundenprogramme.
  2. 2
    Vorlagennamen & Tags standardisieren: Nehmen Sie Programmbereich, Region und Version in Vorlagentitel auf (z. B. Loyalty-CoffeeClub-EU-v2) und vergeben Sie strukturierte tags (z. B. ["retail", "q4-2026", "dach"]), um den Katalog sofort filtern zu können.
  3. 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 / ModelleigenschaftDurchsetzung 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) setzt archivedAt und gibt diese externalId sofort 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 über status (Pass-Status), lifecycleStatus, walletVoidStatus (WalletPropagationStatus), bundleId, externalId, Geräteplattform (APPLE_WALLET vs. 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 mehrere PassProject-Container hinweg als LINKED-, VIP-, CUSTOM- oder PRIVACY_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

JSON
{
  "name": "Artisan Coffee Club - Platinum Tier (Copy)",
  "duplicatePassFlow": true,
  "certificateId": "cert_01j7k8m9n2p3"
}

HTTP-Antwort (201 Created)

JSON
{
  "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

GET /api/v1/templates?rowKind=PRODUCTION&kind=storeCard&tag=retail&search=Coffee&page=1&limit=20
Header
X-API-Key <API_KEY>
JSON
{
  "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.

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.