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 (
.pkpasssigné avecbundleIdet 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 duchangeMessagesur l'écran verrouillé.
Workflow de vérification et de débogage
1. Clés sandbox (pi_test_), outils du tableau de bord et passes de test
-
Clés API sandbox (
pi_test_<secret>) : Provisionnées viaPOST /api/v1/api-keysavec"environment": "test"(API_KEY_ENVIRONMENT_VALUES) dans les espaces sandbox. Elles exécutent la validation, la signaturebundleIdet 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-healthet/settings/workspace/developer/query-helper. -
Points de terminaison de santé (sans préfixe) : Interrogez
GET /health,GET /health/liveness,GET /health/readiness,GET /health/detailedetGET /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 Bruno | Flux couverts et assertions |
|---|---|
Auth & API Keys | Cré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 & Mechanics | CRUD 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 Runtime | Nonces 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. |
Billing | Aperçu d'abonnement, changements de formule, SetupIntents Stripe et téléchargements de factures PDF. |
Webhooks Inbox | Enregistrement de webhooks push (/api/v1/webhooks/subscriptions), tests de vérification HMAC et interrogation de la file pull (/webhook-payload). |
Integrations | Points de terminaison OAuth Zapier/Make (/api/v1/me, /api/v1/webhook-subscriptions) et hooks Shopware/Shopify. |
Analytics | Requê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: FournissezidempotencyKeydansrequest payload(ouexternalIdavecPOST /api/v1/passes/upsert-by-external-id). -
POST /api/v1/scans: Envoyez l'en-têtex-idempotency-key: test-scan-retry-001(Idempotency Engine) ; une nouvelle soumission renvoie exactement le mêmerequest payload, consultable à tout moment surGET /api/v1/scans/operations/test-scan-retry-001. -
POST /api/v1/scans/pass/:passId/use: Envoyez l'en-têteIdempotency-Key(en cohérence avec le champ optionnelidempotencyKeydu corps). -
POST /v1/pos/redeem&POST /api/v1/reader/redeem: EnvoyezidempotencyKeydans 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 :
{
"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.jsawait req.text(), FastAPIawait 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-
2xxou 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écutezPOST /api/v1/webhooks/subscriptions/:id/testpour 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.
