Panoramica
Prima di indirizzare traffico di produzione su un'integrazione Wallet pass, è possibile verificare ogni chiamata API, regola di scansione, blocco di idempotenza e firma webhook utilizzando le chiavi sandbox Passinstance (pi_test_...), la Console Sviluppatore nella Dashboard (/settings/workspace/developer/*) e la nostra Collezione API Bruno preconfigurata (sotto docs/bruno/).
Importante: Testi sempre l'emissione del pass (
.pkpassfirmato conbundleIde link di salvataggio Google Wallet) e gli aggiornamenti dinamici su almeno un dispositivo fisico iOS (Apple Wallet) e un dispositivo Android (Google Wallet) prima del lancio. Le anteprime desktop convalidano la struttura del layout, ma l'installazione su dispositivo fisico verifica la latenza reale delle push APNs e la visualizzazione deichangeMessagenella schermata di blocco.
Flusso di verifica dell'integrazione e debug
1. Chiavi sandbox (pi_test_), strumenti Dashboard e pass di esempio
-
Chiavi API Sandbox (
pi_test_<secret>): Generate tramitePOST /api/v1/api-keyscon"environment": "test"(API_KEY_ENVIRONMENT_VALUES) nei workspace sandbox. Esercitano validazione, firmabundleIde code push senza consumare le quote di produzione. -
Diagnostica sviluppatore nella Dashboard: Ispezioni log richieste in tempo reale, code in background Bull, stato del sistema e payload API direttamente all'interno di
/settings/workspace/developer/logs,/settings/workspace/developer/jobs,/settings/workspace/developer/system-healthe/settings/workspace/developer/query-helper. -
Endpoint di Health (privi di prefisso): Interroghi
GET /health,GET /health/liveness,GET /health/readiness,GET /health/detailedeGET /health/circuit-breakers(tutti esposti senza/api/v1).
2. Collezione API Bruno
Passinstance mantiene una Collezione API Bruno ufficiale in docs/bruno/ con richieste preconfigurate organizzate per cartelle di dominio, tra cui:
| Area di dominio Bruno | Flussi e verifiche coperti |
|---|---|
Auth & API Keys | Creazione chiavi (pi_test_), applicazione di API_KEY_SCOPE_VALUES, rotazione e telemetria d'utilizzo. |
Templates & Mechanics | CRUD modelli, idratazione asset di livello, tessere a timbri e configurazione valore memorizzato. |
Passes & Distribution | Emissione singola (externalId, idempotencyKey), upsert-by-external-id, smart link di download (/d/:slug, /s/:token) e POST /api/v1/passes/export. |
Scanner Runtime | Nonce POST /api/v1/scans/prepare, valutazione a 14 regole POST /api/v1/scans, /api/v1/scanner-keys/verify e sincronizzazione dataset offline. |
Billing | Anteprima abbonamento, cambio piano, Stripe SetupIntent e download fatture PDF. |
Webhooks Inbox | Registrazione webhook push (/api/v1/webhooks/subscriptions), test di verifica HMAC e polling su coda Pull Webhook (/webhook-payload). |
Integrations | Endpoint OAuth Zapier/Make (/api/v1/me, /api/v1/webhook-subscriptions) e hook Shopware/Shopify. |
Analytics | Query su intervalli temporali multiserie (passes/overview, wallet-installations) ed esportazioni CSV. |
3. Testare l'idempotenza (x-idempotency-key, Idempotency-Key e idempotencyKey)
Gli endpoint modificanti proteggono dai nuovi tentativi di rete tramite contratti di idempotenza espliciti:
-
POST /api/v1/passes: ForniscaidempotencyKeyinrequest payload(oppureexternalIdconPOST /api/v1/passes/upsert-by-external-id). -
POST /api/v1/scans: Invii l'headerx-idempotency-key: test-scan-retry-001(Idempotency Engine); un nuovo invio restituisce l'identicorequest payload, interrogabile in qualsiasi momento suGET /api/v1/scans/operations/test-scan-retry-001. -
POST /api/v1/scans/pass/:passId/use: Invii l'headerIdempotency-Key(coerente con l'eventualeidempotencyKeynel corpo). -
POST /v1/pos/redeemePOST /api/v1/reader/redeem: InviiidempotencyKeynel corpo JSON della richiesta (request payload/request payload).
4. Envelope di errore standard
Quando una richiesta non supera la validazione o il rate limiting, API Error Handler restituisce un payload di errore strutturato con requestId di correlazione e errorCode leggibile dalle applicazioni:
{
"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. Debug delle firme webhook e dei Circuit Breaker
Se il proprio endpoint webhook non riceve eventi o non supera la validazione HMAC:
-
Verifichi l'analisi del raw body: Si assicuri che il framework web (Express
express.raw({ type: 'application/json' }), Next.jsawait req.text(), FastAPIawait request.body()) legga esattamente lo stream di byte grezzo prima della deserializzazione JSON. -
Ispezioni lo stato del Circuit Breaker: Tenga presente che 10 risposte consecutive non-
2xxo timeout (10s) aprono il circuit breaker dell'endpoint (CIRCUIT_BREAKER_THRESHOLD = 10) per un intervallo di raffreddamento di 30 minuti (CIRCUIT_BREAKER_COOLDOWN_MS). Corregga l'anomalia sul ricevente ed eseguaPOST /api/v1/webhooks/subscriptions/:id/testper ripristinare il circuito.
Per snippet di codice pronti per la produzione in Node.js, Python, PHP e cURL, consulti Utility di integrazione.
