Skip to content
Guia da Central de Ajuda · Atualizações e notificações
3 min de leituraVerificado 2026-11-16

Atualizar passes existentes

Saiba como alterações no servidor disparam atualizações silenciosas APNs Apple e patches REST Google Wallet.

Neste guia

Visão geral: Como funciona a sincronização de passes em direto

Ao contrário de bilhetes em PDF estáticos ou imagens de códigos de barras, os passes digitais geridos pela Passinstance mantêm-se ligados dinamicamente à cloud após a instalação. Sempre que um atributo do passe, saldo de mecânica (carimbos, pontos de fidelização, saldo pré-pago), patamar ou design do modelo muda, a Passinstance orquestra um Pipeline Assíncrono de Propagação para Carteiras que atualiza o cartão ativo no iPhone, Apple Watch e dispositivo Android do cliente.

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
PIPELINE DE ATUALIZAÇÃO E PROPAGAÇÃO
ETAPA 01 FONTES DE GATILHOS DE ALTERAÇÃO
Atualização Única: PATCH/api/v1/passes/:id ou upsert-by-external-id
Atualização Lote: POST/api/v1/batch-pass-operations/update
Publicar Modelo: POST/api/v1/templates/:id/publish (propagateUpdates)
Scanner / POS: POST/api/v1/scans, /v1/pos/redeem, /api/v1/reader/redeem
ETAPA 02 CONFIRMAÇÃO EM BASE DE DADOS E TRANSIÇÃO DE PROPAGAÇÃO
1
Incrementa revisão do passe e grava registo de auditoria pass audit log
2
Define walletVoidStatus (WalletPropagationStatus): NONEPENDINGQUEUED
3
Coloca tarefa background job queue de propagação em fila (wallet-propagation queue)
Registos Dispositivos Apple Wallet
ETAPA 03A
1
Apple Push Delivery envia push HTTP/ {} a cada dispositivo registado
2
iOS acorda e consulta:GET/v1/devices/.../registrations
3
iOS obtém novo .pkpass assinadoGET/v1/passes/:typeId/:serial
Objeto Cloud Google Wallet
ETAPA 03B azio| | 1. Google Wallet Sync execu
REST PATCH autenticado em walletobjects/v1/...
2
Google Cloud envia estado atualizado para dispositivos Android via Google Play Services
ETAPA 04 TELEMETRIA FINAL E ATUALIZAÇÃO DO ESTADO DE PROPAGAÇÃO
walletVoidStatus (WalletPropagationStatus): SUCCEEDED ou FAILED

Ciclo de vida do estado de propagação (walletVoidStatus / WalletPropagationStatus)

Cada registo de passe acompanha o estado de anulação/propagação pelas redes cloud da Apple e Google através de Pass.walletVoidStatus (WalletPropagationStatus):

Enum de estadoSignificado e estado operacional
NONEO passe acabou de ser criado ou nenhuma propagação visível na carteira foi colocada em fila.
PENDINGUma revisão de campo, saldo de mecânica ou anulação/modelo foi confirmada; a aguardar envio para a fila background job queue.
QUEUEDEnviado para a fila de workers in-memory cache/background job queue de propagação de carteiras para execução em APNs e Google REST.
SUCCEEDEDA notificação push APNs foi aceite pela gateway HTTP/2 da Apple (200 OK) e/ou o PATCH REST da Google Wallet foi concluído com sucesso.
FAILEDA propagação encontrou um erro externo (ex.: certificado Apple Pass Type expirado, token APNs revogado 410 Gone ou erro de quota na Google API).

Importante: Publicar um rascunho de modelo via POST /api/v1/templates/:id/publish com propagateUpdates: true distribui tarefas de propagação pelos passes ativos associados a esse modelo (filtrável com activePassesOnly: true). Execute previamente GET /api/v1/templates/:id/publish-risk-check para inspecionar alterações críticas e potenciais impactos.

Endpoints da API para atualizar passes

MétodoCaminho do endpointDescrição
PATCH/api/v1/passes/:idAtualiza atributos personalizados, estado, data de expiração ou código de barras de um passe único e despoleta propagação na carteira.
POST/api/v1/passes/upsert-by-external-idCria ou atualiza de forma idempotente um passe existente correspondido por (customerId, externalId) (PUT /api/v1/passes/by-external-id/:externalId também suportado).
POST/api/v1/batch-pass-operations/updateAtualiza os passIds selecionados num pedido em lote (request payload) e coloca em fila tarefas de propagação.
POST/api/v1/templates/:id/publishPromove um rascunho de modelo (request payload com propagateUpdates: true) e atualiza os passes ativos desse modelo.

Exemplo: Atualização de passe único e gatilho de propagação

JSON
PATCH /api/v1/passes/c41a8d20-6e11-4f3b-9a81-0029d81a4f10
{
  "attributes": {
    "points": 1450,
    "tier": "Platinum",
    "nextReward": "Free Espresso"
  },
  "expirationDate": "2027-12-31 23:59"
}

Resposta (200 OK):

JSON
{
  "id": "c41a8d20-6e11-4f3b-9a81-0029d81a4f10",
  "externalId": "cust_884910",
  "serialNumber": "PI-8849-2026-X9",
  "status": "ACTIVE",
  "lifecycleStatus": "ACTIVE",
  "walletVoidStatus": "QUEUED",
  "updatedAt": "2026-11-15T14:22:10.114Z"
}

Exemplo: Atualização em lote por matriz de passes (request payload)

JSON
POST /api/v1/batch-pass-operations/update
{
  "operation": "update",
  "passIds": [
    "c41a8d20-6e11-4f3b-9a81-0029d81a4f10",
    "9b2f1e44-8a10-4c92-a711-5530e91b2c01"
  ],
  "updateData": {
    "attributes": {
      "seasonalOffer": "Winter Bonus Points"
    }
  }
}

Porque o tempo de sincronização pode variar entre dispositivos

  • Modo de Voo e Poupança de Dados: Dispositivos iOS em Modo de Voo ou Modo de Baixo Consumo adiam transferências APNs em segundo plano até a ligação Wi-Fi ou rede móvel regressar.
  • Opção de atualização manual: Clientes que desativaram Atualizações Automáticas no verso do passe Apple Wallet têm de puxar para baixo manualmente dentro da Apple Wallet para obter o pacote .pkpass mais recente.
  • Supressão de passes anulados: Por predefinição, passes no estado VOIDED ou EXPIRED suprimem pushes de rotina de marketing, salvo se updateVoidedExpiredPasses: true estiver ativo no modelo.

Consulte Notificações push, Ver e atualizar passes e Versões de modelos e publicação para fluxos relacionados.

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.