Skip to content
Hilfecenter-Anleitung · Entwickler-API
5 Min. LesezeitGeprüft 2026-11-16

API-Referenz

Durchsuchen Sie alle REST-Endpunkte für Passes, Templates, Scanner, Delivery, Webhooks und Stapelverarbeitung.

In dieser Anleitung

Überblick

Die Passinstance REST API gliedert sich in modulare Domänen-Controller, die überwiegend unter /api/v1 eingebunden sind (ergänzt um eigene präfixfreie Routen für POS /v1/pos/*, Pull-Webhooks /webhook-payload, eingehende Anbieter-Webhooks /webhooks/*, Health-Probes /health/* sowie Smart-Links /s/:token und /d/:slug). Jeder Endpunkt verwendet Standard-HTTP-Verben (GET, POST, PUT, PATCH, DELETE), erzwingt anhand Ihrer API-Zugangsdaten die Mandantenisolation des Arbeitsbereichs und gibt ein deterministisches JSON-Payload zurück (API response (T) bei Arbeitsbereich-APIs).

Voraussetzungen: Erstellen Sie unter /settings/workspace/developer/api-credentials einen Arbeitsbereich-API-Schlüssel (pi_live_... oder pi_test_...) mit den benötigten API_KEY_SCOPE_VALUES (passes, templates, scans, webhooks, analytics oder *), bevor Sie /api/v1/*-Routen aufrufen. Eine interaktive OpenAPI-Dokumentation steht unter GET /api/public/docs und /docs bereit.

Anfrage- & Antwort-Lebenszyklus

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
REST-API-ANFRAGE- & UMSCHLAG-LEBENSZYKLUS
BETEILIGTE SYSTEMKOMPONENTEN
P1 Externe Integration
P2 Passinstance /api/v1/*
P3 Wallet-Anbieter & DB
SCHRITT 1 ANFRAGE / AKTION POST/api/v1/passes
SCHRITT 2 ANFRAGE / AKTION DTO & Mandantengrenze prüfen
SCHRITT 3 ANFRAGE / AKTION .pkpass signieren (bundleId)
›
idempotencyKey
›
& Google Wallet JWT bauen
SCHRITT 4 ANTWORT 201 Created
›
API response (request payload)
SCHRITT 5 ANFRAGE / AKTION PATCH/api/v1/passes/:id
SCHRITT 6 ANFRAGE / AKTION Feld-Update speichern
SCHRITT 7 ANTWORT 200 OK
›
7. APNs & Google Push einreihen >

REST-Endpunkt-Katalog nach Domäne

1. Pässe, Upserts & Stapelverarbeitung

VerbPfadBeschreibung
POST/api/v1/passesStellt eine Pass-Instanz aus (request payload: templateId, optional externalId, idempotencyKey, attributes), signiert mit dem Vorlagen-Zertifikat (bundleId = Apple passTypeIdentifier).
POST/api/v1/passes/upsert-by-external-idErstellt oder aktualisiert idempotent einen Pass, der über (templateId, externalId) zugeordnet wird (request payload).
GET/api/v1/passesListet Pass-Instanzen mit Paginierung, Statusfilterung (pass status) und Suchabfragen auf.
GET/api/v1/passes/:idRuft vollständige Details, dynamische Attribute, externalId, serialNumber und Registrierungsstatus ab.
PATCH / PUT/api/v1/passes/:idAktualisiert dynamische Felder, Stufe oder Ablaufdatum und sendet Live-Updates an installierte Wallets.
POST/api/v1/passes/voiding/:id/voidEntwertet einen Pass (request payload + VoidingReason) und versendet ein stilles voided: true-Push-Update.
DELETE/api/v1/passes/:idLöscht einen Pass per Soft-Delete und widerruft aktive Wallet-Installationen.
POST/api/v1/passes/exportExportiert gefilterte Pass-Datensätze als UTF-8-CSV- oder JSON-Download-Job.
POST/api/v1/batch-pass-operations/createFührt synchrone/gequeute Massen-Pass-Erstellungen über Batch Operations API aus (ebenfalls /update, /upsert, /activate, /deactivate, /delete).
POST/api/v1/batch-processingÜbermittelt einen asynchronen großen CSV-/JSON-Stapelauftrag, verfolgt über Batch Processing API.

2. Vorlagen & Mechaniken

VerbPfadBeschreibung
GET/api/v1/templatesListet Pass-Vorlagen des Arbeitsbereichs, Pass-Typen (PassKind), bundleId-Zertifikatsbindungen und Veröffentlichungsstatus auf.
GET/api/v1/templates/:idLiefert Vorlagenschema, visuelles Layout und aktive Mechaniken zurück.
POST/api/v1/templates/:id/publishVeröffentlicht Entwurfsänderungen (request payload) und versendet gebündelte Push-Updates (vorab GET .../publish-risk-check).
GET/api/v1/templates/:templateId/attributesListet dynamische Feldschlüssel und -typen auf, die bei der Pass-Ausstellung benötigt werden (unterstützt OAuth templates:read).
POST/api/v1/mechanics/redeemLöst eine freigeschaltete Treue- oder Stempelkarten-Prämie ein (request payload: UUID passId, mechanicId).
GET/api/v1/mechanics/:mechanicId/passes/:passId/ledgerGibt das Transaktions-Ledger der Wertguthaben- oder Treuemechanik eines Passes zurück (GET /api/v1/balance-changes für den Mandanten-Feed).

3. Scans, Geräte & POS-Validierung

VerbPfadBeschreibung
POST/api/v1/scansWertet einen Barcode-/NFC-Scan gegen die 14-Regel-Validation Rules Engine aus (ScanMode & scan status).
POST/api/v1/scans/prepareStellt eine kurzlebige kryptografische scan nonce zum Anti-Replay-Schutz aus.
GET/api/v1/scans/passSchreibgeschützte Pass-Abfrage per ?barcode=... (oder Pfad-Parameter GET /api/v1/scans/pass/:barcodeValue).
POST/api/v1/scans/pass/:passId/useFührt direkt eine request payload-Aktion aus (INCREMENT, DECREMENT, DEBIT, CREDIT, VALIDATE, NOOP, SET).
GET/api/v1/scans/result/:scanIdRuft den Audit-Datensatz und ruleTrace eines abgeschlossenen Scans ab.
GET/api/v1/scans/offline-datasetCursor-paginierter Pass-Snapshot (offline scan dataset) für mobile Offline-Scanner.
POST/v1/pos/redeemPräfixfreier POS-Endpunkt für atomare PosOperation-Befehle (DISCOUNT, ADD_POINTS, DEDUCT_VALUE, ADD_STAMPS, VOID, CUSTOM).
POST/api/v1/reader/redeemVerarbeitet Hardware-NFC-Leser-Einlösungen, authentifiziert via X-Reader-Secret (POST /api/v1/reader/validate für Zutrittsprüfungen).

4. Push-Benachrichtigungen, Webhooks & Workflows

VerbPfadBeschreibung
POST/api/v1/push-notifications/templates/:id/sendVersendet eine Sofort-Benachrichtigung an alle für eine Vorlage registrierten Geräte (request payload auf /passes/:id/schedule).
POST/api/v1/push-notifications/segmentationAdressiert ein gefiltertes Pass-Segment (request payload) mit lokalisierten Push-Updates.
POST/api/v1/push-notifications/batchSendet Stapel-Benachrichtigungen über Passlisten oder CSV-Uploads (request payload).
GET / POST/api/v1/webhooksRuft die Webhook-Übersicht ab oder verwaltet ausgehende HTTPS-Push-Webhook-Endpunkte (/api/v1/webhooks/subscriptions).
GET/webhook-payloadPräfixfreie Pull API (auch GET /api/v3/webhook-payload unterstützt) zum Abrufen unbestätigter Events für Empfänger hinter Firewalls.
POST/webhook-payload/acknowledgePräfixfreie Empfangsbestätigung ({ upTo, webhookId } bzw. POST /api/v3/webhook-payload/acknowledge).
GET / POST/api/v1/workflowsListet oder erstellt ereignisgesteuerte automatisierte Workflows (Workflow Engine API, neben /api/v1/automations).

5. Analysen, Abrechnung & Datenschutz-Governance

VerbPfadBeschreibung
GET/api/v1/analyticsMehrteiliger Telemetriebericht (passes, registrations, walletAppsShare; siehe /api/v1/analytics/passes/overview).
GET/api/v1/analytics/wallet-installationsGeräte- und Pass-bezogene Installationsmatrix zwischen Apple Wallet und Google Wallet (request payload).
GET/api/v1/billing/subscriptionLiefert aktiven Abonnementtarif, Abrechnungszyklus und Verlängerungsstatus.
GET/api/v1/billing/invoices/:id/downloadStreamt die PDF-Steuerrechnung (application/pdf).
POST/api/v1/customer/:customerId/privacy-settings/data-subject-exportErzeugt ein DSGVO-konformes Archiv personenbezogener Daten für einen Passinhaber.

Standard-API response (T)-Umschlag & Statuscodes

Erfolgs-Umschlag (200 OK / 201 Created)

JSON
{
  "success": true,
  "data": {
    "id": "pass_01hxyz8821",
    "templateId": "tmpl_vip_member",
    "serialNumber": "PI-VIP-8821",
    "externalId": "crm_cust_44910",
    "bundleId": "pass.com.passinstance.vip",
    "status": "ACTIVE",
    "passAccessUrl": "https://api.passinstance.com/s/vip-8821-x9a2"
  },
  "meta": {
    "requestId": "req_99481a2b7c",
    "timestamp": "2026-11-16T10:10:00.000Z"
  }
}

Standard-HTTP-Statuscodes

StatuscodeBedeutungLösung
200 OK / 201 CreatedAnfrage wurde synchron erfolgreich ausgeführt.Ergebnis-Payload aus data auslesen.
400 Bad RequestDTO-Validierungsfehler oder verletzte Domänenregel.errorCode, messageKey und das Array details prüfen.
401 UnauthorizedFehlender, abgelaufener oder ungültiger API-Schlüssel / Bearer-Token.Header x-api-key oder Authorization sowie Übereinstimmung von pi_test_ vs. pi_live_ mit dem Arbeitsbereich prüfen.
403 ForbiddenGültiger Schlüssel besitzt nicht den erforderlichen Scope (z. B. fehlendes 'passes') oder Mandantenzugriff.Zugewiesene Scopes über GET /api/v1/api-keys prüfen.
404 Not FoundZiel-Ressourcen-ID existiert nicht im authentifizierten Arbeitsbereich.UUID / serialNumber / externalId und Arbeitsbereich-Umgebung prüfen.
409 ConflictDoppelte externalId, serialNumber oder gleichzeitige Idempotenzkollision./api/v1/passes/upsert-by-external-id verwenden oder einen eindeutigen idempotencyKey übergeben.
429 Too Many Requests1-Sekunden-Burst- oder Kontingent-Rate-Limit überschritten.Antwort-Header Retry-After und RateLimit-Reset beachten.

Vollständige Schemadefinitionen finden Sie im Entwickler-Dokumentations-Hub sowie unter API-Übersicht & Authentifizierung.

Bereit für Ihr erstes Wallet-Kartenprogramm?

Erstellen Sie Ihren Workspace, konfigurieren Sie Ihre Vorlage und testen Sie eine echte Karte in Apple Wallet und Google Wallet, bevor Sie skalieren.