Erstellen Sie hochvolumige Apple Wallet (.pkpass) und Google Wallet Integrationen. Ausstellen, aktualisieren, scannen und Echtzeit-Benachrichtigungen über produktive REST-APIs übertragen.
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
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.
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"
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.
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.
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
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
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.
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.
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.
Ö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.
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.
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.
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.
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.
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
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.
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.