Skip to content
Helpcentrum-gids · Ontwikkelaarstools
3 min leestijdGecontroleerd 2026-11-16

Testen & foutopsporing

Controleer API-verkeer met webhooklogs, gestandaardiseerde API-foutcodes en gratis sandbox-testkaarten.

In deze gids

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 (.pkpass ondertekend met bundleId en 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 en changeMessage-weergave op het toegangsscherm.

Workflow voor integratieverificatie & foutopsporing

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
SANDBOXTESTEN, IDEMPOTENTIE & WEBHOOK-DEBUGGEN
DEELNEMENDE SYSTEEMACTOREN
P1 Developer / Bruno CLI
P2 Passinstance API (pi_test_...)
P3 Diagnose- & auditlaag
STAP 1 VERZOEK / ACTIE POST/api/v1/passes
›
Header: x-api-key: pi_test_...
›
Valideert DTO tegen Sjabloon
›
Body: externalId,
›
Ondertekent .pkpass (bundleId)
›
idempotencyKey
›
zendt webhook pass_created
STAP 2 ANTWOORD 201 Created { requestId }
STAP 3 VERZOEK / ACTIE Herhaal POST/api/v1/scans
›
Header: x-idempotency-key: k_01
STAP 4 ANTWOORD 200 OK (Idempotente cache-hit)
STAP 5 VERZOEK / ACTIE Controleer status & logboeken
›
GET/health/detailed
›
/settings/workspace/developer/logs

1. Sandboxsleutels (pi_test_), Dashboard-tools & testpassen

  • Sandbox API-sleutels (pi_test_<secret>): Aangemaakt via POST /api/v1/api-keys met "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-health en /settings/workspace/developer/query-helper.
  • Health Endpoints (zonder prefix): Poll GET /health, GET /health/liveness, GET /health/readiness, GET /health/detailed en GET /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-domeingebiedGedekte stromen & controles
Auth & API KeysSleutelaanmaak (pi_test_), handhaving van API_KEY_SCOPE_VALUES, rotatie en gebruikstelemetrie.
Templates & MechanicsSjabloon-CRUD, tier-afbeeldingshydratatie, stempelkaarten en instellingen voor opgeslagen waarde.
Passes & DistributionEnkele uitgifte (externalId, idempotencyKey), upsert-by-external-id, slimme downloadlinks (/d/:slug, /s/:token) en POST /api/v1/passes/export.
Scanner RuntimePOST /api/v1/scans/prepare-nonces, POST /api/v1/scans 14-regeltoetsing, /api/v1/scanner-keys/verify en offline datasetsynchronisatie.
BillingVoorvertoning van abonnement, planwijzigingen, Stripe SetupIntents en PDF-factuurdownloads.
Webhooks InboxRegistratie van pushwebhooks (/api/v1/webhooks/subscriptions), HMAC-verificatietests en polling van Pull Webhook-wachtrij (/webhook-payload).
IntegrationsZapier/Make OAuth-endpoints (/api/v1/me, /api/v1/webhook-subscriptions) en Shopware/Shopify-hooks.
AnalyticsTijdreeksqueries (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: Geef idempotencyKey mee in request payload (of externalId via POST /api/v1/passes/upsert-by-external-id).
  • POST /api/v1/scans: Stuur header x-idempotency-key: test-scan-retry-001 (Idempotency Engine); herhaling retourneert exact hetzelfde request payload, opvraagbaar via GET /api/v1/scans/operations/test-scan-retry-001.
  • POST /api/v1/scans/pass/:passId/use: Stuur header Idempotency-Key (komt overeen met optionele body idempotencyKey).
  • POST /v1/pos/redeem & POST /api/v1/reader/redeem: Stuur idempotencyKey in 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:

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-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.js await req.text(), FastAPI await 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 2xx of 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 roep POST /api/v1/webhooks/subscriptions/:id/test aan om het circuit te resetten.

Bekijk kant-en-klare codevoorbeelden voor Node.js, Python, PHP en cURL in Integratiehulpmiddelen.

Gerelateerde product- en ontwikkelaarsdocs

Klaar om uw eerste kaartprogramma te lanceren?

Maak uw workspace aan, configureer uw sjabloon en test een echte kaart in Apple Wallet en Google Wallet voordat u opschaalt.