Passinstance Entwickler-Dokumentation
Erstellen Sie hochvolumige Apple Wallet (.pkpass) und Google Wallet Integrationen. Ausstellen, aktualisieren, scannen und Echtzeit-Benachrichtigungen über produktive REST-APIs übertragen.
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.
https://api.passinstance.com/api/v1https://staging-api.passinstance.com/api/v1Authentifizierung — 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.
Authorization: ApiKey pi_live_xxxxxxxxxxxxxxxxxxxxxxxxAuthorization: ApiKey pi_test_xxxxxxxxxxxxxxxxxxxxxxxxx-scanner-key: scan_key_77a8b9c0d1e2f3a4...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.
export PASSINSTANCE_API_KEY="pi_test_..."POST /api/v1/passes mit templateId und serialNumber
response.data.passAccessUrl aus der 201-Created-Antwort extrahieren
URL per SMS/E-Mail senden; Nutzer tippt auf "Zu Apple/Google Wallet hinzufügen"
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.
https://passinstance.com/api/docs/openapi.jsonKlicken Sie in Postman, Insomnia oder Bruno auf Import und fügen Sie /api/docs/openapi.json ein
Setzen Sie baseUrl = https://api.passinstance.com und PASSINSTANCE_API_KEY = pi_test_...
Senden Sie GET /api/v1/templates mit X-API-Key: zum Testen Ihres Workspaces
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.
{
"success": true,
"data": { ... },
"errors": [],
"statusCode": 200
}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).
POST /api/v1/templatesMaster-Layout, Barcode-Typ, Markenfarben und Schemafelder
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.
Kryptografische PKCS#7-Signatur mit Apple Pass Type ID-Zertifikat
Google Cloud Service Account REST-JWT-Nutzlast
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_PROGRAMLOYALTY_PROGRAM & Stufen
Punktegutschrift pro Scan (defaultChangeValue) mit automatischer Stufenprogression
STAMP_CARDSTAMP_CARD_ADD / DEDUCT
Verfolgt Stempelpositionen (0..maximumValue) mit onCap ('noop' | 'reset') und rewardClaimBehavior
PREPAID_CARDPREPAID_CARD Ledger
ISO-4217-Prepaid-Ledger-Buchhaltung in kleinsten Währungseinheiten mit disallowNegativeBalance-Durchsetzung
VALID_ONCE_PER_DAYVALID_ONCE_PER_DAY & RENEW
Zeitzonenbewusste tägliche Check-in-Limits und automatische Verlängerung von expirationDate beim Scan
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.
Alles, was Sie für den erfolgreichen Start mit Passinstance benötigen.
Entdecken Sie, wie digitale Wallet-Karten unterschiedliche Geschäftsanforderungen erfüllen.
Gestalten, erstellen, organisieren und pflegen Sie Ihre digitalen Wallet-Karten.
Stellen Sie Karten an Kundinnen und Kunden zu und halten Sie Wallets aktuell.
Konfigurieren Sie Wallet-Anbieter, Zertifikate und NFC-Funktionen.
Prüfen Sie Pässe, verwalten Sie Check-ins und buchen Sie Prämien.
Verbinden Sie Passinstance mit Ihren Systemen und automatisieren Sie Abläufe.
Überwachen Sie Kennzahlen, verfolgen Sie Aktivitäten und werten Sie Nutzung aus.
Verwalten Sie Organisation, Benutzer, Abonnement und Unternehmenseinstellungen.
Finden Sie Antworten, beheben Sie Störungen und kontaktieren Sie unser Team.
