Skip to content
REST-API-Referenz & SDKs

Passinstance Entwickler-Dokumentation

Erstellen Sie hochvolumige Apple Wallet (.pkpass) und Google Wallet Integrationen. Ausstellen, aktualisieren, scannen und Echtzeit-Benachrichtigungen über produktive REST-APIs übertragen.

API-Schlüssel erhalten
5-Minuten-SchnellstartAPI-Schlüssel erhalten

Erstellen Sie Ihren ersten Wallet-Pass in unter 5 Minuten

Stellen Sie Apple Wallet (.pkpass) & Google Wallet Pässe mit einer einzigen REST-Anfrage aus, signieren Sie sie kryptografisch und verteilen Sie sie.

Live-Pass-Studio — Felder bearbeiten, um Code & Karte direkt zu aktualisieren
Liefert Apple Wallet (.pkpass) & Google Wallet
Ausgabe-Vorschau
ARAcme Rewards
Punkte
450
Mitglied
Jane Doe
Gold VIP
MEMBER-2024-8891
PKCS#7 · .pkpassHTTP 201
POST/api/v1/passes
curl --max-time 30 -X POST https://api.passinstance.com/api/v1/passes \
  -H "X-API-Key: $PASSINSTANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
  -d '{
    "templateId": "tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b",
    "serialNumber": "MEMBER-2024-8891",
    "externalId": "CRM-CUST-99201",
    "name": "Acme VIP Customer Pass",
    "attributes": {
      "guestName": "Jane Doe",
      "tier": "Gold VIP",
      "points": "450"
    },
    "storedValue": "50.00",
    "organizationName": "Acme Rewards",
    "backgroundColor": "#1b2d3c",
    "foregroundColor": "#ffffff",
    "labelColor": "#7db4f0",
    "barcode": {
      "value": "PI-8891-JD-VIP",
      "alternativeText": "8891-VIP"
    },
    "images": {
      "icon": "https://assets.passinstance.com/media/icon.png",
      "logo": "https://assets.passinstance.com/media/logo.png",
      "strip": "https://assets.passinstance.com/media/strip.png"
    },
    "relevantDate": "2026-08-25T18:00:00.000Z"
  }'
Übersicht

Einführung — API-Übersicht

Mit der Passinstance API können Entwickler digitale Pässe für Apple Wallet (iOS) und Google Wallet (Android) dynamisch ausstellen, verteilen, aktualisieren und validieren. Alle API-Anfragen müssen über HTTPS erfolgen und geben einen standardisierten API-Antwortumschlag mit maschinenlesbaren Statuscodes zurück.

Produktions-Basis-URL
Aktiv
https://api.passinstance.com/api/v1
Staging-Sandbox-Basis-URL
https://staging-api.passinstance.com/api/v1
Anfrage- & Antwortformatapplication/json (UTF-8) mit Standard-Antwortumschlag
Backend-Server-ZeitzoneEurope/Berlin (ISO-8601-Zeitstempel)
Sicherheit

Authentifizierung — API-Schlüssel & Autorisierung

Verwenden Sie X-API-Key: <key> oder Authorization: ApiKey <key> für Endpunkte mit API-Schlüsselunterstützung. Bearer ist für Zugriffs-JWTs vorgesehen. Bewahren Sie Zugangsdaten serverseitig auf.

Produktionsschlüssel (Live)
Authorization: ApiKey pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Sandbox-Schlüssel (Test)
Authorization: ApiKey pi_test_xxxxxxxxxxxxxxxxxxxxxxxx
Hardware-Scanner-Schlüssel
x-scanner-key: scan_key_77a8b9c0d1e2f3a4...
Sicherheitsinvariante:Nur Server-zu-Server. Geheime Schlüssel niemals in Frontend-Bundles einbetten.
Schnellstart

Schnellstart — Erste API-Anfrage

Erstellen Sie Ihren ersten nutzbaren Pass in unter 5 Minuten. Setzen Sie Ihren API-Schlüssel-Header, rufen Sie POST /api/v1/passes mit einer gültigen templateId auf und senden Sie die zurückgegebene passAccessUrl an Ihren Endnutzer.

Schritt 1: Schlüssel setzen
export PASSINSTANCE_API_KEY="pi_test_..."
Schritt 2: Pass ausstellen

POST /api/v1/passes mit templateId und serialNumber

Schritt 3: URL abrufen

response.data.passAccessUrl aus der 201-Created-Antwort extrahieren

Schritt 4: Verteilen

URL per SMS/E-Mail senden; Nutzer tippt auf "Zu Apple/Google Wallet hinzufügen"

Ressourcen

Postman-Collection — API-Anfragen importieren & testen

Importieren Sie die Passinstance OpenAPI-3.0-Spezifikation (/api/docs/openapi.json) direkt in Postman, Insomnia oder Bruno, um Endpunkte zu testen, Schemata zu prüfen und typisierte HTTP-Clients zu generieren.

OpenAPI 3.0 JSON-Spezifikation öffnen
1. OpenAPI-3.0-Spezifikations-URL
https://passinstance.com/api/docs/openapi.json
2. In Postman / Bruno importieren

Klicken Sie in Postman, Insomnia oder Bruno auf Import und fügen Sie /api/docs/openapi.json ein

3. Umgebung konfigurieren

Setzen Sie baseUrl = https://api.passinstance.com und PASSINSTANCE_API_KEY = pi_test_...

4. Verbindung prüfen

Senden Sie GET /api/v1/templates mit X-API-Key: zum Testen Ihres Workspaces

Betrieb & FAQ

FAQ — Häufig gestellte Fragen & Fehlerbehandlung

Jede Antwort verwendet den standardisierten API-Antwortumschlag. Beheben Sie 4xx-Fehler vor einem erneuten Versuch; warten Sie bei 5xx und 429 anhand von Retry-After.

200 OK / 201 CreatedErfolg
{
  "success": true,
  "data": { ... },
  "errors": [],
  "statusCode": 200
}
Kernkonzepte

Architektur & Pass-Lebenszyklus

Die Passverwaltung folgt einem 6-stufigen Lebenszyklus: 1. Vorlage (visueller Bauplan) → 2. Pass (kryptografisch signierter Datensatz) → 3. Verteilung (sichere passAccessUrl) → 4. Wallet-Registrierung (Gerät registriert sich bei APNs / Google Push) → 5. Live-Updates (Echtzeit-Sperrbildschirm-Benachrichtigungen) → 6. Scan- & Einlösetelemetrie (Barcode-Validierung & Webhook-Stream).

