Skip to content
Guia da Central de Ajuda · Distribuição de passesFase de integração 5
5 min de leituraVerificado 2026-11-16

Links de download e PassFlow

Personalize páginas PassFlow com deteção automática de SO, guias PassTour, proteção por PIN, limites e pausa rápida.

Neste guia

Inspecione capturas de ecrã exatas do painel e detalhes ampliados relacionados com este guia.

Foco ampliado da interface1 / 2
Elementos-chave da interface

Limites de emissão e controlos de acesso (Zoom)

Configure emissão ilimitada ou limitada, canais de acesso, encaminhamento de Wallet e proteções como bloquear nova transferência após ativação e desduplicar destinatários.

Visão geral e arquitetura de endpoints inteligentes

Cada passe emitido e ligação de distribuição de modelo na Passinstance resolve-se através de um Motor de Download Inteligente sensível à plataforma (modelo DownloadPage e Download Page API). Em vez de distribuir ligações separadas para Apple e Android, partilha um único URL canónico (passAccessUrl, /d/:slug ou /s/:token) que inspeciona dinamicamente o cabeçalho User-Agent HTTP do cliente, o contexto do navegador e o estado de segurança antes de entregar o payload de carteira adequado.

Interruptores de acesso à distribuição e salvaguardas de ligação
Interruptores de acesso à distribuição e salvaguardas de ligação
FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
ENCAMINHAMENTO DE DOWNLOAD INTELIGENTE E ENTREGA POR SO
ETAPA 01 PEDIDO HTTP GET RECEBIDO DO CLIENTE
GET/d/:slug | GET/download/:slug | GET/s/:token
ETAPA 02 GUARDA DE ACESSO E PIPELINE DE VALIDAÇÃO DE TOKEN
1
Verifica Estado Passe/Modelo (ACTIVE, passDownloadDeactivated = false)
2
Verifica Prazo e Bloqueio (enableDownloadUntil, limitToOneActivePerPass)
3
Avalia Desafio de PIN (?pin= / X-Wallet-Experience-Pin quando ativo)
Safari iOS / WebKit
ETAPA 03A Transmite ZIP .pkpass
Content-Type: application/vnd.apple. pkpass
Chrome Android
ETAPA 03B Redireciona 302
p/ JWT Google Ass. pay.google.com/ gp/v/save/<jwt>
Computador / WebView App
ETAPA 03C Renderiza PassFlow +
Código QR Dinâmico (GET/d/:slug/qr) +
E-mail/SMS e PassTour

Deteção dinâmica de User-Agent e comportamento por plataforma

  1. 1
    iPhone e iPad (Safari iOS): Transmite diretamente o pacote .pkpass assinado criptograficamente com o tipo MIME Content-Type: application/vnd.apple.pkpass, abrindo imediatamente a janela modal nativa do iOS Adicionar à Apple Wallet.
  2. 2
    WebViews incorporadas em apps iOS (Instagram, TikTok, Facebook, LinkedIn): Como as webviews de redes sociais bloqueiam streams binários application/vnd.apple.pkpass, a Passinstance deteta o User-Agent da app incorporada e apresenta uma sobreposição dedicada de encaminhamento para o Safari, instruindo o titular a abrir a ligação no Safari nativo.
  3. 3
    Dispositivos Android: Efetua um redirecionamento HTTP 302 (ou apresenta um botão de um toque Adicionar à Google Wallet) para https://pay.google.com/gp/v/save/<signed_jwt>, provisionando diretamente na Google Wallet o objeto cloud LoyaltyObject, EventTicketObject ou GenericObject.
  4. 4
    Navegadores de computador: Apresenta uma página PassFlow responsiva com a marca contendo um código QR dinâmico de elevado contraste (GET /d/:slug/qr) juntamente com controlos self-service de reenvio por e-mail/SMS (POST /d/:slug/send-link-by-email, POST /d/:slug/send-link-by-sms) para que utilizadores de computador transfiram o passe para o smartphone em segundos.

Importante: Quando a Vinculação a Dispositivo Único (limitToOneActivePerPass: true) está ativa num modelo ou passe (sharingProhibited), a ligação inteligente de download bloqueia automaticamente assim que um dispositivo conclui o seu primeiro registo no Apple Wallet Web Service (POST /v1/devices/:deviceLibraryIdentifier/registrations/...) ou callback save da Google Wallet, impedindo a partilha não autorizada da ligação.

