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