1. VorlagePOST /api/v1/templates

Master-Layout, Barcode-Typ, Markenfarben und Schemafelder

Plattform-Leitfäden

Apple Wallet vs. Google Wallet Vergleichsmatrix

Passinstance signiert automatisch .pkpass-Pakete für iOS und erzeugt signierte JWT-Objekte für Google Wallet. Assets, Barcodes und Sperrbildschirm-Trigger passen sich nahtlos an beide Betriebssysteme an.

Apple WalletiOS · .pkpass
Apple Wallet Signierung

Kryptografische PKCS#7-Signatur mit Apple Pass Type ID-Zertifikat

Google WalletAndroid · JWT
Google Wallet Issuer

Google Cloud Service Account REST-JWT-Nutzlast

Plattformübergreifende Parität (ein REST-Aufruf)iOS + Android
Hero- / Strip-GrafikenApple: 375×123 px (3:1) | Google: 1032×336 px (ca. 3:1)
Universelle BarcodesQR-Code und PDF417 nativ auf beiden mobilen Plattformen unterstützt
Kernkonzepte

Pass-Mechaniken & Loyalty-Solutions-Engine

Verknüpfen Sie zustandsbehaftete Geschäftsmechaniken über 8 schlüsselfertige Lösungen hinweg mit Vorlagen (Treueprogramme, Stempelkarten, Coupons, Geschenkkarten/Prepaid, Event-Tickets, Mitgliedschaften, Mitarbeiterausweise, VIP-Karten). Regeln werden beim Scan oder API-Aufruf atomar ausgeführt.

LOYALTY_PROGRAM

LOYALTY_PROGRAM & Stufen

Punktegutschrift pro Scan (defaultChangeValue) mit automatischer Stufenprogression

STAMP_CARD

STAMP_CARD_ADD / DEDUCT

Verfolgt Stempelpositionen (0..maximumValue) mit onCap ('noop' | 'reset') und rewardClaimBehavior

PREPAID_CARD

PREPAID_CARD Ledger

ISO-4217-Prepaid-Ledger-Buchhaltung in kleinsten Währungseinheiten mit disallowNegativeBalance-Durchsetzung

VALID_ONCE_PER_DAY

VALID_ONCE_PER_DAY & RENEW

Zeitzonenbewusste tägliche Check-in-Limits und automatische Verlängerung von expirationDate beim Scan

Vorlagenverwaltung

7 Endpunkte
GEThttps://api.passinstance.com/api/v1/templatesAPI-Schlüssel
Vorlagenverwaltung

Alle Vorlagen auflisten

Paginierte Liste der Pass-Vorlagen abrufen, die zum authentifizierten Kunden-Workspace gehören.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Query-Parameter3 fakultativ

Antwort-Statuscodes

GEThttps://api.passinstance.com/api/v1/templates/{id}API-Schlüssel
Vorlagenverwaltung

Vorlagendetails abrufen

Vollständige Details einer Pass-Vorlage einschließlich Farben, Barcode-Einstellungen, Layoutfeldern und Mechanik-Regeln abrufen.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
idUUID
Erforderlich

Eindeutige Vorlagenkennung.

Beispiel: tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Antwort-Statuscodes

GEThttps://api.passinstance.com/api/v1/templates/{id}/fieldsAPI-Schlüssel
Vorlagenverwaltung

Vorlagenfelder abrufen

Berechnete dynamische Felddefinitionen und benutzerdefinierte Eigenschaftsschlüssel abrufen, die pro Pass für eine Vorlage befüllt werden können.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
idstring (UUID)
Erforderlich

Eindeutige Vorlagen-UUID.

Beispiel: 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
Query-Parameter1 fakultativ

Antwort-Statuscodes

POSThttps://api.passinstance.com/api/v1/templatesAPI-Schlüssel
Vorlagenverwaltung

Pass-Vorlage erstellen

Neue wiederverwendbare Pass-Vorlage mit visuellem Branding, Barcode-Typ, NFC-Konfiguration und Layoutfeldern entwerfen und registrieren.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1

Vorlagen-Anfragekonfiguration gemäß OpenAPI-JSON-Schema.

Anfrage-Body6 erforderlich • 4 fakultativ
namestring
Erforderlich

Anzeigename der Vorlage.

Beispiel: VIP Loyalty Card Template
descriptionstring
Erforderlich

Ausführliche Beschreibung von Zweck und Stufenvorteilen des Passes.

Beispiel: Exclusive loyalty and rewards card for VIP customers
organizationNamestring
Erforderlich

Organisations-/Markenname im Karten-Header.

Beispiel: Acme Rewards
kindstring (enum)
Erforderlich

storeCard, coupon, eventTicket, generic, boardingPass oder membership.

Beispiel: storeCard
statusstring (enum)
Erforderlich

DRAFT, PUBLISHED, ARCHIVED, DEPRECATED oder UNDER_REVIEW.

Beispiel: PUBLISHED
preferredStyleSchemestring (enum)
Erforderlich

DARK, posterGeneric, posterEventTicket, bannerEventTicket oder semanticBoardingPass.

Beispiel: DARK

Antwort-Statuscodes

POSThttps://api.passinstance.com/api/v1/templates/{id}/publishAPI-Schlüssel
Vorlagenverwaltung

Vorlagen-Entwurf veröffentlichen

Vorlagen-Entwurfsrevision (rowKind: DRAFT) auf PUBLISHED hochstufen, changesToPush: true setzen und APNs- sowie Google Wallet-Updates für alle aktiven Pässe einreihen.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
idstring (UUID)
Erforderlich

Zu veröffentlichende Vorlagen-UUID.

Beispiel: tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Anfrage zur Steuerung sofortiger vs. geplanter Veröffentlichung und Wallet-Push-Verteilung.

Anfrage-Body4 fakultativ

Antwort-Statuscodes

POSThttps://api.passinstance.com/api/v1/templates/{id}/copyAPI-Schlüssel
Vorlagenverwaltung

Vorlage duplizieren

Eine bestehende Pass-Vorlage einschließlich Layout, Farben, Bildern und Mechaniken innerhalb desselben Kunden-Workspaces klonen.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
idstring (UUID)
Erforderlich

Quell-Vorlagen-UUID, die dupliziert werden soll.

Beispiel: 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Optional name, description, and ISO 4217 currency override for the duplicated template.

Anfrage-Body3 fakultativ

Antwort-Statuscodes

