Skip to content
Guia da Central de Ajuda · Ajuda para titulares de passes
4 min de leituraVerificado 2026-11-16

Resolver problemas na Wallet

Desbloqueie ficheiros .pkpass em browsers integrados de redes sociais, alinhe contas Google e melhore leitura QR.

Neste guia

Resolução de Problemas Comuns de Instalação e Leitura

A maioria dos contratempos ao adicionar um cartão ou validá-lo na caixa resulta de browsers integrados em aplicações sociais, contas Google distintas, proteções de transferência (verifyDownloadPin / downloadUntil) ou reflexos no ecrã ao balcão.

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
DIAGNÓSTICO DE TRANSFERÊNCIA E REENCAMINHAMENTO
ETAPA 01 TITULAR ABRE /d/:slug, /download/:slug OU /s/:token
ETAPA 02A INTERCEÇÃO WEBVIEW
Instagram/TikTok iOS bloqueia .pkpass
Indicar toque em
«Abrir no Safari»
ETAPA 02B TRATAMENTO LINK EXPIRADO
Link após downloadUntil
Permite pedir novo link via POST/d/:slug/ request-recovery
ETAPA 02C BARREIRA VERIF. DE PIN
Solicita PIN em /d/:slug e valida verifyDownloadPin com ?pin= / cabeçalho

Referência de Diagnóstico para Proteções de Transferência

Ao investigar por que razão uma ligação inteligente (/d/:slug, /download/:slug ou /s/:token) não abre de imediato o Apple Wallet ou o Google Wallet, verifique o estado da resposta e o mecanismo de proteção ativo:

Sintoma / Comportamento da ProteçãoMecanismo de BackendCausa e Solução para o Titular
«O Safari não consegue transferir este ficheiro» ou ecrã em branco no iPhoneRestrição MIME do WKWebView integradoA ligação foi aberta no Instagram, TikTok, Facebook, LinkedIn ou numa pré-visualização de e-mail. Toque em ... -> Abrir no browser (Safari) para que o iOS instale o .pkpass assinado com bundleId.
O cartão exige um PIN de 4 a 6 dígitosverifyDownloadPin (Public Download Page)O emissor ativou proteção por PIN (pinVerified: false até ser validado). Introduza o PIN na página PassFlow (GET /d/:slug?pin=...) ou na notificação por e-mail/SMS para desbloquear as ligações Wallet.
Ligação expirada (downloadUntil)Validação da marca temporal downloadUntilO token temporário de transferência expirou. Utilize o botão de recuperação na página (POST /d/:slug/request-recovery com { emailOrPhone }) para receber uma nova ligação.
Limite de dispositivos atingido (HTTP 403 Forbidden)limitToOneActivePerPass: trueO cartão já está ativo noutro dispositivo. Remova primeiro o cartão do telemóvel antigo ou peça ao emissor para repor a associação de dispositivo.
Cartão guardado no Android, mas ausente na app Google WalletConta Google distintaO Chrome tinha sessão iniciada numa conta Gmail secundária diferente da conta principal da app Google Wallet. Troque de conta no avatar no canto superior direito da Google Wallet.

Desbloquear uma Página de Transferência Protegida por PIN

Quando um modelo, pacote Wallet Experience ou página de transferência exige verificação de PIN antes de disponibilizar o .pkpass assinado ou o URL do Google Save, Public Download Page valida o PIN através de verifyDownloadPin (aceitando o cabeçalho ou o parâmetro ?pin= em /d/:slug e /d/:slug/download) e retém os URLs de transferência (error=pin_required / pinVerified: false) até ser introduzido um PIN válido na interface da página.

Corrigir Leitura Ótica de Códigos de Barras e NFC na Caixa

Se um leitor de POS ou a câmara de um smartphone de atendimento tiver dificuldade em ler o seu cartão ao balcão:

  1. 1
    Maximize o brilho do ecrã: O Apple Wallet e o Google Wallet aumentam automaticamente a retroiluminação ao apresentar códigos, mas modos agressivos de poupança de bateria podem anular esse ajuste. Aumente o brilho manualmente.
  2. 2
    Evite películas de privacidade escuras: Películas polarizadas reduzem drasticamente o contraste em ângulos inclinados sob iluminação comercial. Mantenha o telemóvel plano e diretamente voltado para o leitor ótico (10–15 cm de distância).
  3. 3
    Aproxime do símbolo NFC sem contacto: Para cartões configurados com Apple VAS ou Google Smart Tap (NFC), encoste a extremidade superior do iPhone ou a zona central traseira do Android ao ícone de ondas do leitor durante 1 segundo e confirme com Face ID / Touch ID / biometria se solicitado.
  4. 4
    Utilize o número de série legível: Todos os cartões com código de barras apresentam um código alternativo (serialNumber ou ID de membro) por baixo do gráfico QR/PDF417/Code128 para que a equipa consulte o cartão via GET /api/v1/scans/pass?barcode=... se o ecrã estiver danificado.

Importante: Se visualizar um indicador de expirado ou anulado no cartão (pass status: VOIDED ou EXPIRED), o cartão já foi resgatado ou ultrapassou o prazo de validade e será rejeitado pelo leitor (ALREADY_VOIDED / PASS_VOIDED_AFTER_SCAN ou EXPIRED).

Ainda precisa de ajuda? Consulte Adicionar um Cartão à Wallet ou entre em contacto em Contactar o Suporte.

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.