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

Atualizações e mensagens agendadas

Agende campanhas por lote, segmente audiências antes de eventos ou renovações e audite registos de envio.

Neste guia

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

Foco ampliado da interface
Elementos-chave da interface

Registro de atividades — Atualizações e push (Ampliado)

Confirme que republicações do template e notificações push executam sem falhas em passes Apple e Google ativos.

Visão geral: Campanhas agendadas e mensagens automatizadas

A Passinstance permite às equipas programar antecipadamente atualizações de passes com hora marcada, comunicados promocionais, notificações em massa por CSV e lembretes automáticos de expiração. As tarefas agendadas ficam persistidas no database e são executadas por filas de workers diferidas background job queue, assegurando distribuição fiável nos endpoints Apple APNs e Google Wallet REST no momento exato definido.

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
MOTOR DE NOTIFICAÇÕES AGENDADAS E EM LOTE
ETAPA 01 AGENDAMENTO E INGESTÃO DE CAMPANHAS
Push Agendado Modelo (POST/api/v1/push-notifications/templates/:id)
Campanha Pesquisa Guardada (POST/api/v1/push-notifications/segmentation)
Notificação Lote / CSV (POST/api/v1/batch-notifications e /csv)
Cron Automatizado de Ciclo de Vida (Lembretes Expiração e Renovação Patamar)
ETAPA 02 RESOLUÇÃO DE FUSO HORÁRIO E FILA DIFERIDA ASSÍNCRONA
1
Resolve hora de execução alvo via resolveCustomerTimeZone (Fuso IANA)
2
Persiste lote (batch notification status: SCHEDULED)
3
Coloca tarefa diferida background job queue em fila (delay = scheduledAt - now())
No Carimbo Temporal publicationDate
ETAPA 03 DISTRIBUIÇÃO POR WORKERS E PIPELINE DE PROPAGAÇÃO
1
Seleciona passes ACTIVE elegíveis com registos APNs / Google Wallet ativos
2
Altera o valor do campo de notificação designado e incrementa revisão do passe
3
Envia pushes silenciosos APNs HTTP/2 e patches walletobjects Google Wallet
4
Grava resultados por passe (SUCCESSFUL, FAILED, CANCELLED)

Agendar campanhas antecipadamente

Utilize Notificações em Lote (/batch-notifications em Lote na barra lateral do Painel) ou a API REST para agendar futuras atualizações de passes de forma organizada:

  1. 1
    Escolher público-alvo (mode): Em request payload, direcione passes explícitos (manual), segmentos/pesquisas guardadas (filter / segment), todos os passes elegíveis (all) ou carregue um ficheiro CSV com registos serialNumber / externalId (csv via /api/v1/batch-notifications/csv).
  2. 2
    Redigir a mensagem: Indique message (<=200 carateres em notificações em lote, suportando marcadores {attributeKey}, ou <=85 carateres em Push Notifications API).
  3. 3
    Configurar data, hora e fuso horário: Forneça publicationDate (YYYY-MM-DD HH:mm ou ISO 8601), resolvido para o fuso horário IANA do espaço de trabalho. Enquanto o lote permanecer no estado SCHEDULED (batch notification status: SCHEDULED, PROCESSING, SUCCESSFUL, FAILED, CANCELLED), pode atualizar (PATCH), enviar imediatamente (POST /:batchId/send-now), repetir (POST /:batchId/retry) ou cancelar (DELETE).
  4. 4
    Verificar execução e registos de auditoria: Acompanhe o progresso e exporte erros linha a linha via GET /api/v1/batch-notifications/:batchId/errors.csv.

Importante: Apenas passes Instalados com pelo menos um registo ativo na Apple Wallet (deviceLibraryIdentifier) ou um objeto ativo na Google Wallet podem apresentar notificações push no ecrã bloqueado. Verifique Registos Ativos de Dispositivos em Analítica antes de agendar.

Endpoints da API de notificações agendadas e em lote

MétodoCaminho do endpointControladorDescrição
POST/api/v1/push-notifications/templates/:idPush Notifications APIAgenda uma notificação push (request payload) num modelo (com segmentIds / savedSearchIds opcionais).
POST/api/v1/push-notifications/templates/:id/sendPush Notifications APIDifunde imediatamente uma notificação push do modelo (request payload).
POST/api/v1/push-notifications/segmentationPush Notifications APIEnvia uma notificação imediata para uma pesquisa guardada (request payload).
POST/api/v1/batch-notificationsBatch Notifications APICria uma notificação em lote agendada (request payload: `manual \filter \csv \all \segment`).
GET/api/v1/batch-notifications/:batchIdBatch Notifications APIObtém o progresso de execução (SCHEDULED, PROCESSING, SUCCESSFUL, CANCELLED, FAILED) e telemetria.
DELETE/api/v1/batch-notifications/:batchIdBatch Notifications APICancela uma tarefa de notificação em lote pendente em SCHEDULED antes do envio.

Exemplo: Agendar uma notificação em lote (request payload)

JSON
POST /api/v1/batch-notifications
{
  "name": "Winter Flash Sale Push",
  "message": "Hi {firstName}, enjoy 25% off today with your {memberTier} card!",
  "publicationDate": "2026-11-20 17:00",
  "mode": "filter",
  "filters": {
    "templateId": "7b9e4c12-3f81-4a90-b8d2-19c48a70e112",
    "segmentIds": ["seg_vip_tier_01"]
  }
}

Resposta (201 Created):

JSON
{
  "id": "bn_8831a9c0",
  "status": "SCHEDULED",
  "publicationDate": "2026-11-20T16:00:00.000Z"
}

Lembretes automatizados de expiração e contagem decrescente de eventos

Além de campanhas manuais e agendadas por CSV, pode associar gatilhos temporais automatizados em Fluxos de Trabalho e Automação:

  • Lembretes pré-expiração: Atualize automaticamente um campo de aviso (ex.: "Your pass expires in 3 days — tap to renew") N dias antes da expirationDate de um passe.
  • Contagem decrescente de check-in de eventos: Combine a apresentação no ecrã bloqueado por RelevantDate com uma notificação push agendada 24 horas antes do evento a confirmar porta, lugar ou instruções de estacionamento.

Saiba mais em Notificações push, Configuração de fluxos de trabalho e Analítica de distribuição e interação.

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.