DELETEhttps://api.passinstance.com/api/v1/templates/{id}API-Schlüssel
Vorlagenverwaltung

Vorlage löschen

Eine Pass-Vorlage löschen und eine asynchrone Hintergrundaufgabe starten, um zugehörige Pässe in Apple Wallet und Google Wallet zu widerrufen.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
idstring (UUID)
Erforderlich

Zu löschende Vorlagen-UUID.

Beispiel: 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Antwort-Statuscodes

Vorlagen-Benachrichtigungen

3 Endpunkte
POSThttps://api.passinstance.com/api/v1/push-notifications/templates/{id}/sendAPI-Schlüssel
Vorlagen-Benachrichtigungen

Push an alle Vorlagen-Pässe senden

Sofortige Sperrbildschirm-Push-Benachrichtigung an alle aktiven Apple Wallet und Google Wallet Pässe einer Vorlage senden.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
idstring (UUID)
Erforderlich

Vorlagen-UUID, deren registrierte Geräte die Rundsendung erhalten.

Beispiel: tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Nutzlast mit pushNotificationText (max. 85 Zeichen) und optionalem Header-Text.

Anfrage-Body1 erforderlich • 1 fakultativ
pushNotificationTextstring
Erforderlich

Sperrbildschirm-Benachrichtigung an aktive Vorlagen-Pässe (max. 85 Zeichen; unterstützt Platzhalter).

Beispiel: Flash Sale starts now! Show your VIP pass at checkout for 2x points.

Antwort-Statuscodes

GEThttps://api.passinstance.com/api/v1/templates/{id}/notificationAPI-Schlüssel
Vorlagen-Benachrichtigungen

Geplante Benachrichtigungen auflisten

Alle geplanten und kürzlich ausgeführten Push-Benachrichtigungskampagnen für eine bestimmte Pass-Vorlage auflisten.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
idstring (UUID)
Erforderlich

Template UUID.

Beispiel: 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Antwort-Statuscodes

DELETEhttps://api.passinstance.com/api/v1/templates/notification/{notificationId}API-Schlüssel
Vorlagen-Benachrichtigungen

Geplante Benachrichtigung stornieren

Eine ausstehende geplante Push-Benachrichtigung für eine Vorlage stornieren, bevor sie an die Wallet-Geräte gesendet wird.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
notificationIdstring (UUID)
Erforderlich

UUID der geplanten Benachrichtigung aus der Planungs- oder Listenabfrage.

Beispiel: f1e2d3c4-b5a6-4987-8765-43210fedcba9

Antwort-Statuscodes

Vorlagen-Integrationen

2 Endpunkte
POSThttps://api.passinstance.com/api/v1/integration-connections/embed-widgetsAPI-Schlüssel
Vorlagen-Integrationen

Embed-Integration erstellen (iFrame)

Eine einbettbare iFrame-Widget-Konfiguration für eine veröffentlichte Vorlage erstellen, um PassFlow-Registrierungen auf Ihrer Website einzubetten.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1

Configuration for the embedded download widget including templateId and allowed host domains.

Anfrage-Body3 erforderlich • 1 fakultativ
namestring
Erforderlich

Anzeigename für die Embed-Widget-Integration.

Beispiel: Checkout Loyalty Embed Widget
templateIdstring (UUID)
Erforderlich

UUID der Ziel-Pass-Vorlage.

Beispiel: 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
allowedDomainsstring[]
Erforderlich

Liste zulässiger Ursprungs-Domains (Origins), die das Widget einbetten dürfen.

Beispiel: ["shop.yourbrand.com", "app.yourbrand.com"]

Antwort-Statuscodes

Pass-Verwaltung

11 Endpunkte
POSThttps://api.passinstance.com/api/v1/passesAPI-Schlüssel
Pass-Verwaltung

Neuen Pass ausstellen

Erstellen und signieren Sie einen neuen Apple Wallet (.pkpass) & Google Wallet Pass aus einer Vorlage mit Kundenfeldern, Barcode und dynamischen Werten.

Header2 erforderlich • 1 fakultativ
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Typestring
Erforderlich

Muss application/json sein.

Beispiel: application/json
Query-Parameter2 fakultativ

Nutzlast mit Vorlagen-ID, eindeutiger Seriennummer, Kundenfeldwerten und optionaler Barcode-Konfiguration.

Anfrage-Body1 erforderlich • 15 fakultativ
templateIdstring (UUID)
Erforderlich

Vorlagen-ID für den Pass.

Beispiel: tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Antwort-Statuscodes

POSThttps://api.passinstance.com/api/v1/passes/upsert-by-external-idAPI-Schlüssel
Pass-Verwaltung

Pass per externer ID synchronisieren (Upsert)

Idempotentes Erstellen oder Aktualisieren eines Passes über (customerId, externalId) für nahtlose CRM-, POS- und E-Commerce-Synchronisation.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1

Anfrage mit templateId, externalId und dynamischen Pass-Attributen.

Anfrage-Body2 erforderlich • 3 fakultativ
templateIdstring (UUID)
Erforderlich

UUID der Zielvorlage.

Beispiel: tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
externalIdstring
Erforderlich

Stabile externe CRM/POS-Kennung, eindeutig innerhalb Ihres Workspaces.

Beispiel: CRM-CUST-99201

Antwort-Statuscodes

POSThttps://api.passinstance.com/api/v1/batch-pass-operations/createAPI-Schlüssel
Pass-Verwaltung

Pässe im Batch ausstellen

Mehrere Wallet-Pässe in einer atomaren Batch-Operation mit Validierung und Fehlerberichterstattung ausstellen.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1

Anfrage mit einem Array von Pass-Konfigurationen.

Anfrage-Body1 erforderlich
passesarray of objects
Erforderlich

Array von Pass-Einträgen mit templateId, barcodeValue und additionalData.

Beispiel: [ { "templateId": "tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b", "barcodeValue": "BULK-001", "additionalData": { "name": "Member #001" } }, { "templateId": "tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b", "barcodeValue": "BULK-002", "additionalData": { "name": "Member #002" } } ]

Antwort-Statuscodes

GEThttps://api.passinstance.com/api/v1/passesAPI-Schlüssel
Pass-Verwaltung

Alle Pässe auflisten

Paginierte Liste von Pässen für den authentifizierten Kunden-Workspace mit Such- und Statusfiltern abrufen.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Query-Parameter13 fakultativ

Antwort-Statuscodes

