Visão geral
A Passinstance automatiza o ciclo de vida de passes digitais desde o design e empacotamento criptográfico até à distribuição multicanal, validação no ponto de venda e sincronização push silenciosa. Ao separar a configuração do layout visual das mecânicas de lógica de negócio e dos protocolos de comunicação com dispositivos, a plataforma proporciona uma experiência uniforme nos ecossistemas iOS e Android.
Sequência técnica ponta a ponta
O diagrama de sequência seguinte detalha o fluxo completo desde a criação do modelo até à sincronização em tempo real na carteira:
Ciclo de vida técnico passo a passo
1. Autoria de modelos e versionamento
Cada passe tem origem num registo Template. A Passinstance utiliza versionamento em tabela única acompanhado por TemplateRowKind (PRODUCTION, PUBLISHED, ARCHIVED, DRAFT) e template status (DRAFT, PUBLISHED, ARCHIVED, DEPRECATED, UNDER_REVIEW, DELETING, DELETED). As edições em rascunho permanecem isoladas numa revisão DRAFT até um operador ou cliente API executar POST /api/v1/templates/:id/publish, promovendo o rascunho para a linha base canónica PRODUCTION e preservando snapshots históricos imutáveis PUBLISHED / ARCHIVED. Antes da publicação, a plataforma avalia GET /api/v1/templates/:id/publish-risk-check para inspecionar alterações em campos críticos e calcular quantos passes ativos serão atualizados.
2. Assinatura criptográfica, estado de artefactos e emissão de passes
Quando um registo de passe é gerado (POST /api/v1/passes), a criação do passe resolve templateId através de resolvePassCreationTemplateId para a linha base ativa, associa um externalId opcional único por tenant, respeita o cabeçalho opcional Idempotency-Key (idempotencyKey) e inicializa appleArtifactStatus e googleArtifactStatus (ArtifactStatus: NOT_GENERATED -> GENERATING -> READY \| FAILED \| INVALIDATED):
-
Apple Wallet: Ao transferir, o
Apple Wallet Packagerempacotapass.json, até 13 slots de imagem (image asset slot incluindo variantes retina@2xe@3x) e ficheiros localizadospass.stringsnum pacote zip.pkpass, calcula os hashes demanifest.jsone assina o manifesto através de encriptação PKCS#7 destacada com os certificados Apple Pass Type ID e Apple WWDR. Múltiplos passes complementares que partilhem umbundleId(Pass.bundleId) podem ser entregues em conjunto como um pacote.pkpasses. -
Google Wallet: O backend sincroniza definições de classe (
LoyaltyClass,EventTicketClass,GenericClass, etc.) com as APIs REST da Google Wallet e assina um URL de gravação JWTRS256(https://pay.google.com/gp/v/save/:jwt).
3. Distribuição por ligações inteligentes
A Passinstance emite URLs canónicos de apresentação inteligente (https://app.passinstance.com/d/:slug, https://app.passinstance.com/p/:passId ou /s/:token em API/domínios próprios). Ao serem acedidos por um utilizador final:
-
O Endpoint Público de Download (
GET /d/:slug/download) deteta o user agent:
- O Safari no iOS recebe uma resposta HTTP com o tipo MIME application/vnd.apple.pkpass, abrindo o ecrã nativo para adicionar à Apple Wallet. - O Chrome no Android é redirecionado para https://pay.google.com/gp/v/save/:jwt, iniciando a Google Wallet. - Os navegadores de computador apresentam a página PassFlow de download com um código QR de alto contraste (GET /d/:slug/qr) e autoenvio opcional por e-mail/SMS.
4. Registo do dispositivo e handshake do Web Service
Ao guardar na Apple Wallet, o dispositivo iOS inicia o protocolo oficial Apple Wallet Web Service:
-
Envia
POST /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumbercom o cabeçalhoAuthorization: ApplePass <authenticationToken>. -
A Passinstance valida o token e regista o
pushTokendo dispositivo na base de dados, transitando o estado do passe deAWAITING_OPT_INparaACTIVE.
5. Validação no ponto de venda e execução de mecânicas
Na caixa física ou no check-in do recinto, um operador lê o passe utilizando a aplicação Passinstance Scanner ou um sistema POS integrado:
-
É enviado um pedido para
POST /api/v1/scansautenticado viax-scanner-key. -
O
Pass Mechanics Engineavalia as regras ativas (por exemplo, adicionar carimbos, deduzir saldo pré-pago, validar cupões de utilização única ou verificar a validação diária).
6. Sincronização push silenciosa na cloud
Quando os dados do passe mudam:
-
A Passinstance envia um payload JSON vazio
{}por HTTP/2 para os servidores Apple APNs. -
O dispositivo Apple acorda silenciosamente em segundo plano, consulta
GET /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier?passesUpdatedSince=<tag>e descarrega o pacote.pkpassatualizado. -
Qualquer campo configurado com uma
changeMessagecontendo o marcador%@gera uma notificação nativa no ecrã bloqueado do iOS. -
Em simultâneo, a Passinstance envia um pedido REST
PATCHao endpointwalletobjectsda Google Wallet, atualizando o cartão Android em tempo real.

Principais endpoints e métodos da API
| Caminho do endpoint | Método HTTP | Autenticação | Funcionalidade |
|---|---|---|---|
/api/v1/templates | POST | Bearer / Chave API | Criar uma nova definição de modelo de passe |
/api/v1/templates/:id/publish | POST | Bearer / Chave API | Promover modelo em rascunho para a versão de produção ativa |
/api/v1/passes | POST | Bearer / Chave API | Emitir um novo passe com valores de campos personalizados |
/api/v1/passes/:id | PATCH | Bearer / Chave API | Atualizar atributos de um passe existente e colocar push em fila |
/api/v1/scans | POST | x-scanner-key | Validar código de barras do passe, aplicar mecânica e registar leitura |
/v1/devices/... | POST | ApplePass <token> | Callback de registo de dispositivo da Apple Wallet |
Importante: As atualizações da Apple Wallet baseiam-se num modelo pull: a Passinstance não envia os dados do passe dentro da notificação APNs. Em vez disso, um sinal APNs vazio de ativação instrui o dispositivo Apple a obter de forma segura o
.pkpassassinado mais recente a partir dos servidores Passinstance.
Explore o guia completo de integração em 6 fases ou consulte a nossa Arquitetura da API.
