Skip to content
Guia da Central de Ajuda · Gestão de passesFase de integração 4
6 min de leituraVerificado 2026-11-16

Ciclo de vida e estados do passe

Compreenda Criado, Não instalado, Instalado, Expirado e Anulado e o seu efeito na faturação e leituras.

Neste guia

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

Foco ampliado da interface
Elementos-chave da interface

Detalhe do estado de registo na Wallet em tempo real (Zoom)

Clique no ícone da Apple Wallet ou Google Wallet em qualquer linha para verificar registos ativos, remoções e histórico de instalação.

Visão geral

A Passinstance governa cada passe emitido através de três máquinas de estados ortogonais acompanhadas no modelo Pass:

  1. 1
    pass status (11 valores): Estado funcional de validade de negócio que determina se um passe pode ser instalado, lido ou resgatado.
  2. 2
    PassLifecycleStatus (5 fases): Progressão administrativa de retenção e revogação desde ACTIVE até DELETED.
  3. 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

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
MÁQUINA DE ESTADOS E PROPAGAÇÃO NA CARTEIRA
ETAPA 01
1
ESTADO DE NEGÓCIO (pass status) [DRAFT] / [AWAITING_OPT_IN] / [PENDING_ACTIVATION]
[GENERATING][ACTIVE] <[INACTIVE] / [SUSPENDED] [REDEEMED] [EXPIRED] [CANCELLED] / [VOIDED]
ETAPA 02
2
PROGRESSÃO DO CICLO DE VIDA (PassLifecycleStatus) [ACTIVE][VOIDING][VOIDED][DELETING][DELETED]
ETAPA 03
3
PIPELINE DE SINCRONIZAÇÃO CLOUD (WalletPropagationStatus) [NONE][PENDING][QUEUED][SUCCEEDED] (ou [FAILED] + Repetição)

1. Todos os 11 estados de negócio pass status

Valor pass statusResultado da validação por scannerApresentação visual na carteira e comportamento
DRAFTRejeitado (INVALID)O registo do passe existe na BD antes da assinatura; a ligação de download ainda não está ativa.
AWAITING_OPT_INRejeitado (PENDING)Criado via PassFlow ou campanha; a aguardar código OTP por e-mail/SMS ou confirmação de consentimento RGPD.
PENDING_ACTIVATIONRejeitado (PENDING)Passe emitido a aguardar captura de pagamento externo ou leitura de ativação em POS.
GENERATINGRejeitado (PENDING)O pacote criptográfico .pkpass ou o objeto Google Wallet está atualmente a ser compilado por um worker.
ACTIVEAceite (SUCCESS)Passe válido e ativo elegível para leitura, acumulação de pontos, aproximação NFC e notificações push.
INACTIVERejeitado (INVALID)Temporariamente desativado por um operador (POST /api/v1/batch-pass-operations/deactivate).
SUSPENDEDRejeitado (INVALID)Congelado por suspeita de fraude, incumprimento de pagamento ou retenção de segurança; reversível para ACTIVE.
REDEEMEDRejeitado (ALREADY_USED)Cupão ou bilhete de utilização única já foi lido e consumido (VOIDED_AFTER_SCAN scan mode).
EXPIREDRejeitado (EXPIRED)A data/hora atual ultrapassou Pass.expirationDate; o código de barras fica acinzentado no dispositivo do cliente.
CANCELLEDRejeitado (ALREADY_VOIDED)A inscrição ou encomenda foi cancelada (ex.: encomenda de bilhete reembolsada) antes do resgate.
VOIDEDRejeitado (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:

FaseDescrição
ACTIVEEstado operacional normal em passes ativos, inativos ou expirados.
VOIDINGBloqueio 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.
VOIDEDRevogação terminal concluída; o carimbo temporal voidedAt e o motivo voidReason ficam gravados permanentemente no registo do passe.
DELETINGBloqueio transitório adquirido quando um operador pede a eliminação permanente do registo; revoga tokens de download e desassocia ativos de armazenamento.
DELETEDEstado 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
NONEO passe acabou de ser criado ou nenhuma propagação/anulação foi colocada em fila.
PENDINGUma atualização de campo ou transição de ciclo de vida foi confirmada no database e aguarda recolha pelo distribuidor de propagação.
QUEUEDUma tarefa background job queue de sincronização de carteira está em fila para enviar o push APNs HTTP/2 ou pedido PATCH à Google Wallet.
SUCCEEDEDTodos os dispositivos registados / objetos na cloud confirmaram a atualização (na Apple Wallet, o dispositivo obteve o .pkpass mais recente via GET /v1/passes/...).
FAILEDA 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/:id executa uma eliminação SOFT (definindo archivedAt, libertando a unicidade (customerId, externalId) no tenant para reemissão enquanto retém registos de auditoria), enquanto DELETE /api/v1/passes/:id/hard executa uma purga HARD.
  • ArtifactStatus (appleArtifactStatus, googleArtifactStatus): NOT_GENERATED | GENERATING | READY | FAILED | INVALIDATED acompanha 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: true estiver 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):

EndpointEscopoDescrição
POST /api/v1/passes/:id/deactivatePasse ÚnicoTransita temporariamente o estado do passe de ACTIVE para INACTIVE.
POST /api/v1/passes/voiding/:id/voidPasse ÚnicoAnula (voided: true) ou reativa (voided: false) um único passe (204 No Content).
POST /api/v1/passes/voiding/batch-voidMatriz de PassesAnula ou ativa múltiplos passIds num único pedido (request payload).
POST /api/v1/passes/voiding/template-voidModelo InteiroAnula em massa todos os passes ativos emitidos ao abrigo de um templateId (request payload).
GET /api/v1/passes/voiding/:id/voiding-historyRegisto de AuditoriaDevolve 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

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 Content em caso de sucesso, definindo imediatamente status = "VOIDED", lifecycleStatus = "VOIDED" e atualizando walletVoidStatus (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

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

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.

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.