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.

Deteção dinâmica de User-Agent e comportamento por plataforma
-
1
iPhone e iPad (Safari iOS): Transmite diretamente o pacote
.pkpassassinado criptograficamente com o tipo MIMEContent-Type: application/vnd.apple.pkpass, abrindo imediatamente a janela modal nativa do iOS Adicionar à Apple Wallet. -
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 oUser-Agentda 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
Dispositivos Android: Efetua um redirecionamento HTTP
302(ou apresenta um botão de um toque Adicionar à Google Wallet) parahttps://pay.google.com/gp/v/save/<signed_jwt>, provisionando diretamente na Google Wallet o objeto cloudLoyaltyObject,EventTicketObjectouGenericObject. -
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 callbacksaveda 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étodo | Caminho do endpoint | Escopo de autenticação | Descrição técnica |
|---|---|---|---|
| GET | /d/:slug | Público | Roteador 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/info | Público | Devolve metadados JSON (request payload), tokens de marca, passos PassTour e disponibilidade do passe. |
| GET | /d/:slug/qr | Público | Gera uma imagem de código QR legível codificando o URL inteligente de download. |
| GET | /d/:slug/download | Público | Deteta o User-Agent e entrega .pkpass (iOS) ou redirecionamento JWT Google Save (Android); respeita ?pin= ou X-Wallet-Experience-Pin. |
| POST | /d/:slug/create | Pú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-email | Pú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-sms | Público (Limitado por taxa) | request payload ({ phoneNumber, passLink? }) — envia a ligação de download por SMS no formato E.164. |
| POST | /d/:slug/request-recovery | Pú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/:token | Público | Ligaçã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 (
pinna query ou cabeçalhoX-Wallet-Experience-Pin): Exija que os titulares desbloqueiem ligações de download e pacotes.pkpassesprotegidos por PIN antes da instalação na carteira (verificado viaPOST /api/v1/pass-projects/:id/validate-pinnas 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), enquantopass bundle(bundleId) coordena transferências.pkpassesentre 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:
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"
}
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.