GEThttps://api.passinstance.com/api/v1/passes/{id}API-Schlüssel
Pass-Verwaltung

Pass abrufen

Vollständige Details, Installationsstatus und Download-Links für einen einzelnen Pass über seine eindeutige ID abrufen.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
idstring (UUID)
Erforderlich

Die eindeutige UUID-Kennung des Passes.

Beispiel: pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Antwort-Statuscodes

PATCHhttps://api.passinstance.com/api/v1/passes/{id}API-Schlüssel
Pass-Verwaltung

Pass aktualisieren & Push senden

Dynamische Felder, Farben oder Barcodes eines Passes aktualisieren und automatisch APNs- und Google Wallet-Push-Benachrichtigungen an installierte Geräte senden.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
idstring (UUID)
Erforderlich

Die eindeutige UUID des zu aktualisierenden Passes.

Beispiel: pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Felder zur Änderung am Pass. Installierte Geräte erhalten sofortige Hintergrund-Updates.

Anfrage-Body13 fakultativ

Antwort-Statuscodes

POSThttps://api.passinstance.com/api/v1/passes/voiding/{id}/voidAPI-Schlüssel
Pass-Verwaltung

Pass deaktivieren

Einen Pass in Apple Wallet und Google Wallet mit sofortiger Push-Weitergabe als ungültig markieren oder reaktivieren.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
idUUID
Erforderlich

Eindeutige Pass-Instanz-ID zum Ungültigmachen oder Reaktivieren.

Beispiel: 9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Nutzlast zur Steuerung des Void-Status, Audit-Grundes und der Wallet-Verteilungsoptionen.

Anfrage-Body1 erforderlich • 1 fakultativ
voidedboolean
Erforderlich

Auf true setzen, um den Pass ungültig zu machen, oder false zum Reaktivieren.

Beispiel: true

Antwort-Statuscodes

DELETEhttps://api.passinstance.com/api/v1/passes/{id}API-Schlüssel
Pass-Verwaltung

Pass löschen

Einen Pass dauerhaft aus Ihrem Workspace löschen und registrierte Apple-Wallet- und Google-Wallet-Installationen widerrufen.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
idstring (UUID)
Erforderlich

Eindeutige UUID des zu löschenden Passes.

Beispiel: b1d972dc-eccf-4f87-ab21-25939d9213d8

Antwort-Statuscodes

POSThttps://api.passinstance.com/api/v1/passes/{id}/useAPI-Schlüssel
Pass-Verwaltung

Mechanik-Aktion anwenden

Atomare Pass-Mechanik-Operation ausführen: INCREMENT (Stempelkarte), DECREMENT, DEBIT (Prepaid-Guthaben), CREDIT oder VALIDATE (Einmal-Coupon).

Header3 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Typestring
Erforderlich

Muss application/json sein.

Beispiel: application/json
Idempotency-Keystring
Erforderlich

Verpflichtende UUID zur Sicherstellung einer atomaren Ausführung und zur Vermeidung doppelter Guthaben- oder Stempelabbuchungen.

Beispiel: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
Pfad-Parameter1 erforderlich
idstring (UUID)
Erforderlich

Die eindeutige UUID des zu bearbeitenden Passes.

Beispiel: pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Anfrage mit Mechanik-Aktion, optionalem Dezimalbetrag, Operator-ID und Standort.

Anfrage-Body1 erforderlich • 4 fakultativ
actionstring (enum)
Erforderlich

INCREMENT, DECREMENT, DEBIT, CREDIT, VALIDATE oder NOOP.

Beispiel: INCREMENT

Antwort-Statuscodes

POSThttps://api.passinstance.com/api/v1/passes/{id}/adjust-valueAPI-Schlüssel
Pass-Verwaltung

Pass-Guthaben anpassen

Guthaben oder Prämienpunkte auf einem Pass manuell gutschreiben (CREDIT) oder abbuchen (DEBIT) inklusive Transaktions-Audit-Protokollierung.

Header3 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Typestring
Erforderlich

Muss application/json sein.

Beispiel: application/json
Idempotency-Keystring
Erforderlich

Verpflichtende UUID zur Sicherstellung atomarer Anpassung und Vermeidung doppelter Gutschriften.

Beispiel: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
Pfad-Parameter1 erforderlich
idUUID
Erforderlich

Ziel-Pass-Instanz-ID.

Beispiel: 9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Anpassungs-Nutzlast mit CREDIT- oder DEBIT-Operation, Betrag und Begründung.

Anfrage-Body2 erforderlich • 2 fakultativ
actionstring
Erforderlich

Transaktionsaktion: 'CREDIT' zum Hinzufügen oder 'DEBIT' zum Abziehen von Guthaben.

Beispiel: CREDIT
amountstring
Erforderlich

Numerischer Betrag zum Gutschreiben oder Abbuchen als Zeichenkette.

Beispiel: 25.00

Antwort-Statuscodes

POSThttps://api.passinstance.com/api/v1/mechanics/redeemAPI-Schlüssel
Pass-Verwaltung

Pass-Mechanik-Prämie einlösen

Verdiente Treue- oder Stempelkarten-Prämie auf einem Pass mithilfe der konfigurierten Pass-Mechanik mit Idempotenzschutz einlösen.

Header1 erforderlich • 1 fakultativ
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx

Einlösungsanfrage mit passId, mechanicId und optionalem idempotencyKey.

Anfrage-Body2 erforderlich • 3 fakultativ
passIdstring (UUID)
Erforderlich

UUID des Passes, der die Prämie einlöst.

Beispiel: pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d
mechanicIdstring (UUID)
Erforderlich

UUID der an die Vorlage gebundenen Pass-Mechanik-Regel.

Beispiel: mech_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d

Antwort-Statuscodes

Suche & Analysen

4 Endpunkte
GEThttps://api.passinstance.com/api/v1/passes/searchAPI-Schlüssel
Suche & Analysen

Pässe durchsuchen

Volltextsuche über ausgestellte Pässe nach Seriennummer, externer ID, E-Mail-Adresse, Inhabername oder benutzerdefinierten Attributen.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Query-Parameter1 erforderlich
querystring
Erforderlich

Suchbegriff oder Abfragezeichenfolge (bis zu 500 Zeichen).

Beispiel: Jane Doe

Antwort-Statuscodes

GEThttps://api.passinstance.com/api/v1/passes/statistics/{templateId}API-Schlüssel
Suche & Analysen

Pass-Statistiken abrufen

