Ü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 vonchangeMessage.
Ablauf für Integrationsprüfung & Debugging
1. Sandbox-Schlüssel (pi_test_), Dashboard-Tools & Testpässe
-
Sandbox-API-Schlüssel (
pi_test_<secret>): Werden überPOST /api/v1/api-keysmit"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-healthund/settings/workspace/developer/query-helper. -
Health-Endpunkte (präfixfrei): Fragen Sie
GET /health,GET /health/liveness,GET /health/readiness,GET /health/detailedundGET /health/circuit-breakersab (alle ohne/api/v1eingebunden).
2. Bruno API Collection
Passinstance pflegt eine offizielle Bruno API Collection unter docs/bruno/ mit vorkonfigurierten Anfragen über alle Domänenordner hinweg:
| Bruno-Domänenbereich | Abgedeckte Abläufe & Zusicherungen |
|---|---|
Auth & API Keys | Schlüsselerstellung (pi_test_), Durchsetzung von API_KEY_SCOPE_VALUES, Rotation und Nutzungs-Telemetrie. |
Templates & Mechanics | Vorlagen-CRUD, Stufen-Asset-Befüllung, Stempelkarten und Wertguthaben-Konfiguration. |
Passes & Distribution | Einzelausgabe (externalId, idempotencyKey), upsert-by-external-id, Smart-Download-Links (/d/:slug, /s/:token) und POST /api/v1/passes/export. |
Scanner Runtime | POST /api/v1/scans/prepare-Nonces, 14-Regel-Auswertung von POST /api/v1/scans, /api/v1/scanner-keys/verify und Offline-Datensatz-Sync. |
Billing | Abonnement-Vorschau, Tarifwechsel, Stripe-SetupIntents und PDF-Rechnungsdownloads. |
Webhooks Inbox | Push-Webhook-Registrierung (/api/v1/webhooks/subscriptions), HMAC-Prüftests und Pull-Webhook-Warteschlangenabfrage (/webhook-payload). |
Integrations | Zapier-/Make-OAuth-Endpunkte (/api/v1/me, /api/v1/webhook-subscriptions) und Shopware-/Shopify-Hooks. |
Analytics | Mehrteilige 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 SieidempotencyKeyinrequest payload(oderexternalIdmitPOST /api/v1/passes/upsert-by-external-id). -
POST /api/v1/scans: Senden Sie den Headerx-idempotency-key: test-scan-retry-001(Idempotency Engine); bei Wiederholung erhalten Sie das identischerequest payload, jederzeit abrufbar unterGET /api/v1/scans/operations/test-scan-retry-001. -
POST /api/v1/scans/pass/:passId/use: Senden Sie den HeaderIdempotency-Key(passend zu einem optionalenidempotencyKeyim Body). -
POST /v1/pos/redeem&POST /api/v1/reader/redeem: Senden SieidempotencyKeyim 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:
{
"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.jsawait req.text(), FastAPIawait 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 SiePOST /api/v1/webhooks/subscriptions/:id/testaus, um den Circuit Breaker zurückzusetzen.
Produktive Code-Beispiele für Node.js, Python, PHP und cURL finden Sie unter Integrations-Hilfsmittel.
