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

Resolução de problemas e FAQs

Resolva bloqueios de publicação, erros CSV, divergências na pré-visualização, atrasos push e códigos de erro.

Neste guia

Formato Padronizado de Erro da API

Todos os endpoints REST da Passinstance API formatam exceções através do filtro global API Error Handler. Quando uma chamada à API, configuração de webhook ou transação de leitura falha, analise a resposta JSON estruturada para identificar a causa exata e o requestId de correlação:

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
GESTÃO DE EXCEÇÕES E LOCALIZAÇÃO
ETAPA 01 PEDIDO RECEBIDO (/api/v1/passes ou /api/v1/scans, Accept-Language: pt-PT)
ETAPA 02 EXCEÇÃO DE DOMÍNIO / VALIDAÇÃO DISPARADA
Anexa errorCode estruturado e CLIENT_SAFE_EXTENSION_KEYS
ETAPA 03 API Error Handler GLOBAL E Error Catalog
Resolve message localizada a partir de messageKey e Accept-Language
Injeta requestId, timestamp, path, retryAfter e details

Esquema Padrão de Resposta de Erro

JSON
{
  "success": false,
  "error": "BAD_REQUEST",
  "messageKey": "api.errors.passLimitReached",
  "message": "Active wallet pass limit reached for your current subscription plan.",
  "statusCode": 400,
  "timestamp": "2026-11-16T09:20:00.000Z",
  "path": "/api/v1/passes",
  "requestId": "req_8f192b0e4c12",
  "retryAfter": 60,
  "code": "LIMIT_EXCEEDED",
  "errorCode": "PASS_LIMIT_REACHED",
  "details": [
    {
      "activePasses": 1000,
      "limit": 1000,
      "upgradeRequired": true
    }
  ]
}

Resoluções Comuns de errorCode

Consulte a tabela seguinte para resolver códigos de erro frequentes devolvidos em errorCode ou reasonCode in the scan response:

errorCode / reasonCodeEstado HTTP / LeituraCausa RaizResolução
PASS_LIMIT_REACHED400 / 402O espaço de trabalho atingiu a quota de installedDevices do plano atual.Atualize o plano via POST /api/v1/billing/subscription/change ou limpe cartões inativos.
PASS_VOIDED_AFTER_SCANREJECTED (ALREADY_VOIDED)Um cupão ou bilhete de utilização única (VOIDED_AFTER_SCAN scan mode) já foi resgatado.Bloqueio antifraude esperado; consulte o estado anterior via GET /api/v1/scans/pass?barcode=... (correspondência por serialNumber ou externalId).
OUT_OF_BALANCEREJECTED (FAILED)O débito de saldo pré-pago excede o montante restante com disallowNegativeBalance: true.Carregue o saldo via /public/reload-sessions/:sessionId/initialize ou POST /api/v1/passes/:id/adjust-value.
INVALID_SCANNER_KEY401 / 403O cabeçalho x-scanner-key está em falta, expirou ou foi revogado.Verifique o estado da chave via GET /api/v1/scanner-keys/verify ou rode-a com POST /api/v1/scanner-keys/:id/rotate.

Guia Rápido de Diagnóstico

1. O Modelo Não Publica

  • Execute a Verificação de Risco Pré-Publicação: Invoque GET /api/v1/templates/:id/publish-risk-check para inspecionar blockers e warnings estruturados antes de chamar POST /api/v1/templates/:id/publish.
  • Verifique a Assinatura Apple e bundleId: Confirme que existe um certificado .p12 Apple Pass Type ID válido e não expirado correspondente ao bundleId (passTypeIdentifier) do modelo atribuído ao espaço de trabalho (/api/v1/certificates).
  • Verifique a Sintaxe de Cores e Códigos de Barras: Confirme a formatação rgb(r, g, b) no Apple Wallet e garanta que os modelos de código de barras referenciam apenas chaves de campo existentes sem chavetas abertas.

2. A Atualização em Tempo Real Não Apareceu no Telemóvel

  • Verifique o Registo do Dispositivo: Apenas cartões com estado Ativo em Wallets (installedDevices > 0) mantêm um canal push APNs ou Google Wallet ativo. Cartões não instalados (unclaimedPasses) não podem receber notificações push.
  • Verifique a Alteração de Valor (changeMessage): O Apple Wallet apresenta um alerta no ecrã bloqueado apenas quando um campo com um changeMessage válido (incluindo %@) muda para um valor textual diferente. Guardar a mesma string suprime o alerta.

3. A Importação CSV em Lote Rejeitou Linhas

  • Valide o ficheiro CSV via POST /api/v1/batch-processing/:id/validate antes de iniciar a execução (POST /api/v1/batch-processing/:id/start). Confirme a codificação UTF-8, alinhe os cabeçalhos das colunas com as chaves de campo do modelo e remova linhas duplicadas de serialNumber ou externalId.

Importante: Registe sempre o requestId devolvido no envelope JSON de erro (ex.: req_8f192b0e4c12) ao escalar uma ocorrência para Contactar o Suporte.

Explore mais respostas sobre a plataforma na Visão Geral de Suporte.

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.