Aggregierte Ausstellungs-, Aktivierungs-, Wallet-Installations- und Einlösestatistiken für eine bestimmte Pass-Vorlage abrufen.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
templateIdstring (UUID)
Erforderlich

UUID der Zielvorlage.

Beispiel: 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
Query-Parameter2 fakultativ

Antwort-Statuscodes

GEThttps://api.passinstance.com/api/v1/passes/{id}/historyAPI-Schlüssel
Suche & Analysen

Pass-Statusverlauf abrufen

Chronologischen Audit-Verlauf der Statusänderungen, Punkte-/Saldoaktualisierungen, Scans und Entwertungen eines Passes abrufen.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
idstring (UUID)
Erforderlich

Pass UUID.

Beispiel: b1d972dc-eccf-4f87-ab21-25939d9213d8
Query-Parameter1 fakultativ

Antwort-Statuscodes

POSThttps://api.passinstance.com/api/v1/passes/exportAPI-Schlüssel
Suche & Analysen

Pässe als CSV exportieren

UTF-8-CSV-Export (text/csv; charset=utf-8) ausgewählter Pass-Instanzen anhand der Pass-IDs streamen.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1

Anfrage zur Angabe von 1 bis 2.000 Pass-UUIDs und dem Exportformat.

Anfrage-Body2 erforderlich
passIdsstring[] (UUID v4)
Erforderlich

Array mit 1 bis 2.000 Pass-UUIDs für den CSV-Export.

Beispiel: ["pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d"]
formatstring (enum)
Erforderlich

Export-Ausgabeformat ('csv').

Beispiel: csv

Antwort-Statuscodes

Pass-Zustellung

4 Endpunkte
GEThttps://api.passinstance.com/api/v1/passes/{id}/urisAPI-Schlüssel
Pass-Zustellung

Pass-Ressourcen-URLs abrufen

Direkte Download- und Verteilungs-URLs für einen Pass abrufen, einschließlich gehosteter PassFlow-Seite, .pkpass, Google-Wallet-JWT und QR-Code.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
idstring (UUID)
Erforderlich

Pass UUID.

Beispiel: b1d972dc-eccf-4f87-ab21-25939d9213d8

Antwort-Statuscodes

GEThttps://api.passinstance.com/d/{slug}/infoÖffentlich
Pass-Zustellung

Gebrandete Download-Seite abrufen

Öffentliche gebrandete Pass-Download-Seite anhand des Slugs auflösen (präfixfrei GET /d/{slug}/info). Für authentifizierte Verwaltungssuche nutzen Sie GET /api/v1/download-pages/slug/{slug}.

Pfad-Parameter1 erforderlich
slugstring
Erforderlich

Eindeutiger Vanity-Slug der gehosteten Download-Seite.

Beispiel: acme-vip-2026
Query-Parameter2 fakultativ

Antwort-Statuscodes

POSThttps://api.passinstance.com/api/v1/passes/{id}/enabledownloadAPI-Schlüssel
Pass-Zustellung

Pass-Download aktivieren

Den Download-Link eines Passes erneut aktivieren oder entsperren, wenn die Vorlage mit einer Einmal-Download-Sperre konfiguriert ist.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
idstring (UUID)
Erforderlich

UUID des Passes, dessen Download entsperrt werden soll.

Beispiel: b1d972dc-eccf-4f87-ab21-25939d9213d8

Optional timestamp specifying how long re-download remains unlocked.

Anfrage-Body1 fakultativ

Antwort-Statuscodes

POSThttps://api.passinstance.com/api/v1/passes/{id}/send-emailAPI-Schlüssel
Pass-Zustellung

Pass per E-Mail senden

E-Mail mit dem Pass-Installationslink (Apple Wallet & Google Wallet) über die transaktionale E-Mail-Pipeline an den Inhaber senden.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
idstring (UUID)
Erforderlich

UUID des Passes, der per E-Mail zugestellt werden soll.

Beispiel: b1d972dc-eccf-4f87-ab21-25939d9213d8

Recipient email address(es) and optional custom subject and message body.

Anfrage-Body4 fakultativ

Antwort-Statuscodes

Push-Benachrichtigungen

2 Endpunkte
POSThttps://api.passinstance.com/api/v1/passes/{id}/notificationsAPI-Schlüssel
Push-Benachrichtigungen

Sperrbildschirm-Benachrichtigung senden

Sofortige Push-Benachrichtigung und Sperrbildschirm-Nachricht an einen installierten Apple Wallet (.pkpass) oder Google Wallet Pass senden. Für geplante Sendungen oder Header-Anpassung nutzen Sie POST /api/v1/push-notifications/passes/{id}.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
idUUID
Erforderlich

Eindeutige Pass-Instanz-UUID, die die Benachrichtigung erhalten soll.

Beispiel: 9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Anfrage mit Nachrichtentext und optionalem Header-Titel.

Anfrage-Body1 erforderlich • 1 fakultativ
messagestring
Erforderlich

Textnachricht, die auf dem Sperrbildschirm des Nutzers angezeigt wird.

Beispiel: Your reward points have been updated! You now have 250 points.

Antwort-Statuscodes

POSThttps://api.passinstance.com/api/v1/passes/sendpushnotificationsAPI-Schlüssel
Push-Benachrichtigungen

Massen-Push-Benachrichtigungen senden

Sperrbildschirm-Push-Benachrichtigung gleichzeitig an eine ausgewählte Liste von Pass-IDs über APNs und Google Wallet senden.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1

Target pass UUID array (up to 500 passes) and notification message text supporting {attribute} placeholders.

Anfrage-Body2 erforderlich
listOfPassesstring[] (UUID)
Erforderlich

Array mit 1 bis 500 Pass-UUIDs.

Beispiel: ["b1d972dc-eccf-4f87-ab21-25939d9213d8"]
pushNotificationTextstring
Erforderlich

Sperrbildschirm-Nachricht (unterstützt dynamische Platzhalter wie {holderName}).

Beispiel: Hi {holderName}, you unlocked a new reward!

Antwort-Statuscodes

Bündelverwaltung

4 Endpunkte
POSThttps://api.passinstance.com/api/v1/bundles/upsertAPI-Schlüssel
Bündelverwaltung

Pass-Bündel erstellen oder aktualisieren

Ein Multi-Pass-Bündel (.pkpasses) erstellen oder aktualisieren, mit dem Nutzer mehrere zusammengehörige Pässe in einem Schritt installieren können.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1

Array of pass UUIDs (up to 10) and optional existing bundleId.

