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

Conceitos-chave e terminologia

Definições claras de Modelos, Passes, Mecânicas, Atributos, Wallet Experiences (Projetos), PassFlow e Registos ativos.

Neste guia

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

Foco ampliado da interface
Elementos-chave da interface

Propriedades e atributos personalizados (Zoom)

Defina atributos reutilizáveis do cliente ({serviceOrDuration}, {holderName}, {passReference}, {validUntil}, {memberQrToken}) e configure tipos de dados e regras.

Arquitetura central e entidades da plataforma

Para construir fluxos de carteira fiáveis, programadores e administradores devem compreender como a Passinstance organiza modelos, registos dinâmicos de passes, mecânicas de lógica de negócio e estados de registo de dispositivos.

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
RELAÇÕES ENTRE ENTIDADES
ETAPA 01 Template (Esquema Base e Versionamento)
Layout: StoreCard, EventTicket, Coupon, Membership
Cores, Simbologia de Barras, Mapeamento de Campos, Imagens
ETAPA 02 Emissão 1:N | Associação de Regra 1:1
Pass (Instância Concreta)
SerialNumber e AuthToken
Valores Dinâmicos de Campos
Estado e ExpirationDate
Registo de Dispositivo 1:N (Appl
pass mechanic (Motor de Estado)
Tipo: STAMP_CARD_ADD, LOYALTY_PROGRAM, PREPAID_CARD,
VALID_ONCE_PER_DAY ações Google)

Esquema de entidades no backend e mapeamento de modelos Passinstance database

Cada conceito da plataforma corresponde diretamente a uma entidade estruturada no Passinstance database na camada de base de dados do Passinstance API:

