Pular para o conteúdo principal

Payloads e Deep Links de Notificação

Pilar: 03 — Notificações
Status: 🟢 Implementado
Última Revisão Técnica: 2026-08-03
Módulos Conectados: gatein-server (app/core/firebase.py), gatein-app (src/navigation/RootNavigator.js)

1. Estrutura Padrão dos Payloads FCM​

Todas as notificações enviadas pelo servidor Gatein seguem o padrão bidimensional do Firebase Cloud Messaging:

  1. notification: Contém o título e corpo visíveis renderizados pelo SO.
  2. data: Objeto de chave-valor (onde todos os valores são obrigatoriamente string) consumido pela engine de roteamento dinâmico do aplicativo mobile.
{
  "notification": {
    "title": "Check-in Aprovado",
    "body": "Sua entrada no Terminal Santos foi liberada. Acesse seu Ticket."
  },
  "data": {
    "type": "CHECKIN_APPROVED",
    "appointment_id": "w8x9k2m1",
    "ticket_id": "z9y8x7w6",
    "terminal_id": "p4k2n8m9",
    "click_action": "FLUTTER_NOTIFICATION_CLICK"
  }
}

2. Dicionário Completo de Payloads por Tipo de Evento​

2.1 Evento: CHECKIN_APPROVED​

  • Finalidade: Notificar o motorista que a entrada no terminal foi autorizada.
  • Payload data:
{
  "type": "CHECKIN_APPROVED",
  "appointment_id": "w8x9k2m1",
  "ticket_id": "z9y8x7w6"
}
  • Roteamento no App: Redireciona imediatamente para a tela TicketScreen carregando o Ticket z9y8x7w6.

2.2 Evento: CHECKIN_REJECTED​

  • Finalidade: Informar que a solicitação de check-in foi recusada pelo operador.
  • Payload data:
{
  "type": "CHECKIN_REJECTED",
  "appointment_id": "w8x9k2m1",
  "reason": "Doca ocupada. Aguarde nova orientação na área de triagem."
}
  • Roteamento no App: Abre a tela CheckinFailScreen exibindo o motivo retornado pelo operador.

2.3 Evento: REMINDER_1DAY​

  • Finalidade: Lembrete de véspera de atendimento.
  • Payload data:
{
  "type": "REMINDER_1DAY",
  "count": "1",
  "appointment_id": "w8x9k2m1"
}
  • Roteamento no App: Abre a tela principal HomeScreen com o card do agendamento destacado.

2.4 Evento: COUNTDOWN (Lembrete de 12 Horas)​

  • Finalidade: Notificação com dados para contador regressivo na interface.
  • Payload data:
{
  "type": "COUNTDOWN",
  "appointment_id": "w8x9k2m1",
  "target_timestamp": "2026-08-04T10:00:00Z",
  "count": "1"
}
  • Roteamento no App: Abre a tela AppointmentDetailScreen iniciando o timer regressivo nativo.

2.5 Evento: WINDOW_OPEN​

  • Finalidade: Avisar que a tolerância inicial da janela agendada foi atingida.
  • Payload data:
{
  "type": "WINDOW_OPEN",
  "appointment_id": "w8x9k2m1"
}
  • Roteamento no App: Abre a tela CheckinScreen ou habilita o botão de Check-in Remoto via GPS.

2.6 Evento: TRIP_ASSIGNED​

  • Finalidade: Notificar a atribuição de uma nova viagem de frete.
  • Payload data:
{
  "type": "TRIP_ASSIGNED",
  "trip_id": "t1k2m3n4"
}
  • Roteamento no App: Redireciona para a aba TripsTab / TripDetailScreen.
graph TD
    PUSH[Notificação Recebida / Tocado pelo Usuário] --> PARSE[Leitura do data.type]
    
    PARSE -->|CHECKIN_APPROVED| TICKET[TicketScreen / params: ticket_id]
    PARSE -->|CHECKIN_REJECTED| FAIL[CheckinFailScreen / params: reason]
    PARSE -->|REMINDER_1DAY| HOME[HomeScreen]
    PARSE -->|COUNTDOWN| DETAIL[AppointmentDetailScreen / params: appointment_id]
    PARSE -->|WINDOW_OPEN| CHECKIN[CheckinScreen / params: appointment_id]
    PARSE -->|TRIP_ASSIGNED| TRIP[TripDetailScreen / params: trip_id]
    PARSE -->|ANNOUNCEMENT_PUBLISHED| ANNOUNCEMENT[NotificationsScreen / params: announcement_id]

4. Regras de Sanitização de Payloads​

  1. Apenas Strings no Dicionário data: O SDK do Firebase Admin rejeita dicionários contendo valores booleanos, inteiros ou nulos dentro do campo data. Todos os atributos (como count ou timestamps) devem ser convertidos com str() antes do envio.
  2. Sqids Obrigatórios: Nenhum ID interno bruto (UUID ou Integer) pode ser enviado no payload de notificação. Todos os atributos identificadores devem utilizar encode_id().