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

Testen & Debugging

Analysieren Sie API-Payloads über Webhook-Logs, standardisierte API-Fehlercodes und kostenlose Sandbox-Testpässe.

In dieser Anleitung

Überblick

Bevor Sie eine Wallet-Pass-Integration für den Produktivbetrieb freigeben, können Sie jeden API-Aufruf, jede Scan-Regel, jede Idempotenzsperre und jede Webhook-Signatur mithilfe von Passinstance-Sandbox-Schlüsseln (pi_test_...), der Entwicklerkonsole im Dashboard (/settings/workspace/developer/*) sowie unserer vorgefertigten Bruno API Collection (unter docs/bruno/) überprüfen.

Wichtig: Testen Sie die Pass-Ausstellung (bundleId-signierte .pkpass-Datei und Google-Wallet-Speicherlink) sowie dynamische Updates vor dem Start stets auf mindestens einem physischen iOS-Gerät (Apple Wallet) und einem Android-Gerät (Google Wallet). Desktop-Vorschauen prüfen zwar die Layout-Struktur, erst die Installation auf physischen Geräten verifiziert jedoch reale APNs-Push-Latenzen und das Sperrbildschirm-Rendering von changeMessage.

Ablauf für Integrationsprüfung & Debugging

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
SANDBOX-TESTS, IDEMPOTENZ & WEBHOOK-DEBUGGING
BETEILIGTE SYSTEMKOMPONENTEN
P1 Entwickler / Bruno CLI
P2 Passinstance API (pi_test_...)
P3 Diagnose- & Audit-Oberfläche
SCHRITT 1 ANFRAGE / AKTION POST/api/v1/passes
›
Header: x-api-key: pi_test_...
›
DTO gegen Vorlage validieren
›
Body: externalId,
›
.pkpass (bundleId) & JWT signieren
›
idempotencyKey
›
pass_created-Webhook auslösen
SCHRITT 2 ANTWORT 201 Created { requestId }
SCHRITT 3 ANFRAGE / AKTION POST/api/v1/scans wiederholen
›
Header: x-idempotency-key: k_01
SCHRITT 4 ANTWORT 200 OK (Idempotenter Cache-Hit)
SCHRITT 5 ANFRAGE / AKTION Health & Protokolle prüfen
›
GET/health/detailed
›
/settings/workspace/developer/logs

1. Sandbox-Schlüssel (pi_test_), Dashboard-Tools & Testpässe

  • Sandbox-API-Schlüssel (pi_test_<secret>): Werden über POST /api/v1/api-keys mit "environment": "test" (API_KEY_ENVIRONMENT_VALUES) in Sandbox-Arbeitsbereichen bereitgestellt. Sie testen Validierung, bundleId-Signierung und Push-Warteschlangen, ohne Produktionskontingente zu verbrauchen.
  • Dashboard-Entwicklerdiagnose: Prüfen Sie Echtzeit-Request-Protokolle, Bull-Hintergrundwarteschlangen, Systemzustand und API-Payloads direkt unter /settings/workspace/developer/logs, /settings/workspace/developer/jobs, /settings/workspace/developer/system-health und /settings/workspace/developer/query-helper.
  • Health-Endpunkte (präfixfrei): Fragen Sie GET /health, GET /health/liveness, GET /health/readiness, GET /health/detailed und GET /health/circuit-breakers ab (alle ohne /api/v1 eingebunden).

2. Bruno API Collection

Passinstance pflegt eine offizielle Bruno API Collection unter docs/bruno/ mit vorkonfigurierten Anfragen über alle Domänenordner hinweg:

Bruno-DomänenbereichAbgedeckte Abläufe & Zusicherungen
Auth & API KeysSchlüsselerstellung (pi_test_), Durchsetzung von API_KEY_SCOPE_VALUES, Rotation und Nutzungs-Telemetrie.
Templates & MechanicsVorlagen-CRUD, Stufen-Asset-Befüllung, Stempelkarten und Wertguthaben-Konfiguration.
Passes & DistributionEinzelausgabe (externalId, idempotencyKey), upsert-by-external-id, Smart-Download-Links (/d/:slug, /s/:token) und POST /api/v1/passes/export.
Scanner RuntimePOST /api/v1/scans/prepare-Nonces, 14-Regel-Auswertung von POST /api/v1/scans, /api/v1/scanner-keys/verify und Offline-Datensatz-Sync.
BillingAbonnement-Vorschau, Tarifwechsel, Stripe-SetupIntents und PDF-Rechnungsdownloads.
Webhooks InboxPush-Webhook-Registrierung (/api/v1/webhooks/subscriptions), HMAC-Prüftests und Pull-Webhook-Warteschlangenabfrage (/webhook-payload).
IntegrationsZapier-/Make-OAuth-Endpunkte (/api/v1/me, /api/v1/webhook-subscriptions) und Shopware-/Shopify-Hooks.
AnalyticsMehrteilige Zeitreihenabfragen (passes/overview, wallet-installations) sowie CSV-Exporte.

3. Idempotenz testen (x-idempotency-key, Idempotency-Key & idempotencyKey)

Verändernde Endpunkte schützen gegen Netzwerk-Wiederholungen über explizite Idempotenzverträge:

  • POST /api/v1/passes: Übergeben Sie idempotencyKey in request payload (oder externalId mit POST /api/v1/passes/upsert-by-external-id).
  • POST /api/v1/scans: Senden Sie den Header x-idempotency-key: test-scan-retry-001 (Idempotency Engine); bei Wiederholung erhalten Sie das identische request payload, jederzeit abrufbar unter GET /api/v1/scans/operations/test-scan-retry-001.
  • POST /api/v1/scans/pass/:passId/use: Senden Sie den Header Idempotency-Key (passend zu einem optionalen idempotencyKey im Body).
  • POST /v1/pos/redeem & POST /api/v1/reader/redeem: Senden Sie idempotencyKey im JSON-Request-Body (request payload / request payload).

4. Standard-Fehlerumschlag

Schlägt eine Anfrage aufgrund von Validierung oder Rate-Limiting fehl, liefert API Error Handler ein strukturiertes Fehler-Payload mit Korrelations-requestId und maschinenlesbarem errorCode:

JSON
{
  "success": false,
  "error": "BAD_REQUEST",
  "messageKey": "api.errors.invalidInput",
  "message": "Invalid input provided: attribute 'memberName' is required by template",
  "statusCode": 400,
  "timestamp": "2026-11-16T10:20:00.000Z",
  "path": "/api/v1/passes",
  "requestId": "req_8f192b0e4c1a",
  "code": "VALIDATION_ERROR",
  "errorCode": "MISSING_REQUIRED_TEMPLATE_ATTRIBUTE",
  "details": [
    {
      "field": "attributes.memberName",
      "issue": "Required string attribute is missing"
    }
  ]
}

5. Webhook-Signaturen & Circuit Breaker debuggen

Wenn Ihr Webhook-Endpunkt keine Events empfängt oder die HMAC-Validierung fehlschlägt:

  • Raw-Body-Parsing prüfen: Stellen Sie sicher, dass Ihr Web-Framework (Express express.raw({ type: 'application/json' }), Next.js await req.text(), FastAPI await request.body()) den exakten rohen Byte-Stream vor der JSON-Deserialisierung einliest.
  • Circuit-Breaker-Status prüfen: Beachten Sie, dass 10 aufeinanderfolgende Nicht-2xx-Antworten oder Timeouts (10s) den Circuit Breaker des Endpunkts (CIRCUIT_BREAKER_THRESHOLD = 10) für eine 30-minütige Abkühlphase (CIRCUIT_BREAKER_COOLDOWN_MS) auslösen. Beheben Sie den Fehler beim Empfänger und führen Sie POST /api/v1/webhooks/subscriptions/:id/test aus, um den Circuit Breaker zurückzusetzen.

Produktive Code-Beispiele für Node.js, Python, PHP und cURL finden Sie unter Integrations-Hilfsmittel.

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.