Skip to content
Hilfecenter-Anleitung · Pass-AusgabeOnboarding-Phase 3
4 Min. LesezeitGeprüft 2026-11-16

Einzelne Pässe erstellen

Erzeugen Sie einzelne Karten aus einer veröffentlichten Vorlage mit Kundendaten und direktem Download-/QR-Testlink.

In dieser Anleitung

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

Vergrößerter UI-Fokus
Wichtige UI-Elemente

Einzelnen Pass erstellen & Schnellaktionen (Zoom)

Klicken Sie in der Kopfzeile auf „+ Create pass“ oder unter Schnellaktionen auf „Create single pass“, um einen Testpass aus Ihrer Vorlage zu erzeugen.

Überblick

Mit der Einzelausgabe von Pässen können Bediener und Backend-Integrationen eine einzelne personalisierte digitale Wallet-Karte aus jeder PUBLISHED-Vorlage erzeugen. Ob manuell über das Pass erstellen-Panel im Dashboard oder programmatisch per REST-API: Passinstance weist eine kryptografisch eindeutige serialNumber und ein authenticationToken zu, befüllt alle dynamischen {variable}-Felder, signiert das Apple-.pkpass-Paket sowie das Google-Wallet-JWT und liefert sofort eine intelligente Verteilungs-URL (passAccessUrl) zurück.

Schnellaktionen einer Vorlage zum Erstellen eines einzelnen Passes
Schnellaktionen einer Vorlage zum Erstellen eines einzelnen Passes

Systemarchitektur: Einzel-Pass-Ausgabe & idempotenter Upsert

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
EINZEL-PASS-AUSGABE & IDEMPOTENTER UPSERT
STUFE 01 DASHBOARD-DRAWER / CRM / POS-BACKEND
Standardausgabe: POST/api/v1/passes (request payload)
Idempotenter Upsert: POST/api/v1/passes/upsert-by-external-id
STUFE 02 PASS-AUSGABE-SERVICE (Pass Issuance Engine)
1
Prüft, ob Ziel-Template PUBLISHED & auf Workspace (customerId) begrenzt
2
Prüft Verbundschlüssel (customerId, externalId) auf idempotente Deduplizierung
3
Erzeugt eindeutige serialNumber & 32-Byte-Hex authenticationToken
4
Validiert structured JSON-attributes gegen Custom-Property-Schema der Vorlage
5
Speichert Pass-Zeile (status: ACTIVE) & initialisiert pass mechanic-Konto
STUFE 03 WALLET-SIGNIERUNG & SMART-LINK-PAKETIERUNG
Erstellt Smart-Download-Link (passAccessUrl) & QR-Code-Endpunkt
Bereitet signierten Apple-.pkpass-Stream & Google-Wallet-Save-JWT vor
Liefert API response (request payload) mit 201 Created oder 200 OK

Einzelnen Pass manuell im Dashboard ausgeben

  1. 1
    Öffnen Sie die Übersichtsseite Ihrer veröffentlichten (Published) Vorlage.
  2. 2
    Klicken Sie in der oberen Kopfzeile (oder unter Schnellaktionen) auf Pass erstellen.
  3. 3
    Füllen Sie alle im Formular als Erforderliche Eigenschaft (Required Custom Property) markierten Felder aus (z. B. Kundenname, E-Mail/Telefon für den Versand, Start-Stempelzahl oder externalId).
  4. 4
    Senden Sie das Formular ab, um den Pass sofort zu generieren.
  5. 5
    Kopieren Sie die eindeutige Download-URL (passAccessUrl), zeigen Sie den Installations-QR-Code zum Scannen mit einem Smartphone an oder lösen Sie direkt aus dem Pass-Detailbereich eine Versand-E-Mail aus.

Voraussetzungen: Veröffentlichen Sie Ihre Vorlage (POST /api/v1/templates/:id/publish) mit gültigen Apple Pass Type ID- / Google-Wallet-Zugangsdaten, bevor Sie Live-Pässe ausgeben. Intern löst resolvePassCreationTemplateId die templateId auf die aktive PRODUCTION/PUBLISHED-Basisrevision auf und lehnt Vorlagen im Zustand DELETING/DELETED ab (BadRequestException / NotFoundException).

API-Referenz für die programmatische Ausgabe

1. Neuen Pass erstellen (POST /api/v1/passes)

Erstellt über request payload einen neuen Pass-Datensatz und berücksichtigt dabei einen optionalen HTTP-Header Idempotency-Key (idempotencyKey, max. 128 Zeichen gemäß [A-Za-z0-9._:-]+, abgesichert über einen SHA-256-Hash des Requests) sowie die optionalen Query-Parameter ?includePassSource=apple|google und ?pin=.

Anfrageparameter von request payload

FeldTypErforderlichBeschreibung
templateIdstring (UUID)JaVorlagen-UUID (wird automatisch auf die aktive PRODUCTION/PUBLISHED-Basiszeile aufgelöst).
externalIdstringOptionalMandantenweit eindeutige CRM-/POS-/Bestell-ID (max. 255 Zeichen; eindeutig für alle nicht gelöschten aktiven Pässe via @@unique([customerId, externalId])).
serialNumberstringOptionalEigene eindeutige Seriennummer (wird automatisch generiert, falls weggelassen).
barcodeValuestringOptionalExpliziter Barcode-Payload. Standardmäßig aus Vorlagen-Barcode-Konfiguration oder generiert.
barcodeAltText / barcodeAlternativeTextstringOptionalKlartext-Beschriftung unter dem Barcode für manuelle Eingabe an der Kasse.
attributesRecord<string, any>OptionalSchlüssel-Wert-structured JSON-Objekt passend zu den Custom-Property-Keys Ihrer Vorlage.
expirationDatestringOptionalAblaufdatum/-zeit (<= 10 Jahre in der Zukunft, interpretiert in der Workspace-Zeitzone).
validityAsOfDate / validAsOfDatestringOptionalGültig-ab-Datum/-zeit (issuedDate).
enableDownloadUntilstringOptionalDownload-Frist ("YYYY-MM-DD HH:mm" oder ISO-Zeitstempel).
sharingProhibitedbooleanOptionalÜberschreibt die Anti-Sharing-Einstellung der Vorlage (limitToOneActivePerPass).
validationPlacesstring[]OptionalAbweichende zulässige Validation Places, sofern auf der Vorlage aktiviert.
skipDistributeOnCreatebooleanOptionalUnterdrückt den automatischen Versand nach Erstellung (E-Mail/SMS) bei API-Ausgabe.

