Skip to content
Guida del Centro assistenza · Strumenti di sviluppo
3 min di letturaVerificato 2026-11-16

Test e debug

Analizza payload API tramite log webhook, codici di errore API standardizzati e pass di test sul piano gratuito.

In questa guida

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 (.pkpass firmato con bundleId e 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 dei changeMessage nella schermata di blocco.

Flusso di verifica dell'integrazione e debug

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
TEST IN SANDBOX, IDEMPOTENZA E DEBUG WEBHOOK
ATTORI DI SISTEMA COINVOLTI
P1 Sviluppatore / Bruno CLI
P2 API Passinstance (pi_test_...)
P3 Diagnostica e Audit
FASE 1 RICHIESTA / AZIONE POST/api/v1/passes
›
Header: x-api-key: pi_test_...
›
Valida DTO rispetto al Modello
›
Body: externalId,
›
Firma .pkpass (bundleId) e JWT
›
idempotencyKey
›
emette webhook pass_created
FASE 2 RISPOSTA 201 Created { requestId }
FASE 3 RICHIESTA / AZIONE Riprova POST/api/v1/scans
›
Header: x-idempotency-key: k_01
FASE 4 RISPOSTA 200 OK (Cache hit idempotente)
FASE 5 RICHIESTA / AZIONE Ispeziona stato e log
›
GET/health/detailed
›
/settings/workspace/developer/logs

1. Chiavi sandbox (pi_test_), strumenti Dashboard e pass di esempio

  • Chiavi API Sandbox (pi_test_<secret>): Generate tramite POST /api/v1/api-keys con "environment": "test" (API_KEY_ENVIRONMENT_VALUES) nei workspace sandbox. Esercitano validazione, firma bundleId e 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-health e /settings/workspace/developer/query-helper.
  • Endpoint di Health (privi di prefisso): Interroghi GET /health, GET /health/liveness, GET /health/readiness, GET /health/detailed e GET /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 BrunoFlussi e verifiche coperti
Auth & API KeysCreazione chiavi (pi_test_), applicazione di API_KEY_SCOPE_VALUES, rotazione e telemetria d'utilizzo.
Templates & MechanicsCRUD modelli, idratazione asset di livello, tessere a timbri e configurazione valore memorizzato.
Passes & DistributionEmissione singola (externalId, idempotencyKey), upsert-by-external-id, smart link di download (/d/:slug, /s/:token) e POST /api/v1/passes/export.
Scanner RuntimeNonce POST /api/v1/scans/prepare, valutazione a 14 regole POST /api/v1/scans, /api/v1/scanner-keys/verify e sincronizzazione dataset offline.
BillingAnteprima abbonamento, cambio piano, Stripe SetupIntent e download fatture PDF.
Webhooks InboxRegistrazione webhook push (/api/v1/webhooks/subscriptions), test di verifica HMAC e polling su coda Pull Webhook (/webhook-payload).
IntegrationsEndpoint OAuth Zapier/Make (/api/v1/me, /api/v1/webhook-subscriptions) e hook Shopware/Shopify.
AnalyticsQuery 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: Fornisca idempotencyKey in request payload (oppure externalId con POST /api/v1/passes/upsert-by-external-id).
  • POST /api/v1/scans: Invii l'header x-idempotency-key: test-scan-retry-001 (Idempotency Engine); un nuovo invio restituisce l'identico request payload, interrogabile in qualsiasi momento su GET /api/v1/scans/operations/test-scan-retry-001.
  • POST /api/v1/scans/pass/:passId/use: Invii l'header Idempotency-Key (coerente con l'eventuale idempotencyKey nel corpo).
  • POST /v1/pos/redeem e POST /api/v1/reader/redeem: Invii idempotencyKey nel 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:

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. 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.js await req.text(), FastAPI await 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-2xx o 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 esegua POST /api/v1/webhooks/subscriptions/:id/test per ripristinare il circuito.

Per snippet di codice pronti per la produzione in Node.js, Python, PHP e cURL, consulti Utility di integrazione.

Documentazione prodotto e API correlata

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.