ConceitoModelo Passinstance databaseResponsabilidades e atributos armazenados
Modelo (Template)TemplateArmazena a configuração visual, tipo de layout (pass type), relações de ativos (image asset slot), regras de código de barras, expressões regulares de identificador personalizado e versionamento em tabela única (groupId, versionNumber, rowKind: `PRODUCTION \PUBLISHED \ARCHIVED \DRAFT, status`: template status).
PassePassRepresenta um cartão individual emitido. Contém id, serialNumber único, authenticationToken, downloadCode, externalId opcional único por tenant, bundleId (bundleId) opcional, idempotencyKey opcional, attributes em structured JSON, expirationDate, prontidão de artefactos (appleArtifactStatus, googleArtifactStatus) e flags de ciclo de vida/anulação.
Mecânica de Passepass mechanicConfigura regras com estado associadas a um modelo. Armazena mechanicType (mechanic type), minimumValue, maximumValue, defaultChangeValue, patamares (PassTier) e regras de gestão de limites.
Conta Pré-Pagaprepaid accountGere o valor monetário armazenado para cartões-presente e pré-pagos. Mantém unidades inteiras de saldo e associa registos imutáveis de transações prepaid ledger entry.
Pacote de Passes (Bundle)pass bundleAgrupa até 10 passes complementares através de Pass.bundleId (bundle grouping mode: `AUTO \MANUAL, BundleStatus: ACTIVE \CANCELLED) para transferência de ficheiros .pkpasses` multi-cartão.
Experiência WalletPassProjectOrquestra um modelo principal (mainTemplateId) e modelos ligados (PassProjectTemplateRole: `PRIMARY \LINKED \PRIVACY_MODE \INACTIVE \VIP \CUSTOM`), páginas unificadas de obtenção, pacotes, segmentos e fluxos de automação visuais.
PassFlowPassFlowGere páginas de registo self-service em múltiplas etapas (/f/:url, PassFlowType, PassFlowStatus) com formulários personalizáveis, verificação OTP por SMS/E-mail, proteção contra bots (SpamProtectionMode), gateways de pagamento e entrega direta na carteira.
Configuração de ScannerScannerConfigurationConfigura locais físicos de check-in (ValidationPlace), tokens ScannerKey com escopo definido, modos de validação (ScanMode), definições de leitores NFC (NfcReaderMode) e sincronização de conjuntos de dados offline.

Principais identificadores de passes e chaves de correlação

Ao integrar CRMs, checkouts de e-commerce ou backends de bilhética, compreenda o papel exato de cada identificador num Pass:

CampoColuna / Escopo Passinstance databaseMutabilidade e formatoFinalidade principal
idChave primária UUIDGerado pelo sistema, imutávelReferência interna de recurso na API (GET /api/v1/passes/:id).
serialNumberString globalmente únicaGerado pelo sistema (ou personalizado quando configurado), imutávelIdentificador canónico Apple Wallet .pkpass e sufixo de objeto Google.
externalId@unique([customerId, externalId]) onde archivedAt IS NULLString fornecida pelo cliente (máx. 255 carateres)Chave de negócio do seu CRM, POS ou BD de bilhética que permite POST /api/v1/passes/upsert-by-external-id idempotente e pesquisa via GET /api/v1/passes/by-external-id/:externalId.
bundleIdbundleId (chave estrangeira UUID para pass bundle)Gerido pelo sistema via /api/v1/bundles/* ou PassProjectAgrupa até 10 passes num pacote Apple multi-cartão .pkpasses ou experiência unificada de obtenção.
idempotencyKey@unique([customerId, idempotencyKey])Fornecido via cabeçalho Idempotency-Key (<=128 carateres [A-Za-z0-9._:-]+)Previne emissão duplicada se um pedido HTTP POST /api/v1/passes for repetido; verificado via hash SHA-256 do corpo do pedido.
downloadCode / authenticationTokenTokens de segurança por passeStrings criptográficas geradas pelo sistemaCódigo curto público de download e segredo partilhado Authorization: ApplePass <token> do Apple Web Service.

Enums da máquina de estados e mapeamento do ciclo de vida

Os registos de passes transitam por máquinas de estados rigorosas entre enums Passinstance database durante a criação, sincronização com carteiras e anulação/eliminação:

Estado do Passe (pass status)

  • DRAFT: Provisionado como rascunho não emitido e ainda indisponível para instalação pública.
  • AWAITING_OPT_IN: Gerado durante fluxos de registo opt-in/OTP; a aguardar verificação antes da ativação.
  • GENERATING: Em processo de geração assíncrona do passe ou dos artefactos.
  • ACTIVE: Emitido e válido. Disponível para instalação na carteira e validação por scanner.
  • INACTIVE: Temporariamente em pausa/desativado; os scanners rejeitam a validação até ser reativado.
  • EXPIRED: Ultrapassou a sua expirationDate; os scanners rejeitam com motivo PASS_EXPIRED.
  • REDEEMED: Cupão ou vale de utilização única que concluiu o resgate.
  • CANCELLED, SUSPENDED, PENDING_ACTIVATION: Estados especializados de faturação, administrativos e pré-ativação.
  • VOIDED: Revogado ou anulado por um administrador ou regra de leitura; os scanners rejeitam com PASS_VOIDED.

Ciclo de vida do passe, modo de eliminação e prontidão dos artefactos

  • PassLifecycleStatus: Controla transições irreversíveis de anulação e purga:
TEXT
ACTIVE  --->  VOIDING  --->  VOIDED  --->  DELETING  --->  DELETED
  • PassDeletionMode: Distingue entre eliminação lógica (SOFT, preserva o histórico de auditoria e liberta a unicidade de externalId para passes ativos) e remoção permanente (HARD, DELETE /api/v1/passes/:id/hard).
  • ArtifactStatus (appleArtifactStatus e googleArtifactStatus): Acompanha o estado de geração por ecossistema (NOT_GENERATED, GENERATING, READY, FAILED, INVALIDATED).

Estado de anulação e propagação na carteira (walletVoidStatus / WalletPropagationStatus)

Acompanha a propagação assíncrona do estado de anulação/atualização para Apple APNs e Google Wallet no campo Pass.walletVoidStatus:

  • NONE: Sem propagação pendente.
  • PENDING: Estado registado na base de dados; a aguardar entrada na fila.
  • QUEUED: Enviado para os workers background job queue de sincronização de carteiras.
  • SUCCEEDED: Despertar Apple APNs ou PATCH REST da Google confirmado.
  • FAILED: O envio push para a carteira de destino falhou (elegível para repetição automática ou regeneração manual).

Propriedades personalizadas e interpolação dinâmica de tokens

A Passinstance utiliza a sintaxe dinâmica entre chavetas {propertyName} para associar dados de clientes aos campos do cartão:

  • Sintaxe: Coloque {firstName}, {pointsBalance} ou {membershipTier} em qualquer rótulo ou valor de campo principal, secundário, auxiliar ou do verso.
  • Mensagens de alteração (changeMessage): Configure changeMessage: "You earned a stamp! You now have %@ stamps." em campos da Apple Wallet. Quando atualizado, o marcador %@ é substituído pelo novo valor, gerando um aviso imediato no ecrã bloqueado do iOS.
  • Valores atribuídos (Attributed Values): Os campos do verso da Apple Wallet suportam etiquetas HTML de âncora (<a href="https://example.com">Terms</a>) para ligações web clicáveis, números de telefone e endereços de e-mail.

Importante: A capacidade de faturação contabiliza Passes Ativos em Carteira (o número total de dispositivos atualmente registados via Apple APNs ou objetos Google Wallet), e não registos em rascunho não emitidos nem passes expirados.

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.