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
Live-Docs-Workbench — Codebeispiele aktualisieren sich während der Eingabe
Ü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

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.