Anfrage-Body1 erforderlich • 1 fakultativ
passesstring[] (UUID)
Erforderlich

Array mit 1 bis 10 Pass-UUIDs, die zu einem Bündel zusammengefasst werden.

Beispiel: ["b1d972dc-eccf-4f87-ab21-25939d9213d8", "c2e083ed-fddf-4a98-bc32-36040e0324e9"]

Antwort-Statuscodes

GEThttps://api.passinstance.com/api/v1/bundles/{id}/passesAPI-Schlüssel
Bündelverwaltung

Pässe im Bündel auflisten

Alle einzelnen Pässe auflisten, die aktuell einem Pass-Bündel zugeordnet sind, einschließlich Status und Seriennummern.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
idstring (UUID)
Erforderlich

UUID des Pass-Bündels.

Beispiel: e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b
Query-Parameter3 fakultativ

Antwort-Statuscodes

POSThttps://api.passinstance.com/api/v1/bundles/{id}/voidAPI-Schlüssel
Bündelverwaltung

Bündel-Pässe entwerten

Alle in einem Pass-Bündel enthaltenen Pässe in einer einzigen Operation entwerten oder reaktivieren.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
idstring (UUID)
Erforderlich

UUID des Pass-Bündels.

Beispiel: e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b

Confirmation flag and optional audit reason for voiding all passes in the bundle.

Anfrage-Body1 erforderlich • 1 fakultativ
voidedboolean
Erforderlich

Muss auf true gesetzt sein, um alle Pässe im Bündel zu entwerten.

Beispiel: true

Antwort-Statuscodes

DELETEhttps://api.passinstance.com/api/v1/bundles/{id}API-Schlüssel
Bündelverwaltung

Pass-Bündel löschen

Eine Pass-Bündel-Gruppierung löschen (optional unter Beibehaltung oder Widerruf der darunterliegenden Einzelpässe).

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
idstring (UUID)
Erforderlich

UUID des zu löschenden Pass-Bündels.

Beispiel: e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b

Antwort-Statuscodes

Sicherheit

Übersicht — Wie die Pass-Validierung funktioniert

Jeder Barcode- oder NFC-Scan durchläuft eine deterministische 14-Regel-Validierungspipeline (Status, Ablauf, Zeitfenster, Geofencing, Mechaniken, Rate-Limits, Anti-Replay) mit optionalen kryptografischen Nonces und Offline-Datensatz-Synchronisierung.

Anti-Replay-Nonce

POST /api/v1/scans/prepare stellt eine kurzlebige kryptografische Anti-Replay-Nonce gebunden an den Barcode aus

14-Regel-Pipeline

PassStatus → Expiration → TimeWindow → Geofencing → Mechanics → RateLimit → AntiReplay

Offline-Datensatz-Sync

GET /api/v1/scans/offline-dataset liefert Cursor-paginierte Snapshots für Offline-Terminals

Scanner-Schlüssel-Kopplung

POST /api/v1/scanner-keys/from-link tauscht Pairing-Token + PIN gegen einen bereichsbezogenen x-scanner-key

Scanner-Konfiguration

3 Endpunkte
GEThttps://api.passinstance.com/api/v1/validation/configsAPI-Schlüssel
Scanner-Konfiguration

Scanner-Konfigurationen auflisten

Alle im Workspace eingerichteten Scanner-Konfigurationsprofile (Mobil-App, Web-Scanner, POS) und deren Vorlagenberechtigungen auflisten.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Query-Parameter2 fakultativ

Antwort-Statuscodes

GEThttps://api.passinstance.com/api/v1/validation/configs/{id}API-Schlüssel
Scanner-Konfiguration

Scanner-Konfiguration abrufen

Details einer einzelnen Scanner-Konfiguration abrufen, einschließlich zulässiger Vorlagen, Nach-Scan-Nachricht und Validierungsregeln.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
idstring (UUID)
Erforderlich

UUID der Scanner-Konfiguration.

Beispiel: 7a8b9c0d-1e2f-4a3b-8c9d-0e1f2a3b4c5d

Antwort-Statuscodes

POSThttps://api.passinstance.com/api/v1/validation/configsAPI-Schlüssel
Scanner-Konfiguration

Scanner-Konfiguration erstellen

Ein neues Scanner-Konfigurationsprofil mit Vorlagenzuordnung, Standard-Scan-Aktion und benutzerdefinierter Bestätigungsnachricht erstellen.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1

Scanner configuration profile name, allowed template UUIDs, scan mode, and optional cooldown window.

Anfrage-Body2 erforderlich • 2 fakultativ
namestring
Erforderlich

Anzeigename für das Scanner-Konfigurationsprofil.

Beispiel: Main Entrance Gate Scanners
templateIdsstring[] (UUID)
Erforderlich

Vorlagen-UUIDs, die unter diesem Scanner-Profil validiert werden dürfen.

Beispiel: ["8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b"]

Antwort-Statuscodes

Scan-Operationen

4 Endpunkte
GEThttps://api.passinstance.com/api/v1/validation/scansAPI-Schlüssel
Scan-Operationen

Scan-Einträge auflisten

Paginiertes Audit-Protokoll der Pass-Scans mit Filterung nach Vorlage, Pass-ID, Scanner-Konfiguration, Entscheidung und Zeitraum abrufen.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Query-Parameter3 fakultativ

Antwort-Statuscodes

POSThttps://api.passinstance.com/api/v1/scansScanner-Schlüssel
Scan-Operationen

Barcode- / NFC-Scan verarbeiten

Optischen Barcode, QR-Code oder Apple VAS / Google Smart Tap NFC-Scan von einem Terminal oder mobilen Scanner über die 14-Regel-Validierungs-Engine prüfen.

Header2 erforderlich • 2 fakultativ
x-scanner-keystring
Erforderlich

Zweckgebundener Scanner-Konfigurationsschlüssel aus dem Dashboard oder einem Scanner-Kopplungslink.

Beispiel: scan_key_77a8b9c0d1e2f3a4b5c6d7e8
Content-Typestring
Erforderlich

Muss application/json sein.

Beispiel: application/json

Nutzlast mit gescanntem Barcode-String, optionaler Anti-Replay-Nonce, Kanal-/Protokoll-Metadaten und Operator-Kontext.

Anfrage-Body1 erforderlich • 8 fakultativ
scannedBarcodeValuestring
Erforderlich

Der aus QR-Code, PDF417, CODE128, AZTEC oder NFC-Tap gelesene Rohwert.

