Skip to content
Guia da Central de Ajuda · Ferramentas de desenvolvimento
3 min de leituraVerificado 2026-11-16

Testes e depuração

Inspecione pedidos API com registos webhook, códigos de erro API padronizados e passes de teste no plano gratuito.

Neste guia

Visão geral

Antes de colocar uma integração Wallet em tráfego de produção, pode validar cada chamada à API, regra de leitura, bloqueio de idempotência e assinatura webhook utilizando chaves sandbox do Passinstance (pi_test_...), a Consola de Programadores do Painel (/settings/workspace/developer/*) e a nossa Coleção Bruno API pré-configurada (em docs/bruno/).

Importante: Teste sempre a emissão de cartões (.pkpass assinado com bundleId e ligação Google Wallet Save) bem como atualizações dinâmicas em pelo menos um dispositivo físico iOS (Apple Wallet) e um Android (Google Wallet) antes do lançamento. As pré-visualizações no computador validam a estrutura visual, mas a instalação física confirma latência real APNs e apresentação de changeMessage no ecrã bloqueado.

Fluxo de Verificação de Integrações e Depuração

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
TESTES SANDBOX, IDEMPOTÊNCIA E DEPURAÇÃO DE WEBHOOKS
ATORES DE SISTEMA PARTICIPANTES
P1 Programador / Bruno CLI
P2 API Passinstance (pi_test_...)
P3 Diagnóstico e Auditoria
ETAPA 1 PEDIDO / AÇÃO POST/api/v1/passes
›
Header: x-api-key: pi_test_...
›
Valida DTO face ao Modelo
›
Body: externalId,
›
Assina .pkpass (bundleId) e JWT
›
idempotencyKey
›
emite webhook pass_created
ETAPA 2 RESPOSTA 201 Created { requestId }
ETAPA 3 PEDIDO / AÇÃO Repetir POST/api/v1/scans
›
Header: x-idempotency-key: k_01
ETAPA 4 RESPOSTA 200 OK (Acerto cache idempot.)
ETAPA 5 PEDIDO / AÇÃO Inspecionar Saúde e Registos
›
GET/health/detailed
›
/settings/workspace/developer/logs

1. Chaves Sandbox (pi_test_), Ferramentas do Painel e Cartões de Teste

  • Chaves API Sandbox (pi_test_<secret>): Provisionadas via POST /api/v1/api-keys com "environment": "test" (API_KEY_ENVIRONMENT_VALUES) em espaços de trabalho sandbox. Exercitam validações, assinatura bundleId e filas push sem consumir quotas de produção.
  • Diagnósticos do Painel de Programadores: Inspecione registos de pedidos em tempo real, filas Bull em segundo plano, estado do sistema e payloads da API diretamente em /settings/workspace/developer/logs, /settings/workspace/developer/jobs, /settings/workspace/developer/system-health e /settings/workspace/developer/query-helper.
  • Endpoints de Saúde (Sem Prefixo /api/v1): Consulte GET /health, GET /health/liveness, GET /health/readiness, GET /health/detailed e GET /health/circuit-breakers.

2. Coleção Bruno API

O Passinstance mantém uma Coleção Bruno API oficial em docs/bruno/ com pedidos pré-configurados organizados por pasta de domínio, incluindo:

Domínio BrunoFluxos e Validações Cobertos
Auth & API KeysCriação de chaves (pi_test_), imposição de API_KEY_SCOPE_VALUES, rotação e telemetria de utilização.
Templates & MechanicsCRUD de modelos, hidratação de ativos por patamar, cartões de carimbos e saldo pré-pago.
Passes & DistributionEmissão individual (externalId, idempotencyKey), upsert-by-external-id, ligações inteligentes (/d/:slug, /s/:token) e POST /api/v1/passes/export.
Scanner RuntimeNonces POST /api/v1/scans/prepare, avaliação das 14 regras POST /api/v1/scans, /api/v1/scanner-keys/verify e sincronização offline.
BillingPré-visualização de subscrição, alterações de plano, SetupIntents Stripe e transferência de faturas PDF.
Webhooks InboxRegisto de webhooks push (/api/v1/webhooks/subscriptions), testes HMAC e consulta à fila Pull Webhook (/webhook-payload).
IntegrationsEndpoints OAuth Zapier/Make (/api/v1/me, /api/v1/webhook-subscriptions) e hooks Shopware/Shopify.
AnalyticsConsultas temporais multissérie (passes/overview, wallet-installations) e exportações CSV.

3. Testar Idempotência (x-idempotency-key, Idempotency-Key e idempotencyKey)

Os endpoints de escrita protegem contra repetições de rede mediante contratos explícitos de idempotência:

  • POST /api/v1/passes: Forneça idempotencyKey em request payload (ou externalId com POST /api/v1/passes/upsert-by-external-id).
  • POST /api/v1/scans: Envie o cabeçalho x-idempotency-key: test-scan-retry-001 (Idempotency Engine); a repetição devolve o request payload idêntico, consultável a qualquer momento em GET /api/v1/scans/operations/test-scan-retry-001.
  • POST /api/v1/scans/pass/:passId/use: Envie o cabeçalho Idempotency-Key (em alinhamento com idempotencyKey opcional no corpo).
  • POST /v1/pos/redeem e POST /api/v1/reader/redeem: Envie idempotencyKey no corpo JSON (request payload / request payload).

4. Envelope Padrão de Erro

Quando um pedido falha por validação ou limite de taxa, API Error Handler devolve uma resposta estruturada com requestId de correlação e errorCode legível por máquina:

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. Depurar Assinaturas Webhook e Disjuntores (Circuit Breakers)

Se o seu endpoint webhook não recebe eventos ou falha na validação HMAC:

  • Verifique a Leitura do Corpo Bruto: Garanta que a sua framework (Express express.raw({ type: 'application/json' }), Next.js await req.text(), FastAPI await request.body()) lê exatamente os bytes brutos antes da desserialização JSON.
  • Inspecione o Estado do Circuit Breaker: Lembre-se de que 10 respostas consecutivas não-2xx ou timeouts (10s) disparam o disjuntor do endpoint (CIRCUIT_BREAKER_THRESHOLD = 10) durante uma pausa de 30 minutos (CIRCUIT_BREAKER_COOLDOWN_MS). Corrija o recetor e execute POST /api/v1/webhooks/subscriptions/:id/test para repor o circuito.

Para exemplos de código prontos para produção em Node.js, Python, PHP e cURL, consulte Utilitários de Integração.

Documentação de produto e API relacionada

Pronto para lançar o seu primeiro programa de cartões Wallet?

Crie o seu espaço de trabalho, configure o seu modelo e teste um cartão real na Apple Wallet e Google Wallet antes de escalar.