Visão geral
A Passinstance governa cada passe emitido através de três máquinas de estados ortogonais acompanhadas no modelo Pass:
-
1
pass status (11 valores): Estado funcional de validade de negócio que determina se um passe pode ser instalado, lido ou resgatado.
-
2
PassLifecycleStatus(5 fases): Progressão administrativa de retenção e revogação desdeACTIVEatéDELETED. -
3
WalletPropagationStatus(5 fases): Estado de sincronização assíncrona na cloud que acompanha o envio push para APNs e Google Wallet.
Arquitetura do sistema: Ciclo de vida do passe e propagação na carteira
1. Todos os 11 estados de negócio pass status
| Valor pass status | Resultado da validação por scanner | Apresentação visual na carteira e comportamento |
|---|---|---|
DRAFT | Rejeitado (INVALID) | O registo do passe existe na BD antes da assinatura; a ligação de download ainda não está ativa. |
AWAITING_OPT_IN | Rejeitado (PENDING) | Criado via PassFlow ou campanha; a aguardar código OTP por e-mail/SMS ou confirmação de consentimento RGPD. |
PENDING_ACTIVATION | Rejeitado (PENDING) | Passe emitido a aguardar captura de pagamento externo ou leitura de ativação em POS. |
GENERATING | Rejeitado (PENDING) | O pacote criptográfico .pkpass ou o objeto Google Wallet está atualmente a ser compilado por um worker. |
ACTIVE | Aceite (SUCCESS) | Passe válido e ativo elegível para leitura, acumulação de pontos, aproximação NFC e notificações push. |
INACTIVE | Rejeitado (INVALID) | Temporariamente desativado por um operador (POST /api/v1/batch-pass-operations/deactivate). |
SUSPENDED | Rejeitado (INVALID) | Congelado por suspeita de fraude, incumprimento de pagamento ou retenção de segurança; reversível para ACTIVE. |
REDEEMED | Rejeitado (ALREADY_USED) | Cupão ou bilhete de utilização única já foi lido e consumido (VOIDED_AFTER_SCAN scan mode). |
EXPIRED | Rejeitado (EXPIRED) | A data/hora atual ultrapassou Pass.expirationDate; o código de barras fica acinzentado no dispositivo do cliente. |
CANCELLED | Rejeitado (ALREADY_VOIDED) | A inscrição ou encomenda foi cancelada (ex.: encomenda de bilhete reembolsada) antes do resgate. |
VOIDED | Rejeitado (ALREADY_VOIDED) | Invalidado permanentemente via Pass Voiding API; define "voided": true no pass.json Apple e STATE_EXPIRED/INACTIVE na Google Wallet. |
2. As 5 fases de PassLifecycleStatus
A coluna lifecycleStatus coordena revogações seguras em várias etapas e a limpeza na base de dados sem deixar objetos órfãos nas carteiras dos utilizadores:
| Fase | Descrição |
|---|---|
ACTIVE | Estado operacional normal em passes ativos, inativos ou expirados. |
VOIDING | Bloqueio transitório adquirido quando um pedido de anulação é iniciado; coloca em fila atualizações push prioritárias de anulação para a Apple e Google Wallet. |
VOIDED | Revogação terminal concluída; o carimbo temporal voidedAt e o motivo voidReason ficam gravados permanentemente no registo do passe. |
DELETING | Bloqueio transitório adquirido quando um operador pede a eliminação permanente do registo; revoga tokens de download e desassocia ativos de armazenamento. |
DELETED | Estado lógico de eliminação (tombstone) ou remoção finalizada antes da purga RGPD. |
3. walletVoidStatus (WalletPropagationStatus), modos de eliminação e artefactos
A Passinstance acompanha o envio assíncrono de pushes na cloud, a semântica de eliminação e a compilação de artefactos de carteira através de colunas e enums dedicados no Passinstance database em Pass:
walletVoidStatus (WalletPropagationStatus)
Sempre que uma transição de anulação/estado é enviada para Apple APNs ou Google Wallet, Pass.walletVoidStatus acompanha o progresso da entrega:
Fase (WalletPropagationStatus) | Descrição |
|---|---|
NONE | O passe acabou de ser criado ou nenhuma propagação/anulação foi colocada em fila. |
PENDING | Uma atualização de campo ou transição de ciclo de vida foi confirmada no database e aguarda recolha pelo distribuidor de propagação. |
QUEUED | Uma tarefa background job queue de sincronização de carteira está em fila para enviar o push APNs HTTP/2 ou pedido PATCH à Google Wallet. |
SUCCEEDED | Todos os dispositivos registados / objetos na cloud confirmaram a atualização (na Apple Wallet, o dispositivo obteve o .pkpass mais recente via GET /v1/passes/...). |
FAILED | A entrega encontrou um erro externo (ex.: token APNs não registado ou erro de quota da Google API); elegível para nova tentativa. |
PassDeletionMode e ArtifactStatus
-
PassDeletionMode(SOFT|HARD):DELETE /api/v1/passes/:idexecuta uma eliminaçãoSOFT(definindoarchivedAt, libertando a unicidade(customerId, externalId)no tenant para reemissão enquanto retém registos de auditoria), enquantoDELETE /api/v1/passes/:id/hardexecuta uma purgaHARD. -
ArtifactStatus(appleArtifactStatus,googleArtifactStatus):NOT_GENERATED | GENERATING | READY | FAILED | INVALIDATEDacompanha se o pacote criptográfico / objeto cloud de cada plataforma está compilado e atualizado.
Invariante importante de faturação e ciclo de vida na carteira
Importante: Anular ou expirar um passe rejeita validações futuras no scanner e assinala visualmente o cartão como inválido/acinzentado na carteira do utilizador, mas o Apple iOS e o Google Android não permitem que servidores externos eliminem à força um passe do dispositivo do cliente sem ação do utilizador. Na Apple Wallet, os passes anulados suprimem atualizações no ecrã bloqueado salvo se
updateVoidedExpiredPasses: trueestiver ativo no modelo. Um passe instalado continua a contar como um registo ativo de dispositivo até que o cliente o remova da carteira ou conclua o cancelamento do registo do dispositivo.
API de desativação e anulação de passes (Passes API / Pass Voiding API)
A Passinstance disponibiliza desativação reversível (POST /api/v1/passes/:id/deactivate) e endpoints formais de anulação em /api/v1/passes/voiding (aceitando VoidingReason: EXPIRED, CANCELLED, LOST, STOLEN, DUPLICATE, FRAUD, TECHNICAL_ISSUE, CUSTOMER_REQUEST, ADMIN_ACTION, SYSTEM_AUTO, OTHER):
| Endpoint | Escopo | Descrição |
|---|---|---|
POST /api/v1/passes/:id/deactivate | Passe Único | Transita temporariamente o estado do passe de ACTIVE para INACTIVE. |
POST /api/v1/passes/voiding/:id/void | Passe Único | Anula (voided: true) ou reativa (voided: false) um único passe (204 No Content). |
POST /api/v1/passes/voiding/batch-void | Matriz de Passes | Anula ou ativa múltiplos passIds num único pedido (request payload). |
POST /api/v1/passes/voiding/template-void | Modelo Inteiro | Anula em massa todos os passes ativos emitidos ao abrigo de um templateId (request payload). |
GET /api/v1/passes/voiding/:id/voiding-history | Registo de Auditoria | Devolve os eventos cronológicos de anulação/ativação do passe. |
Exemplo: Anular um único passe (request payload)
POST /api/v1/passes/voiding/pass_01j8k9m2n3p4q5r6/void Cabeçalhos: X-API-Key: <API_KEY> | Content-Type: application/json
{
"voided": true,
"options": {
"reason": "CANCELLED",
"customReason": "Order refunded via Shopify webhook #SH-99412",
"sendPushNotification": true,
"pushNotificationMessage": "This pass has been voided following your order refund.",
"updateGoogleWallet": true
}
}
Estado HTTP: Devolve
204 No Contentem caso de sucesso, definindo imediatamentestatus = "VOIDED",lifecycleStatus = "VOIDED"e atualizandowalletVoidStatus(WalletPropagationStatus:NONE->PENDING->QUEUED->SUCCEEDED) à medida que decorrem os pushes em segundo plano.
Exemplo: Anular em lote múltiplos passes (request payload)
POST /api/v1/passes/voiding/batch-void Cabeçalhos: X-API-Key: <API_KEY> | Content-Type: application/json
{
"passIds": [
"pass_01j8k9m2n3p4q5r6",
"pass_01j8k9m2n3p4q5r7"
],
"voided": true,
"options": {
"reason": "EXPIRED",
"customReason": "Expired seasonal VIP cohort",
"sendPushNotification": true
}
}
Exemplo: Anular todos os passes de um modelo (request payload)
POST /api/v1/passes/voiding/template-void Cabeçalhos: X-API-Key: <API_KEY> | Content-Type: application/json
{
"templateId": "tmpl_01hxyz987654321",
"voided": true,
"options": {
"reason": "CANCELLED",
"customReason": "Summer 2026 promotional campaign concluded",
"sendPushNotification": true
}
}
Consulte Operações em lote para fluxos baseados em matrizes de ativação, desativação e eliminação, ou Passes ativos e limites de utilização para regras de medição de capacidade.
