Overzicht
Voordat u een Wallet-koppeling openzet voor productieverkeer, kunt u elke API-aanroep, scanregel, idempotentievergrendeling en webhook-handtekening verifiëren met Passinstance-sandboxsleutels (pi_test_...), de Developer Console in het Dashboard (/settings/workspace/developer/*) en onze vooraf ingerichte Bruno API Collection (in docs/bruno/).
Belangrijk: Test pasuitgifte (
.pkpassondertekend metbundleIden Google Wallet Save-link) en dynamische updates altijd op ten minste één fysiek iOS-toestel (Apple Wallet) en één Android-toestel (Google Wallet) vóór livegang. Desktopvoorvertoningen controleren de lay-out, maar fysieke apparaten testen echte APNs-pushvertraging enchangeMessage-weergave op het toegangsscherm.
Workflow voor integratieverificatie & foutopsporing
1. Sandboxsleutels (pi_test_), Dashboard-tools & testpassen
-
Sandbox API-sleutels (
pi_test_<secret>): Aangemaakt viaPOST /api/v1/api-keysmet"environment": "test"(API_KEY_ENVIRONMENT_VALUES) in sandboxwerkruimtes. Ze testen validatie,bundleId-ondertekening en pushwachtrijen zonder productiequota te verbruiken. -
Dashboard Developer Diagnostics: Inspecteer realtime verzoeklogboeken, Bull-achtergrondtaken, systeemgezondheid en API-payloads rechtstreeks in
/settings/workspace/developer/logs,/settings/workspace/developer/jobs,/settings/workspace/developer/system-healthen/settings/workspace/developer/query-helper. -
Health Endpoints (zonder prefix): Poll
GET /health,GET /health/liveness,GET /health/readiness,GET /health/detailedenGET /health/circuit-breakers(alle gemount zonder/api/v1).
2. Bruno API Collection
Passinstance onderhoudt een officiële Bruno API Collection in docs/bruno/ met vooringestelde verzoeken per domeinmap, waaronder:
| Bruno-domeingebied | Gedekte stromen & controles |
|---|---|
Auth & API Keys | Sleutelaanmaak (pi_test_), handhaving van API_KEY_SCOPE_VALUES, rotatie en gebruikstelemetrie. |
Templates & Mechanics | Sjabloon-CRUD, tier-afbeeldingshydratatie, stempelkaarten en instellingen voor opgeslagen waarde. |
Passes & Distribution | Enkele uitgifte (externalId, idempotencyKey), upsert-by-external-id, slimme downloadlinks (/d/:slug, /s/:token) en POST /api/v1/passes/export. |
Scanner Runtime | POST /api/v1/scans/prepare-nonces, POST /api/v1/scans 14-regeltoetsing, /api/v1/scanner-keys/verify en offline datasetsynchronisatie. |
Billing | Voorvertoning van abonnement, planwijzigingen, Stripe SetupIntents en PDF-factuurdownloads. |
Webhooks Inbox | Registratie van pushwebhooks (/api/v1/webhooks/subscriptions), HMAC-verificatietests en polling van Pull Webhook-wachtrij (/webhook-payload). |
Integrations | Zapier/Make OAuth-endpoints (/api/v1/me, /api/v1/webhook-subscriptions) en Shopware/Shopify-hooks. |
Analytics | Tijdreeksqueries (passes/overview, wallet-installations) en CSV-exports. |
3. Idempotentie testen (x-idempotency-key, Idempotency-Key & idempotencyKey)
Muterende endpoints beschermen tegen herhaalde netwerkpogingen via expliciete idempotentiecontracten:
-
POST /api/v1/passes: GeefidempotencyKeymee inrequest payload(ofexternalIdviaPOST /api/v1/passes/upsert-by-external-id). -
POST /api/v1/scans: Stuur headerx-idempotency-key: test-scan-retry-001(Idempotency Engine); herhaling retourneert exact hetzelfderequest payload, opvraagbaar viaGET /api/v1/scans/operations/test-scan-retry-001. -
POST /api/v1/scans/pass/:passId/use: Stuur headerIdempotency-Key(komt overeen met optionele bodyidempotencyKey). -
POST /v1/pos/redeem&POST /api/v1/reader/redeem: StuuridempotencyKeyin de JSON-body (request payload/request payload).
4. Standaard foutenveloppe
Wanneer een verzoek faalt op validatie of rate limiting, retourneert API Error Handler een gestructureerd foutbericht met een correlatie-requestId en machine-leesbare 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-handtekeningen & circuit breakers debuggen
Als uw webhook-endpoint geen gebeurtenissen ontvangt of faalt bij HMAC-validatie:
-
Controleer ruwe body-parsing: Zorg dat uw webframework (Express
express.raw({ type: 'application/json' }), Next.jsawait req.text(), FastAPIawait request.body()) de ongewijzigde ruwe byte-stroom leest vóór JSON-deserialisatie. -
Inspecteer circuit-breakerstatus: Houd er rekening mee dat 10 opeenvolgende antwoorden anders dan
2xxof time-outs (10s) de circuit breaker activeren (CIRCUIT_BREAKER_THRESHOLD = 10) voor een afkoelperiode van 30 minuten (CIRCUIT_BREAKER_COOLDOWN_MS). Verhelp de fout aan de ontvangerszijde en roepPOST /api/v1/webhooks/subscriptions/:id/testaan om het circuit te resetten.
Bekijk kant-en-klare codevoorbeelden voor Node.js, Python, PHP en cURL in Integratiehulpmiddelen.
