Skip to content
Hilfecenter-Anleitung · Entwicklertools
2 Min. LesezeitGeprüft 2026-11-16

Integrationshilfen

Nutzen Sie SDK-Tokens, parametrisierte Dynamic Wallet URLs, KI-Workflows für .pkpass und OpenAPI-Schemata.

In dieser Anleitung

Überblick

Zur Beschleunigung Ihrer Backend-Integration in Node.js/TypeScript-, Python-, PHP- und Shell-Umgebungen — ergänzend zu den Entwickler-Tools im Dashboard unter /settings/workspace/integrations/link-generator, /settings/workspace/developer/embed-sdk, /settings/workspace/developer/sdks, /settings/workspace/developer/query-helper und /settings/workspace/developer/qr-generator — bietet dieser Leitfaden bewährte Produktivmuster für idempotente Pass-Upserts (POST /api/v1/passes/upsert-by-external-id), parametrisierte Download-Links (PARAMETERIZED_PASS_LINK / CREATE_PASS_URL), Cursor-basierte Paginierung sowie zeitkonstante HMAC-SHA256-Webhook-Verifizierung.

Wichtig: Synchronisieren Sie einen Geschäftsdatensatz per Upsert über (templateId, externalId). Der zurückgegebene Pass steht unter data.pass, das Ergebnis unter data.action (CREATED oder UPDATED). Senden Sie bei POST /api/v1/passes einen Idempotency-Key-Header, damit Wiederholungen denselben Erstellungsauftrag verwenden. Der Upsert-Endpunkt wertet diesen Header nicht aus.

Ablauf für idempotentes Upsert & Cursor-Paginierung

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
IDEMPOTENTES UPSERT- & CURSOR-PAGINIERUNGS-MUSTER
BETEILIGTE SYSTEMKOMPONENTEN
P1 Ihre Backend-Anwendung
P2 Passinstance REST API (/api/v1)
SCHRITT 1 ANFRAGE / AKTION POST/passes/upsert-by-external-id
›
{ templateId, externalId, attributes }
›
Abgleich (templateId + externalId)
›
Neu anlegen ODER patchen & pushen
SCHRITT 2 ANTWORT 200 OK data: { pass, action }
SCHRITT 3 ANFRAGE / AKTION GET/scans/offline-dataset
›
?limit=250
SCHRITT 4 ANTWORT 200 OK { data: { passes, nextCursor: "c_1" } }
SCHRITT 5 ANFRAGE / AKTION GET/scans/offline-dataset
›
?limit=250&cursor=c_1&snapshotAt=...
SCHRITT 6 ANTWORT 200 OK { data: { passes, hasMore: false } }

Produktivmuster für mehrere Programmiersprachen

1. Node.js / TypeScript: Idempotenter Pass-Upsert-Helper

TYPESCRIPT
interface IUpsertPassPayload {
  templateId: string;
  externalId: string;
  attributes: Record<string, string | number | boolean>;
  expirationDate?: string;
}

export async function upsertWalletPass(payload: IUpsertPassPayload) {
  const response = await fetch('https://api.passinstance.com/api/v1/passes/upsert-by-external-id', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': process.env.PASSINSTANCE_API_KEY ?? '',
    },
    body: JSON.stringify(payload),
  });

  const body = await response.json();
  if (!response.ok || !body.success) {
    throw new Error(`Passinstance API error [${body.errorCode ?? response.status}]: ${body.message}`);
  }
  return body.data.pass as { id: string; serialNumber: string; externalId?: string; passAccessUrl: string };
}

2. Python: Idempotentes Upsert & HMAC-Webhook-Prüfung

PYTHON
import hmac
import hashlib
import os
import requests

API_BASE_URL = "https://api.passinstance.com/api/v1"
API_KEY = os.environ["PASSINSTANCE_API_KEY"]

def upsert_pass_by_external_id(template_id: str, external_id: str, attributes: dict) -> dict:
    response = requests.post(
        f"{API_BASE_URL}/passes/upsert-by-external-id",
        headers={
            "x-api-key": API_KEY,
            "Content-Type": "application/json",
        },
        json={
            "templateId": template_id,
            "externalId": external_id,
            "attributes": attributes,
        },
        timeout=10,
    )
    response.raise_for_status()
    return response.json()["data"]["pass"]

def verify_webhook_signature(raw_body: bytes, signature_header: str, secret: str) -> bool:
    if not signature_header or not signature_header.startswith("sha256="):
        return False
    digest = hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
    expected = f"sha256={digest}"
    return hmac.compare_digest(signature_header, expected)

3. PHP: Pass ausstellen/aktualisieren & Webhooks verifizieren

PHP
<?php
function upsertPassinstancePass(string $templateId, string $externalId, array $attributes): array {
    $payload = json_encode([
        'templateId' => $templateId,
        'externalId' => $externalId,
        'attributes' => $attributes,
    ], JSON_THROW_ON_ERROR);

    $ch = curl_init('https://api.passinstance.com/api/v1/passes/upsert-by-external-id');
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $payload,
        CURLOPT_HTTPHEADER     => [
            'Content-Type: application/json',
            'x-api-key: ' . getenv('PASSINSTANCE_API_KEY'),
        ],
    ]);
    $raw = curl_exec($ch);
    curl_close($ch);
    return json_decode($raw, true, 512, JSON_THROW_ON_ERROR)['data']['pass'];
}

function verifyPassinstanceWebhook(string $rawBody, string $signatureHeader, string $secret): bool {
    $expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
    return hash_equals($expected, $signatureHeader);
}

4. cURL: Schnelle CLI-Referenz

BASH
curl -X POST "https://api.passinstance.com/api/v1/passes/upsert-by-external-id" \
  -H "Content-Type: application/json" \
  -H "x-api-key: pi_live_89a1f4c2e90b41d7a6c3e2f10984b2c1" \
  -d '{
    "templateId": "6f2c5130-2f2a-4f40-8c68-f7192c5b4f43",
    "externalId": "cust_9012",
    "attributes": {
      "memberName": "Clara Oswald",
      "points": 1250,
      "tier": "GOLD"
    }
  }'

Paginierung von Offline-Scanner-Snapshots

GET /api/v1/scans/offline-dataset erfordert x-scanner-key und liefert den Scanner-Snapshot innerhalb einer Antwort mit success, data und metadata. Verwenden Sie auf allen Seiten denselben Wert für snapshotAt.

Parameter / AntwortfeldTypBeschreibung
limitnumberPässe pro Seite (Standard 500, Maximum 1000).
cursorstringVerwenden Sie data.nextCursor der vorherigen Antwort; bei der ersten Anfrage weglassen.
snapshotAtstring (ISO 8601)Übernehmen Sie data.snapshotAt der ersten Antwort als obere Snapshot-Grenze für weitere Seiten.
data.passesArrayPass-Snapshots im Geltungsbereich der Scanner-Konfiguration.
data.hasMorebooleanRufen Sie weitere Seiten ab, solange dieser Wert true ist.
data.nextCursorstringBei data.hasMore === true als cursor verwenden; auf der letzten Seite fehlt dieses Feld.

Entdecken Sie Live-OpenAPI-Schemas unter /docs, testen Sie mit unserer Bruno-Collection unter Testen & Debugging oder entwerfen Sie Pass-Vorlagen mit KI unter Ersten Wallet-Pass erstellen.

Weiterführende Produkt- & Entwicklerdoku

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.