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.
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 estado | Significado e estado operacional |
|---|---|
NONE | O passe acabou de ser criado ou nenhuma propagação visível na carteira foi colocada em fila. |
PENDING | Uma revisão de campo, saldo de mecânica ou anulação/modelo foi confirmada; a aguardar envio para a fila background job queue. |
QUEUED | Enviado para a fila de workers in-memory cache/background job queue de propagação de carteiras para execução em APNs e Google REST. |
SUCCEEDED | A 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. |
FAILED | A 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/publishcompropagateUpdates: truedistribui tarefas de propagação pelos passes ativos associados a esse modelo (filtrável comactivePassesOnly: true). Execute previamenteGET /api/v1/templates/:id/publish-risk-checkpara inspecionar alterações críticas e potenciais impactos.
Endpoints da API para atualizar passes
| Método | Caminho do endpoint | Descrição |
|---|---|---|
| PATCH | /api/v1/passes/:id | Atualiza 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-id | Cria 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/update | Atualiza os passIds selecionados num pedido em lote (request payload) e coloca em fila tarefas de propagação. |
| POST | /api/v1/templates/:id/publish | Promove 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
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):
{
"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)
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
.pkpassmais recente. -
Supressão de passes anulados: Por predefinição, passes no estado
VOIDEDouEXPIREDsuprimem pushes de rotina de marketing, salvo seupdateVoidedExpiredPasses: trueestiver ativo no modelo.
Consulte Notificações push, Ver e atualizar passes e Versões de modelos e publicação para fluxos relacionados.