Beispiel: PI-8891-JD-VIP

Antwort-Statuscodes

POSThttps://api.passinstance.com/api/v1/scans/prepareScanner-Schlüssel
Scan-Operationen

Anti-Replay-Scan-Nonce vorbereiten

Kurzlebige kryptografische Anti-Replay-Nonce gebunden an einen Pass-Barcode ausstellen, bevor POST /api/v1/scans ausgeführt wird.

Header1 erforderlich
x-scanner-keystring
Erforderlich

Zweckgebundener Scanner-Konfigurationsschlüssel aus dem Dashboard oder einem Scanner-Kopplungslink.

Beispiel: scan_key_77a8b9c0d1e2f3a4b5c6d7e8

Anfrage mit dem gescannten Barcode-Wert zur Bindung der kryptografischen Nonce.

Anfrage-Body1 erforderlich
scannedBarcodeValuestring
Erforderlich

Barcode- oder NFC-Token-String, an den die Anti-Replay-Nonce gebunden wird.

Beispiel: PI-8891-JD-VIP

Antwort-Statuscodes

GEThttps://api.passinstance.com/api/v1/scans/offline-datasetScanner-Schlüssel
Scan-Operationen

Offline-Scanner-Datensatz abrufen

Cursor-paginierten Pass-Snapshot-Datensatz im Bereich des aufrufenden x-scanner-key für lokale Offline-Validierung bei Verbindungsausfall herunterladen.

Header1 erforderlich
x-scanner-keystring
Erforderlich

Zweckgebundener Scanner-Konfigurationsschlüssel aus dem Dashboard oder einem Scanner-Kopplungslink.

Beispiel: scan_key_77a8b9c0d1e2f3a4b5c6d7e8
Query-Parameter3 fakultativ

Antwort-Statuscodes

Übersicht & Endpunkte

4 Endpunkte
Webhooks

Webhooks-Übersicht & Signaturprüfung

Prüfen Sie X-Webhook-Signature als HMAC-SHA256 über den unveränderten Anfragebody mit Ihrem Abonnement-Secret. Vergleichen Sie in konstanter Zeit und verarbeiten Sie Ereignisse idempotent.

Signatur-Header
X-Webhook-Signature: sha256=9f8e7d6c5b4a3...
Zeitstempel-Header
X-Webhook-Timestamp: 2026-08-21T20:30:00.000Z
Replay-Schutz

Gleichen Sie X-Webhook-Id mit der signierten eventId ab, deduplizieren Sie Ereignisse und prüfen Sie den signierten Zeitstempel gemäß Ihrer Replay-Richtlinie.

Unterstützte Ereignisse

PASS_CREATED, PASS_UPDATED, PASS_VOIDED, PASS_DOWNLOADED, APP_SCAN_CREATED, LOCATION_ENTERED, NOTIFICATION_SENT, DEVICE_REGISTERED, DEVICE_UNREGISTERED, TEMPLATE_PUBLISHED

Erwartete Antwort

Geben Sie innerhalb von 5.000 ms HTTP 200 OK zurück, um den Empfang zu bestätigen

Öffentlicher Signaturschlüssel

GET /api/v1/webhooks/public-key liefert den aktiven öffentlichen Schlüssel zur Signaturprüfung

POSThttps://api.passinstance.com/api/v1/webhooks/subscriptionsAPI-Schlüssel
Übersicht & Endpunkte

Webhook-Abonnement erstellen

HTTPS-Endpunkt registrieren, um HMAC-signierte Echtzeit-Ereignisbenachrichtigungen für Pass-Ausgabe, Updates, Scans und Deinstallationen zu erhalten.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1

Anfrage mit Ziel-HTTPS-URL und Liste von Webhook-Ereignistypen-Elementen.

Anfrage-Body2 erforderlich • 5 fakultativ
urlstring (HTTPS URL)
Erforderlich

