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

O que é a Passinstance?

Saiba como a Passinstance fornece cartões Apple Wallet e Google Wallet sem precisar de uma app própria para clientes.

Neste guia

Visão geral

A Passinstance é uma plataforma de infraestrutura de passes para carteiras digitais de nível empresarial, concebida para empresas, programadores e sistemas corporativos. Disponibiliza ferramentas completas para desenhar, assinar criptograficamente, distribuir, atualizar dinamicamente e validar passes digitais nativos na Apple Wallet (iOS e watchOS) e na Google Wallet (Android) sem exigir que os clientes descarreguem ou mantenham uma aplicação móvel personalizada.

Cada passe funciona nativamente na pilha de carteira do sistema operativo. Os utilizadores finais adicionam o cartão com um único toque a partir de uma ligação web, e-mail, SMS ou código QR. Uma vez instalados, os passes apresentam códigos de barras em tempo real ou credenciais NFC sem contacto, recebem notificações push instantâneas quando os saldos ou estados mudam e exibem automaticamente informações relevantes no ecrã bloqueado junto às localizações físicas das lojas.

Arquitetura da plataforma e stack técnico

A plataforma Passinstance assenta numa arquitetura backend modular NestJS de elevada concorrência com filas de processamento assíncronas e conectores cloud para os fornecedores de carteiras digitais:

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
ARQUITETURA DA PLATAFORMA
ETAPA 01 CAMADA DE CLIENTE E INGESTÃO
Painel Admin
(SPA React / Vite)
Ponto de Venda e POS
(Móvel / Web / API)
PassFlow Público
(Registo Self-Service)
ETAPA 02 BACKEND PRINCIPAL PASSINSTANCE (API)
Motor Modular NestJS (apps/api)
Prefixo Global: /api/v1 e Apple Web Service: /v1
Guarda RBAC e Isolamento Multi-Tenant (Organization / Customer)
Motor de Mecânicas (Pass Mechanics Engine, Tier Progression Engine)
Assinador Criptográfico (Apple Wallet Packager PKCS#7 e Gerador JWT Googl
BD database
Esquema Passinstanc
Tenancy Isolado
in-memory cache e ba
Filas
Pipeline APNs
round job queue
Workers | | Ativo
Retina dos Passes
ETAPA 01 REDES CLOUD DAS CARTEIRAS
Apple APNs HTTP/2
Protocolo Gateway
Google Wallet
API Cloud REST
ETAPA 02 DISPOSITIVOS CLIENTE
Apple Wallet
(iOS/watchOS)
Google Wallet
(Android)

Componentes principais do backend

  1. 1
    API Gateway e módulos de domínio: Construído em NestJS, organizando a funcionalidade em módulos de domínio como Template subsystem, Pass subsystem, Pass mechanics subsystem, Scanner subsystem, Onboarding subsystem e Certificate subsystem.
  2. 2
    Passinstance data layer e database: Implementa isolamento estrito por chave estrangeira e atributos structured JSON indexados com índices GIN do database para consultas a campos dinâmicos.
  3. 3
    Pipelines background job queue e in-memory cache: Gere operações em lote assíncronas de elevado débito, incluindo tarefas de geração de passes por CSV, envios em massa de e-mail via managed email delivery e emissões agendadas de notificações push.
  4. 4
    Motor de assinatura criptográfica: Empacota ficheiros Apple .pkpass com assinaturas PKCS#7 destacadas face aos certificados oficiais Apple WWDR G4/G6 e gera tokens JWT assinados para objetos Google Wallet.

Importante: Todos os dados de clientes, modelos e chaves criptográficas de assinatura são alojados na AWS Europa (Frankfurt, eu-central-1) em total conformidade com o RGPD e políticas rigorosas de isolamento multi-tenant.

Duas formas como as equipas utilizam a Passinstance

Consoante os requisitos técnicos, a Passinstance oferece tanto uma suite operacional completa sem código como uma plataforma para programadores compatível com OpenAPI:

Modo operacionalPúblico-alvoCapacidades principais e endpoints de suporte
Painel sem códigoEquipas de marketing, operadores de retalho, clubes de sócios, organizadores de eventosEditor visual drag-and-drop de modelos, emissão em lote por CSV (POST /api/v1/batch-processing), campanhas no Centro de Entrega, emparelhamento de scanner web e móvel.
API REST para programadoresEngenheiros de software, sistemas POS, plataformas CRM e e-commerceCiclo de vida completo programático de passes (/api/v1/passes), verificação de leitura em tempo real (/api/v1/scans), webhooks HMAC-SHA256 bidirecionais push/pull, chaves API com escopo (pi_live_, pi_test_).

Programas de passes e tipos de catálogo suportados

A Passinstance suporta nativamente todos os principais formatos de passes para carteiras digitais definidos pela Apple e pela Google através do pass type no backend:

  • Cartões de fidelização e carimbos (storeCard): Cartões visuais de coleção de carimbos (STAMP_CARD_ADD, STAMP_CARD_DEDUCT) e programas contínuos de recompensas por pontos consoante o valor gasto (LOYALTY_PROGRAM).
  • Cartões de sócio e subscrição (membership / generic / posterGeneric): Credenciais digitais com extensão automática de validade (RENEW_EXPIRATION), miniaturas fotográficas, estilo poster WWDC (posterGeneric) e restrições de partilha via AirDrop.
  • Cupões e vales promocionais (coupon): Passes promocionais de utilização única garantidos por VOIDED_AFTER_SCAN scan mode ou INVALIDATE_AFTER_SCAN para impedir a reutilização de capturas de ecrã.
  • Cartões-presente e saldo pré-pago (storeCard): Contas de valor armazenado (PREPAID_CARD) suportadas por registo contabilístico de partidas dobradas nas unidades monetárias mínimas.
  • Bilhetes de eventos e cartões de embarque (eventTicket / boardingPass): Credenciais de eventos ao vivo com campos de porta/lugar, layouts poster WWDC25 (theme preference), guias de recinto MapKit e regras de check-in em torniquete, ou passes de transporte (transit type: Air, Boat, Bus, Train, Generic).
  • Cartões de colaborador, estudante e cartões de visita digitais (studentId / businessCard / generic): Credenciais de identidade e cartões de contacto interativos com transmissão NFC sem contacto (Apple VAS e Google Smart Tap) e revogação instantânea.

Principais capacidades da plataforma entre backend e frontend

CapacidadeImplementação no backend (Passinstance API)Experiência no frontend (Passinstance Dashboard / scanner)
Correlação com sistemas externos (externalId)Chave opcional única por tenant (externalId, máx. 255 carateres) indexada por passe ativo (archivedAt IS NULL), permitindo sincronização idempotente com CRM via POST /api/v1/passes/upsert-by-external-id.Pesquisável nos filtros da lista /passes, no mapeamento em lote CSV (Bulk Pass Wizard) e no Pass Details panel.
Emissão idempotente (idempotencyKey)Cabeçalho HTTP Idempotency-Key (<=128 carateres [A-Za-z0-9._:-]+) guardado com verificação SHA-256 do payload do pedido para evitar criação duplicada em novas tentativas de rede.Gerado automaticamente por assistentes e SDKs resilientes a novas tentativas; inspecionável nos registos de API do passe.
Agrupamento multi-cartão (bundleId)Pass.bundleId (bundleId) associa até 10 passes complementares num pacote Apple Wallet .pkpasses através de pass bundle (bundle grouping mode: AUTO \MANUAL).Gerido através de PassProject (Wallet Experiences -> separador Bundle) ou seleção em lote em /bundles/:id.
Mecânicas de passe e scannersmechanic type, ScanMode, StoredValueOperation e nonces protegidos contra repetição em POST /api/v1/scans.Validação pelo operador via web scanner (/scanner), app móvel Passinstance Scanner (iOS/Android/Expo com fila offline) ou POS externo (/v1/pos/redeem).

Medição de capacidade e invariantes de alojamento

A Passinstance mede a capacidade da subscrição através de Passes Ativos em Carteira (a contagem de passes atualmente instalados nos dispositivos dos clientes e ligados aos endpoints push APNs ou Google Wallet). Registos em rascunho, passes eliminados e ligações de download não instaladas não consomem quota ativa da subscrição.

Explore a nossa Visão geral da plataforma e saiba mais sobre Mecânicas e funcionalidades de passes.

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.