Skip to content
Guia da Central de Ajuda · Introdução à PassinstanceFase de integração 1
5 min de leituraVerificado 2026-11-16

Como funciona a Passinstance

Acompanhe o fluxo completo desde o modelo e assinatura digital até à leitura, atualizações push e métricas.

Neste guia

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

Foco ampliado da interface
Elementos-chave da interface

Painel Principal — KPIs ao vivo e Tendências (Ampliado)

Com o fluxo no ar, monitore Active in Wallets, Removed, Not Installed além das curvas de criação e registro.

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:

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
CICLO DE VIDA PONTA A PONTA DO PASSE
ATORES DE SISTEMA PARTICIPANTES
P1 Admin / Cliente API
P2 API Principal Passinstance
P3 Cloud Apple / Google
P4 Dispositivo Cliente
ETAPA 1 PEDIDO / AÇÃO POST/api/v1/templates
›
(Definir Layout e Mecânicas)
ETAPA 2 PEDIDO / AÇÃO POST/api/v1/passes
ETAPA 3 PEDIDO / AÇÃO Assinar .pkpass (PKCS#7)
ETAPA 4 PEDIDO / AÇÃO Gerar JWT Google
›
Devolve URL de Download
›
(https://app.passinstance.com/d/:slug ou /p/:passId)
ETAPA 5 PEDIDO / AÇÃO Cliente Abre Ligação Inteligente de Download
›
(Navegador Deteta SO)
ETAPA 6 RESPOSTA Dispositivo Regista-se (POST/v1/devices)
›
(Apple pushToken guardado no Passinstance database)
ETAPA 7 PEDIDO / AÇÃO Leitura em Balcão no POS (POST/api/v1/scans)
›
(Header: x-scanner-key, Body: { scannedBarcodeValue })
ETAPA 8 PEDIDO / AÇÃO Executar Mecânica
›
(Somar carimbos/pontos)
ETAPA 9 PEDIDO / AÇÃO Enviar Push Silencioso
›
(Payload APNs Vazio)
ETAPA 10 PEDIDO / AÇÃO Acordar APNs
ETAPA 11 RESPOSTA Obter Passe Atualizado (GET/v1/passes)
ETAPA 12 PEDIDO / AÇÃO Entregar Novo .pkpass
›
(Alerta Nativo Ecrã Bloq.
›
"Balance updated to %@")

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 Packager empacota pass.json, até 13 slots de imagem (image asset slot incluindo variantes retina @2x e @3x) e ficheiros localizados pass.strings num pacote zip .pkpass, calcula os hashes de manifest.json e 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 um bundleId (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 JWT RS256 (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/:serialNumber com o cabeçalho Authorization: ApplePass <authenticationToken>.
  • A Passinstance valida o token e regista o pushToken do dispositivo na base de dados, transitando o estado do passe de AWAITING_OPT_IN para ACTIVE.

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/scans autenticado via x-scanner-key.
  • O Pass Mechanics Engine avalia 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 .pkpass atualizado.
  • Qualquer campo configurado com uma changeMessage contendo o marcador %@ gera uma notificação nativa no ecrã bloqueado do iOS.
  • Em simultâneo, a Passinstance envia um pedido REST PATCH ao endpoint walletobjects da Google Wallet, atualizando o cartão Android em tempo real.
Tendências e KPIs da vista geral do painel
Tendências e KPIs da vista geral do painel

Principais endpoints e métodos da API

Caminho do endpointMétodo HTTPAutenticaçãoFuncionalidade
/api/v1/templatesPOSTBearer / Chave APICriar uma nova definição de modelo de passe
/api/v1/templates/:id/publishPOSTBearer / Chave APIPromover modelo em rascunho para a versão de produção ativa
/api/v1/passesPOSTBearer / Chave APIEmitir um novo passe com valores de campos personalizados
/api/v1/passes/:idPATCHBearer / Chave APIAtualizar atributos de um passe existente e colocar push em fila
/api/v1/scansPOSTx-scanner-keyValidar código de barras do passe, aplicar mecânica e registar leitura
/v1/devices/...POSTApplePass <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 .pkpass assinado mais recente a partir dos servidores Passinstance.

Explore o guia completo de integração em 6 fases ou consulte a nossa Arquitetura da API.

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.