Ü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.

Systemarchitektur: Einzel-Pass-Ausgabe & idempotenter Upsert
Einzelnen Pass manuell im Dashboard ausgeben
-
1
Öffnen Sie die Übersichtsseite Ihrer veröffentlichten (Published) Vorlage.
-
2
Klicken Sie in der oberen Kopfzeile (oder unter Schnellaktionen) auf Pass erstellen.
-
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
Senden Sie das Formular ab, um den Pass sofort zu generieren.
-
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östresolvePassCreationTemplateIddietemplateIdauf die aktivePRODUCTION/PUBLISHED-Basisrevision auf und lehnt Vorlagen im ZustandDELETING/DELETEDab (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
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
templateId | string (UUID) | Ja | Vorlagen-UUID (wird automatisch auf die aktive PRODUCTION/PUBLISHED-Basiszeile aufgelöst). |
externalId | string | Optional | Mandantenweit eindeutige CRM-/POS-/Bestell-ID (max. 255 Zeichen; eindeutig für alle nicht gelöschten aktiven Pässe via @@unique([customerId, externalId])). |
serialNumber | string | Optional | Eigene eindeutige Seriennummer (wird automatisch generiert, falls weggelassen). |
barcodeValue | string | Optional | Expliziter Barcode-Payload. Standardmäßig aus Vorlagen-Barcode-Konfiguration oder generiert. |
barcodeAltText / barcodeAlternativeText | string | Optional | Klartext-Beschriftung unter dem Barcode für manuelle Eingabe an der Kasse. |
attributes | Record<string, any> | Optional | Schlüssel-Wert-structured JSON-Objekt passend zu den Custom-Property-Keys Ihrer Vorlage. |
expirationDate | string | Optional | Ablaufdatum/-zeit (<= 10 Jahre in der Zukunft, interpretiert in der Workspace-Zeitzone). |
validityAsOfDate / validAsOfDate | string | Optional | Gültig-ab-Datum/-zeit (issuedDate). |
enableDownloadUntil | string | Optional | Download-Frist ("YYYY-MM-DD HH:mm" oder ISO-Zeitstempel). |
sharingProhibited | boolean | Optional | Überschreibt die Anti-Sharing-Einstellung der Vorlage (limitToOneActivePerPass). |
validationPlaces | string[] | Optional | Abweichende zulässige Validation Places, sofern auf der Vorlage aktiviert. |
skipDistributeOnCreate | boolean | Optional | Unterdrü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
{
"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)
{
"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 einempass bundle(/api/v1/bundles/upsertoderPassProject) zu, damitPass.bundleIdbis zu10Pä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 zuexternalIdexistiert (action: "CREATED"), oder führtattributes,expirationDate,status(pass status) sowie eine optionalechangeMessage(<=500Zeichen) mit dem bestehenden Pass zusammen (action: "UPDATED"). -
PUT /api/v1/passes/by-external-id/:externalId: Führt den Upsert über den Pfadparameter:externalIdaus (externalIdim Body muss übereinstimmen oder kann entfallen). -
GET /api/v1/passes/by-external-id/:externalId: Ruft den aktiven Pass direkt überexternalIdab, 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
{
"templateId": "tmpl_01hxyz987654321",
"externalId": "crm_usr_44910",
"status": "ACTIVE",
"changeMessage": "Tier updated to Platinum (%@ pts)",
"attributes": {
"pointsBalance": 750,
"memberTier": "Platinum"
}
}
Beispielantwort (200 OK)
{
"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.
