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.
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
Escolher público-alvo (
mode): Emrequest payload, direcione passes explícitos (manual), segmentos/pesquisas guardadas (filter/segment), todos os passes elegíveis (all) ou carregue um ficheiro CSV com registosserialNumber/externalId(csvvia/api/v1/batch-notifications/csv). -
2
Redigir a mensagem: Indique
message(<=200carateres em notificações em lote, suportando marcadores{attributeKey}, ou<=85carateres emPush Notifications API). -
3
Configurar data, hora e fuso horário: Forneça
publicationDate(YYYY-MM-DD HH:mmou ISO 8601), resolvido para o fuso horário IANA do espaço de trabalho. Enquanto o lote permanecer no estadoSCHEDULED(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
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étodo | Caminho do endpoint | Controlador | Descrição | ||||
|---|---|---|---|---|---|---|---|
| POST | /api/v1/push-notifications/templates/:id | Push Notifications API | Agenda uma notificação push (request payload) num modelo (com segmentIds / savedSearchIds opcionais). | ||||
| POST | /api/v1/push-notifications/templates/:id/send | Push Notifications API | Difunde imediatamente uma notificação push do modelo (request payload). | ||||
| POST | /api/v1/push-notifications/segmentation | Push Notifications API | Envia uma notificação imediata para uma pesquisa guardada (request payload). | ||||
| POST | /api/v1/batch-notifications | Batch Notifications API | Cria uma notificação em lote agendada (request payload: `manual \ | filter \ | csv \ | all \ | segment`). |
| GET | /api/v1/batch-notifications/:batchId | Batch Notifications API | Obtém o progresso de execução (SCHEDULED, PROCESSING, SUCCESSFUL, CANCELLED, FAILED) e telemetria. | ||||
| DELETE | /api/v1/batch-notifications/:batchId | Batch Notifications API | Cancela uma tarefa de notificação em lote pendente em SCHEDULED antes do envio. |
Exemplo: Agendar uma notificação em lote (request payload)
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):
{
"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")Ndias antes daexpirationDatede um passe. -
Contagem decrescente de check-in de eventos: Combine a apresentação no ecrã bloqueado por
RelevantDatecom 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.
