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 (
.pkpassassinado combundleIde 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 dechangeMessageno ecrã bloqueado.
Fluxo de Verificação de Integrações e Depuração
1. Chaves Sandbox (pi_test_), Ferramentas do Painel e Cartões de Teste
-
Chaves API Sandbox (
pi_test_<secret>): Provisionadas viaPOST /api/v1/api-keyscom"environment": "test"(API_KEY_ENVIRONMENT_VALUES) em espaços de trabalho sandbox. Exercitam validações, assinaturabundleIde 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-healthe/settings/workspace/developer/query-helper. -
Endpoints de Saúde (Sem Prefixo
/api/v1): ConsulteGET /health,GET /health/liveness,GET /health/readiness,GET /health/detailedeGET /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 Bruno | Fluxos e Validações Cobertos |
|---|---|
Auth & API Keys | Criação de chaves (pi_test_), imposição de API_KEY_SCOPE_VALUES, rotação e telemetria de utilização. |
Templates & Mechanics | CRUD de modelos, hidratação de ativos por patamar, cartões de carimbos e saldo pré-pago. |
Passes & Distribution | Emissão individual (externalId, idempotencyKey), upsert-by-external-id, ligações inteligentes (/d/:slug, /s/:token) e POST /api/v1/passes/export. |
Scanner Runtime | Nonces POST /api/v1/scans/prepare, avaliação das 14 regras POST /api/v1/scans, /api/v1/scanner-keys/verify e sincronização offline. |
Billing | Pré-visualização de subscrição, alterações de plano, SetupIntents Stripe e transferência de faturas PDF. |
Webhooks Inbox | Registo de webhooks push (/api/v1/webhooks/subscriptions), testes HMAC e consulta à fila Pull Webhook (/webhook-payload). |
Integrations | Endpoints OAuth Zapier/Make (/api/v1/me, /api/v1/webhook-subscriptions) e hooks Shopware/Shopify. |
Analytics | Consultas 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çaidempotencyKeyemrequest payload(ouexternalIdcomPOST /api/v1/passes/upsert-by-external-id). -
POST /api/v1/scans: Envie o cabeçalhox-idempotency-key: test-scan-retry-001(Idempotency Engine); a repetição devolve orequest payloadidêntico, consultável a qualquer momento emGET /api/v1/scans/operations/test-scan-retry-001. -
POST /api/v1/scans/pass/:passId/use: Envie o cabeçalhoIdempotency-Key(em alinhamento comidempotencyKeyopcional no corpo). -
POST /v1/pos/redeemePOST /api/v1/reader/redeem: EnvieidempotencyKeyno 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:
{
"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.jsawait req.text(), FastAPIawait 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-
2xxou 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 executePOST /api/v1/webhooks/subscriptions/:id/testpara 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.
