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.
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:
| Conceito | Modelo Passinstance database | Responsabilidades e atributos armazenados | |||||
|---|---|---|---|---|---|---|---|
| Modelo (Template) | Template | Armazena 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). | ||
| Passe | Pass | Representa 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 Passe | pass mechanic | Configura 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é-Paga | prepaid account | Gere 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 bundle | Agrupa 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 Wallet | PassProject | Orquestra 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. |
| PassFlow | PassFlow | Gere 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 Scanner | ScannerConfiguration | Configura 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:
| Campo | Coluna / Escopo Passinstance database | Mutabilidade e formato | Finalidade principal |
|---|---|---|---|
id | Chave primária UUID | Gerado pelo sistema, imutável | Referência interna de recurso na API (GET /api/v1/passes/:id). |
serialNumber | String globalmente única | Gerado pelo sistema (ou personalizado quando configurado), imutável | Identificador canónico Apple Wallet .pkpass e sufixo de objeto Google. |
externalId | @unique([customerId, externalId]) onde archivedAt IS NULL | String 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. |
bundleId | bundleId (chave estrangeira UUID para pass bundle) | Gerido pelo sistema via /api/v1/bundles/* ou PassProject | Agrupa 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 / authenticationToken | Tokens de segurança por passe | Strings criptográficas geradas pelo sistema | Có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 suaexpirationDate; os scanners rejeitam com motivoPASS_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 comPASS_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:
ACTIVE ---> VOIDING ---> VOIDED ---> DELETING ---> DELETED
-
PassDeletionMode: Distingue entre eliminação lógica (SOFT, preserva o histórico de auditoria e liberta a unicidade deexternalIdpara passes ativos) e remoção permanente (HARD,DELETE /api/v1/passes/:id/hard). -
ArtifactStatus(appleArtifactStatusegoogleArtifactStatus): 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 ouPATCHREST 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): ConfigurechangeMessage: "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.