Beispielanfrage

POST /api/v1/passes?includePassSource=google Header: X-API-Key: <API_KEY> | Content-Type: application/json | Idempotency-Key: crm_usr_44910_v1

JSON
{
  "templateId": "tmpl_01hxyz987654321",
  "externalId": "crm_usr_44910",
  "serialNumber": "PI-GOLD-2026-44910",
  "barcodeValue": "PI-GOLD-2026-44910",
  "barcodeAltText": "44910-GOLD",
  "expirationDate": "2027-12-31 23:59",
  "attributes": {
    "firstName": "Marcus",
    "lastName": "Vance",
    "email": "marcus.vance@example.com",
    "pointsBalance": 500,
    "memberTier": "Gold"
  }
}

Beispielantwort (API response envelope)

JSON
{
  "success": true,
  "data": {
    "id": "pass_01j8k9m2n3p4q5r6",
    "templateId": "tmpl_01hxyz987654321",
    "customerId": "cust_ws_88219",
    "externalId": "crm_usr_44910",
    "bundleId": null,
    "idempotencyKey": "crm_usr_44910_v1",
    "serialNumber": "PI-GOLD-2026-44910",
    "authenticationToken": "a9f4e2c81b7d60359e12c4b8f7a6d5e0",
    "downloadCode": "dl_94f8a1",
    "barcodeValue": "PI-GOLD-2026-44910",
    "barcodeAltText": "44910-GOLD",
    "status": "ACTIVE",
    "lifecycleStatus": "ACTIVE",
    "walletVoidStatus": "NONE",
    "appleArtifactStatus": "NOT_GENERATED",
    "googleArtifactStatus": "READY",
    "downloadUrl": "https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6",
    "passAccessUrl": "https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6",
    "attributes": {
      "firstName": "Marcus",
      "lastName": "Vance",
      "email": "marcus.vance@example.com",
      "pointsBalance": 500,
      "memberTier": "Gold"
    },
    "expirationDate": "2027-12-31T23:59:00.000Z",
    "createdAt": "2026-11-15T15:04:12.000Z"
  },
  "description": "Pass created successfully",
  "errors": [],
  "statusCode": 201
}

Tipp — Multi-Pass-Bündelung (bundleId): Wenn Sie zusammengehörige Pässe für einen Haushalt, Flugabschnitte oder VIP-Event-Bestellungen erstellen, weisen Sie diese einem pass bundle (/api/v1/bundles/upsert oder PassProject) zu, damit Pass.bundleId bis zu 10 Pässe in einem gemeinsamen .pkpasses- bzw. Multi-Card-Claim-Link gruppiert.

2. Idempotenter Upsert & Suche per External ID (request payload)

Bei webhook-gesteuerten Integrationen (Shopify, HubSpot oder POS-Checkouts) können Netzwerk-Retries dieselbe Anfrage mehrfach auslösen. Passinstance stellt dafür dedizierte externalId-Endpunkte bereit, die auf Ihre aktiven Mandantenpässe (archivedAt: null) begrenzt sind:

  • POST /api/v1/passes/upsert-by-external-id: Erstellt einen neuen Pass, falls kein aktiver Pass zu externalId existiert (action: "CREATED"), oder führt attributes, expirationDate, status (pass status) sowie eine optionale changeMessage (<=500 Zeichen) mit dem bestehenden Pass zusammen (action: "UPDATED").
  • PUT /api/v1/passes/by-external-id/:externalId: Führt den Upsert über den Pfadparameter :externalId aus (externalId im Body muss übereinstimmen oder kann entfallen).
  • GET /api/v1/passes/by-external-id/:externalId: Ruft den aktiven Pass direkt über externalId ab, ohne interne UUIDs extern speichern zu müssen.

Beispielanfrage

POST /api/v1/passes/upsert-by-external-id Header: X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "templateId": "tmpl_01hxyz987654321",
  "externalId": "crm_usr_44910",
  "status": "ACTIVE",
  "changeMessage": "Tier updated to Platinum (%@ pts)",
  "attributes": {
    "pointsBalance": 750,
    "memberTier": "Platinum"
  }
}

Beispielantwort (200 OK)

JSON
{
  "success": true,
  "data": {
    "pass": {
      "id": "pass_01j8k9m2n3p4q5r6",
      "externalId": "crm_usr_44910",
      "serialNumber": "PI-GOLD-2026-44910",
      "status": "ACTIVE",
      "walletVoidStatus": "QUEUED"
    },
    "action": "UPDATED"
  },
  "description": "Pass updated successfully",
  "errors": [],
  "statusCode": 200
}

Für den Massenimport großer CSV-Bestände oder direkte JSON-Array-Stapeloperationen lesen Sie Massen-Pass-Erstellung und Massenaktionen.

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.