Endpoints da API de ligações inteligentes e páginas de download

As rotas públicas de resolução de download estão montadas fora do prefixo /api/v1 em Public Download Page e Public Pass Recovery API (/d/:slug/* e alias /download/:slug/*, além das rotas autenticadas de gestão em /api/v1/download-pages/*):

MétodoCaminho do endpointEscopo de autenticaçãoDescrição técnica
GET/d/:slugPúblicoRoteador inicial de ligação inteligente; redireciona navegadores para /download/:slug ou devolve informação JSON quando pedido; suporta ?pass=:passId, ?lang=, ?pin=.
GET/d/:slug/infoPúblicoDevolve metadados JSON (request payload), tokens de marca, passos PassTour e disponibilidade do passe.
GET/d/:slug/qrPúblicoGera uma imagem de código QR legível codificando o URL inteligente de download.
GET/d/:slug/downloadPúblicoDeteta o User-Agent e entrega .pkpass (iOS) ou redirecionamento JWT Google Save (Android); respeita ?pin= ou X-Wallet-Experience-Pin.
POST/d/:slug/createPúblico (Limitado por taxa)Emite um passe diretamente a partir de uma página de download (request payload: name, email?, phone?, additionalFields?).
POST/d/:slug/send-link-by-emailPúblico (Limitado por taxa)request payload ({ email, passLink? }) — envia a ligação de download por e-mail ao utilizador a partir de vistas desktop.
POST/d/:slug/send-link-by-smsPúblico (Limitado por taxa)request payload ({ phoneNumber, passLink? }) — envia a ligação de download por SMS no formato E.164.
POST/d/:slug/request-recoveryPúblico (Limitado por taxa){ emailOrPhone } — envia uma ligação mágica de recuperação quando o cliente muda de telemóvel ou perde a ligação.
GET/s/:tokenPúblicoLigação inteligente canónica associada ao serialNumber / token de um passe individual.

Segurança de tokens, proteção por PIN e entrega secundária

Pode configurar proteções de acesso granulares tanto ao nível do modelo como em cada emissão individual de passe:

  • Expiração do download (enableDownloadUntil): Imponha uma data/hora "YYYY-MM-DD HH:mm" ou carimbo temporal ISO após o qual ligações de download não reclamadas deixam de emitir novos passes, mantendo ativos os passes já instalados nas carteiras dos clientes.
  • Bloqueio a um único dispositivo ativo (limitToOneActivePerPass): Bloqueia novas transferências assim que o passe tiver um registo ativo de dispositivo.
  • Bloqueio por PIN (pin na query ou cabeçalho X-Wallet-Experience-Pin): Exija que os titulares desbloqueiem ligações de download e pacotes .pkpasses protegidos por PIN antes da instalação na carteira (verificado via POST /api/v1/pass-projects/:id/validate-pin nas Wallet Experiences).
  • Pausar todos os downloads (passDownloadDeactivated): Interruptor de emergência nas Definições do Modelo que suspende novas transferências em todos os canais sem revogar os passes já instalados nos dispositivos dos clientes.
  • Prioridade de resolução do passe (?pass=:passId): A resolução pública avalia a disponibilidade específica do passe (P1), predefinições da página de download (P2) e fallback do espaço de trabalho (P3), enquanto pass bundle (bundleId) coordena transferências .pkpasses entre cartões associados.
  • Sobreposições opcionais PassTour: Oriente os utilizadores iniciantes de Apple e Google Wallet com instruções visuais interativas (Guia PassTour).

Exemplo: Payloads de entrega secundária e recuperação

Quando um cliente visualiza um passe num computador ou perde o acesso ao passe na carteira, a página PassFlow chama os endpoints públicos de ação:

JSON
POST /d/vip-gold-2026/send-link-by-email
{
  "email": "alex.rivera@example.com",
  "passLink": "https://app.passinstance.com/d/vip-gold-2026?pass=pass_01j8k9m2"
}
JSON
POST /d/vip-gold-2026/request-recovery
{
  "emailOrPhone": "alex.rivera@example.com"
}

Explore documentação relacionada em Distribuição em autoatendimento, Envio por e-mail e SMS e Encontrar ou recuperar o seu passe.

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.