Ihre Server-Endpunkt-URL (muss mit https:// beginnen, max. 2048 Zeichen).

Beispiel: https://your-server.com/webhooks/passinstance
eventsstring[] (enum)
Erforderlich

Webhook-Ereignistypen-Werte: PASS_CREATED, PASS_UPDATED, PASS_VOIDED, PASS_DOWNLOADED, APP_SCAN_CREATED, LOCATION_ENTERED, NOTIFICATION_SENT, DEVICE_REGISTERED, DEVICE_UNREGISTERED, TEMPLATE_PUBLISHED.

Beispiel: ["PASS_CREATED", "PASS_UPDATED", "APP_SCAN_CREATED"]

Antwort-Statuscodes

DELETEhttps://api.passinstance.com/api/v1/webhooks/subscriptions/{id}API-Schlüssel
Übersicht & Endpunkte

Webhook abbestellen

Ein aktives Webhook-Abonnement anhand seiner ID löschen und zukünftige Ereigniszustellungen an den Endpunkt beenden.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
idstring (UUID)
Erforderlich

UUID des zu entfernenden Webhook-Abonnements.

Beispiel: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Antwort-Statuscodes

GEThttps://api.passinstance.com/api/v1/webhooks/subscriptionsAPI-Schlüssel
Übersicht & Endpunkte

Webhook-Abonnements auflisten

Alle aktiven Webhook-Abonnements abrufen, die für Ihren Kunden-Workspace registriert sind.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1

Antwort-Statuscodes

GEThttps://api.passinstance.com/api/v1/webhooks/public-keyÖffentlich
Übersicht & Endpunkte

Öffentlichen Webhook-Signaturschlüssel abrufen

Den aktiven öffentlichen PEM-Schlüssel von Passinstance abrufen, um asymmetrische Webhook-Signaturen kryptografisch zu prüfen.

Antwort-Statuscodes

Pull-basierte Webhooks

2 Endpunkte
Webhooks

Funktionsweise & Grenzen von Pull-Webhooks

Verarbeiten Sie Pass- und Scan-Ereignisse in Echtzeit über ausgehende HMAC-SHA256-Push-Webhooks (mit exponentiellem Backoff und Circuit-Breakern) oder eingehendes Pull-Webhook-Polling für Firewall-geschützte Umgebungen sowie No-Code-Workflows.

Push-Webhook-Ausfallsicherheit

5 Wiederholungen mit jittered exponentiellem Backoff; Circuit Breaker öffnet nach 10 aufeinanderfolgenden Fehlern

Pull-Webhook-Polling

GET /api/v1/webhook-payload & POST /api/v1/webhook-payload/acknowledge für private Netzwerke

Workflow-Trigger

PASS_CREATED, APP_SCAN_CREATED, PASS_INSTALLED, TIER_CHANGED, BALANCE_CHANGED, SCHEDULED

Workflow-Aktionen

SEND_PUSH_NOTIFICATION, UPDATE_PASS_FIELDS, SEND_EMAIL, WEBHOOK, MOVE_TO_SEGMENT

GEThttps://api.passinstance.com/api/v1/webhook-payloadAPI-Schlüssel
Pull-basierte Webhooks

Ausstehende Pull-Webhook-Ereignisse abfragen

Ausstehende Webhook-Ereignis-Payloads über ausgehendes HTTPS GET für Firewall-geschützte oder private Netzwerke ohne offene Eingangsports abrufen.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Query-Parameter3 fakultativ

Antwort-Statuscodes

POSThttps://api.passinstance.com/api/v1/webhook-payload/acknowledgeAPI-Schlüssel
Pull-basierte Webhooks

Pull-Webhook-Ereignisse bestätigen

Verarbeitete Pull-Webhook-Payloads bis zu einer angegebenen Payload-ID bestätigen, sodass sie als zugestellt markiert und aus der Warteschlange entfernt werden.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1

Anfrage mit Angabe der High-Water-Mark-Payload-ID (upTo).

Anfrage-Body1 erforderlich • 1 fakultativ
upTostring (UUID)
Erforderlich

Zuletzt verarbeitete Webhook-Payload-ID; alle Ereignisse bis einschließlich dieser ID werden bestätigt.

Beispiel: whp_55a4b3c2-1d0e-9f8a-7b6c-5d4e3f2a1b0c

Antwort-Statuscodes

Webhook-Ereignisse

4 Leitfäden
Webhook-EreignisseAusgehende HTTP-POST-Webhook-Benachrichtigung

Vorlagen-Ereignisse (Template Events)

Ausgehende HTTP-POST-Webhook-Benachrichtigungen, wenn eine Pass-Vorlage erstellt, aktualisiert, veröffentlicht oder gelöscht wird.

Vorlage erstellt
POST
TEMPLATE_CREATED

Wird ausgelöst, wenn eine neue Pass-Vorlage erstellt wird

Vorlage aktualisiert
POST
TEMPLATE_UPDATED

Wird ausgelöst, wenn Vorlagenfelder, Layout oder Mechaniken geändert werden

Vorlage veröffentlicht
POST
TEMPLATE_PUBLISHED

Wird ausgelöst, wenn ein Vorlagenentwurf für aktive Pässe veröffentlicht wird

Vorlage gelöscht
POST
TEMPLATE_DELETED

Wird ausgelöst, wenn die Vorlagenlöschung und der Wallet-Widerruf starten

Webhook-EreignisseAusgehende HTTP-POST-Webhook-Benachrichtigung

Pass-Ereignisse (Pass Events)

Ausgehende HTTP-POST-Webhook-Benachrichtigungen für jeden Lebenszyklusschritt eines Passes von der Erstellung bis zur Geräteentfernung.

Pass erstellt
POST
PASS_CREATED

Wird sofort ausgelöst, wenn ein neuer Pass über die REST-API oder PassFlow ausgestellt wird

Pass aktualisiert
POST
PASS_UPDATED

Wird ausgelöst, wenn Pass-Attribute, Treuepunkte, Stufe oder Guthaben geändert werden

Pass entwertet
POST
PASS_VOIDED

Wird ausgelöst, wenn ein Pass in Apple Wallet & Google Wallet entwertet oder deaktiviert wird

Erstmaliger Pass-Download
POST
PASS_FIRST_DOWNLOAD

Wird beim ersten Abruf oder Download des Passes durch den Kunden ausgelöst

Pass heruntergeladen
POST
PASS_DOWNLOADED

Wird bei jedem weiteren Download des Pass-Pakets oder Google-Wallet-Links ausgelöst

Pass vom Gerät entfernt
POST
PASS_REMOVED

Wird ausgelöst, wenn der Nutzer den Pass aus Apple Wallet oder Google Wallet löscht

Webhook-EreignisseAusgehende HTTP-POST-Webhook-Benachrichtigung

Scan-Ereignisse (Scan Events)

Ausgehende HTTP-POST-Webhook-Benachrichtigungen in Echtzeit, sobald ein Pass-Barcode oder NFC-Pass gescannt und validiert wird.

Pass-Scan erstellt
POST
APP_SCAN_CREATED

Wird ausgelöst, wenn POST /api/v1/scans oder ein Scanner einen Scan aufzeichnet

Scan-Metadaten

Enthält passId, serialNumber, templateId, configId, Scan-Entscheidung und Saldoänderung

Zustellgarantie

Mindestens einmalige HTTPS-POST-Zustellung mit X-Webhook-Id und X-Webhook-Signature

Pull-Queue-Kompatibilität

Auch über GET /api/v1/webhook-payload für geschützte Kassensysteme abrufbar

Webhook-EreignisseAusgehende HTTP-POST-Webhook-Benachrichtigung

Nachrichten-Ereignisse & Status-Referenz (Message Events)

Ausgehende HTTP-POST-Webhook-Benachrichtigungen und Zustellstatuscodes für Wallet-Push-Nachrichten, E-Mail-Kampagnen und SMS.

Nachricht gesendet
POST
MESSAGE_SENTNOTIFICATION_SENT

Wird ausgelöst, wenn eine Pass-Nachricht oder ein Push gesendet wird

Zustellung fehlgeschlagen
POST
MESSAGE_FAILED

Wird ausgelöst, wenn eine ausgehende E-Mail, SMS oder Push-Nachricht fehlschlägt

Nachrichten-Statusreferenz

QUEUED -> SENT -> DELIVERED (oder FAILED / BOUNCED mit Diagnosecode)

Idempotente Ereigniskorrelation

Abgleich von eventId und passId im Webhook-Consumer zur Deduplizierung von Wiederholungen

Durchgängige Plattform- & API-Dokumentation

Passinstance Hilfezentrum: Alle 10 Themen & 94 Anleitungen

Entdecken Sie Schritt-für-Schritt-Anleitungen, Workflow-Architekturdiagramme, JSON-Payload-Schemas und Ressourcen zur Fehlerbehebung für jeden Plattformbereich.

Hilfezentrum öffnen
1. Erste Schritte7 Anleitungen

Alles, was Sie für den erfolgreichen Start mit Passinstance benötigen.