Skip to content
Guide du centre d'aide · Outils développeur
4 min de lectureVérifié 2026-11-16

Tests & débogage

Diagnostiquez vos requêtes grâce aux journaux webhooks, codes d'erreur API standardisés et passes de test gratuits.

Dans ce guide

Aperçu

Avant de basculer une intégration Wallet en production, vous pouvez vérifier chaque appel API, règle de scan, verrou d'idempotence et signature webhook grâce aux clés sandbox Passinstance (pi_test_...), à la console développeur du tableau de bord (/settings/workspace/developer/*) et à notre collection API Bruno préconfigurée (dans docs/bruno/).

Important : Testez toujours l'émission des passes (.pkpass signé avec bundleId et lien d'enregistrement Google Wallet) ainsi que les mises à jour dynamiques sur au moins un appareil iOS physique (Apple Wallet) et un appareil Android physique (Google Wallet) avant le lancement. Les aperçus sur ordinateur valident la mise en page, mais l'installation sur téléphone réel vérifie la latence effective des notifications push APNs et le rendu du changeMessage sur l'écran verrouillé.

Workflow de vérification et de débogage

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
TESTS SANDBOX, IDEMPOTENCE & DÉBOGAGE WEBHOOKS
ACTEURS SYSTÈME PARTICIPANTS
P1 Développeur / Bruno CLI
P2 API Passinstance (pi_test_...)
P3 Outils de diagnostic & audit
ÉTAPE 1 REQUÊTE / ACTION POST/api/v1/passes
›
Header: x-api-key: pi_test_...
›
Valide le DTO selon le modèle
›
Body: externalId,
›
Signe .pkpass (bundleId) & JWT
›
idempotencyKey
›
émet webhook pass_created
ÉTAPE 2 RÉPONSE 201 Created { requestId }
ÉTAPE 3 REQUÊTE / ACTION Rejoue POST/api/v1/scans
›
Header: x-idempotency-key: k_01
ÉTAPE 4 RÉPONSE 200 OK (Cache idempotent)
ÉTAPE 5 REQUÊTE / ACTION Inspecte santé & journaux
›
GET/health/detailed
›
/settings/workspace/developer/logs

1. Clés sandbox (pi_test_), outils du tableau de bord et passes de test

  • Clés API sandbox (pi_test_<secret>) : Provisionnées via POST /api/v1/api-keys avec "environment": "test" (API_KEY_ENVIRONMENT_VALUES) dans les espaces sandbox. Elles exécutent la validation, la signature bundleId et les files push sans consommer de quota de production.
  • Diagnostics développeur du tableau de bord : Inspectez en temps réel les journaux de requêtes, les files d'attente Bull en arrière-plan, la santé système et les charges API directement dans /settings/workspace/developer/logs, /settings/workspace/developer/jobs, /settings/workspace/developer/system-health et /settings/workspace/developer/query-helper.
  • Points de terminaison de santé (sans préfixe) : Interrogez GET /health, GET /health/liveness, GET /health/readiness, GET /health/detailed et GET /health/circuit-breakers (tous montés sans /api/v1).

2. Collection API Bruno

Passinstance maintient une collection API Bruno officielle dans docs/bruno/ avec des requêtes préconfigurées classées par domaine :

Domaine BrunoFlux couverts et assertions
Auth & API KeysCréation de clés (pi_test_), contrôle des périmètres API_KEY_SCOPE_VALUES, rotation et télémétrie d'usage.
Templates & MechanicsCRUD des modèles, hydratation des ressources par palier, cartes à tampons et configuration de cartes prépayées.
Passes & DistributionÉmission unitaire (externalId, idempotencyKey), upsert-by-external-id, liens intelligents (/d/:slug, /s/:token) et POST /api/v1/passes/export.
Scanner RuntimeNonces POST /api/v1/scans/prepare, évaluation des 14 règles POST /api/v1/scans, /api/v1/scanner-keys/verify et synchronisation du jeu de données hors ligne.
BillingAperçu d'abonnement, changements de formule, SetupIntents Stripe et téléchargements de factures PDF.
Webhooks InboxEnregistrement de webhooks push (/api/v1/webhooks/subscriptions), tests de vérification HMAC et interrogation de la file pull (/webhook-payload).
IntegrationsPoints de terminaison OAuth Zapier/Make (/api/v1/me, /api/v1/webhook-subscriptions) et hooks Shopware/Shopify.
AnalyticsRequêtes multi-séries par plage temporelle (passes/overview, wallet-installations) et exports CSV.

3. Tester l'idempotence (x-idempotency-key, Idempotency-Key et idempotencyKey)

Les points de terminaison de mutation protègent contre les tentatives réseau répétées via des contrats d'idempotence explicites :

  • POST /api/v1/passes : Fournissez idempotencyKey dans request payload (ou externalId avec POST /api/v1/passes/upsert-by-external-id).
  • POST /api/v1/scans : Envoyez l'en-tête x-idempotency-key: test-scan-retry-001 (Idempotency Engine) ; une nouvelle soumission renvoie exactement le même request payload, consultable à tout moment sur GET /api/v1/scans/operations/test-scan-retry-001.
  • POST /api/v1/scans/pass/:passId/use : Envoyez l'en-tête Idempotency-Key (en cohérence avec le champ optionnel idempotencyKey du corps).
  • POST /v1/pos/redeem & POST /api/v1/reader/redeem : Envoyez idempotencyKey dans le corps JSON de la requête (request payload / request payload).

4. Enveloppe d'erreur standard

Lorsqu'une requête échoue lors de la validation ou du contrôle de débit, API Error Handler renvoie une erreur structurée accompagnée d'un identifiant de corrélation requestId et d'un errorCode exploitable par programme :

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. Déboguer les signatures webhook et les disjoncteurs

Si votre point de terminaison webhook ne reçoit pas d'événements ou échoue lors de la validation HMAC :

  • Vérifiez la lecture du corps brut : Assurez-vous que votre framework web (Express express.raw({ type: 'application/json' }), Next.js await req.text(), FastAPI await request.body()) lit exactement le flux d'octets brut avant toute désérialisation JSON.
  • Inspectez l'état du disjoncteur : Rappelez-vous que 10 réponses consécutives non-2xx ou expirations (10s) déclenchent le disjoncteur du point de terminaison (CIRCUIT_BREAKER_THRESHOLD = 10) pendant une période de refroidissement de 30 minutes (CIRCUIT_BREAKER_COOLDOWN_MS). Corrigez le récepteur puis exécutez POST /api/v1/webhooks/subscriptions/:id/test pour réinitialiser le circuit.

Pour obtenir des exemples de code prêts pour la production en Node.js, Python, PHP et cURL, consultez Utilitaires d'intégration.

Documentation produit et développeur associée

Prêt à lancer votre premier programme de cartes Wallet ?

Créez votre espace de travail, configurez votre modèle et testez une vraie carte dans Apple Wallet et Google Wallet avant de déployer à grande échelle.