Notificacoes de Clientes

O Levy Fleets usa notificacoes push para manter os clientes informados sobre suas viagens, status da conta, promocoes e atualizacoes importantes. Este guia aborda tipos de notificacao, como enviar notificacoes manuais, notificacoes automaticas do sistema e solucao de problemas de entrega.

Visao Geral

O sistema de notificacao usa Expo Push Notifications para entregar mensagens aos dispositivos moveis dos clientes. Notificacoes sao enviadas para:

• Eventos relacionados a viagens (inicio, fim, problemas)
• Alertas de zona (entrando/saindo de zonas)
• Notificacoes de pagamento (cobranças bem-sucedidas, pagamentos falhos)
• Atualizacoes de carteira (creditos adicionados)
• Mensagens promocionais (promocoes, anuncios)
• Alertas do sistema (manutencao, atualizacoes)
• Verificacao de identidade (necessaria, removida)

Tipos de Notificacao

Notificacoes Geradas pelo Sistema

Estas sao automaticamente acionadas por eventos no sistema:

Notificacoes Manuais

Operadores podem enviar notificacoes personalizadas para clientes individuais ou grupos:

Enviando Notificacoes Manuais

Para Cliente Individual

1. Navegue ate Painel > Clientes
2. Clique no cliente para abrir a pagina de detalhes
3. Clique em Acoes (menu de tres pontos)
4. Selecione Enviar Notificacao
5. Preencha o formulario de notificacao:
   • Titulo: Cabecalho da notificacao (exibido em negrito)
   • Corpo: Texto principal da mensagem
   • Tipo: Categoria da notificacao
6. Clique em Enviar

Campos do Formulario de Notificacao

Opcoes de Tipo

Referencia da API

Endpoint de Envio de Notificacao

Endpoint: POST /api/customers/notify

Corpo da Requisicao:

{
  "customerId": "customer-uuid-here",
  "title": "Oferta Especial!",
  "body": "Ganhe 20% de desconto na sua proxima viagem com o codigo ECONOMIZE20",
  "type": "promo"
}

Resposta (Sucesso):

{
  "success": true,
  "ticketId": "XXXX-XXXX-XXXX-XXXX"
}

Resposta (Falha):

{
  "success": false,
  "error": "Cliente nao tem token push"
}

Parametros Obrigatorios

Parametros Opcionais

Deep Linking

Notificacoes podem incluir dados que abrem telas especificas no aplicativo:

Detalhe da Viagem

{
  "customerId": "xxx",
  "title": "Viagem Concluida",
  "body": "Veja o resumo da sua viagem",
  "data": {
    "screen": "ride",
    "rideId": "ride-uuid"
  }
}

Carteira

{
  "customerId": "xxx",
  "title": "Credito Adicionado",
  "body": "Confira seu novo saldo",
  "data": {
    "screen": "wallet"
  }
}

Verificacao de Identidade

{
  "customerId": "xxx",
  "title": "Verifique Sua Identidade",
  "body": "Complete a verificacao para continuar andando",
  "data": {
    "screen": "identity_verification"
  }
}

Notificacoes Automaticas

Notificacoes de Viagem

Notificacoes de Pagamento

Notificacoes de Carteira

Notificacao de Saldo Negativo

Condicoes de Gatilho:

• Saldo da carteira era R$ 0 ou positivo antes da cobranca
• Saldo se torna negativo apos a cobranca
• Apenas acionado pela acao "Cobrar Taxa", nao "Reduzir Saldo"

Conteudo da Notificacao:

• Titulo: "Saldo da carteira negativo"
• Corpo: "Uma cobranca de R$ X,XX foi aplicada a sua conta. Seu saldo da carteira agora e -R$ Y,YY."
• Tipo: wallet

Notificacoes de Identidade

Configuracoes de Notificacao

Preferencias do Cliente

Os clientes podem controlar notificacoes no aplicativo movel:

• Todas as Notificacoes: Botao principal
• Atualizacoes de Viagem: Inicio, fim, alertas
• Promocoes: Mensagens de marketing
• Alertas de Pagamento: Confirmacoes de transacao

Configuracao da Subconta

Operadores podem configurar o comportamento de notificacao:

Gerenciamento de Token Push

Como os Tokens Funcionam

1. Cliente instala o aplicativo e concede permissao de notificacao
2. Aplicativo recebe token push do Expo/APNs/FCM
3. Token e armazenado no registro do cliente (expo_push_token)
4. Notificacoes enviadas para este token
5. Token pode mudar (reinstalacao, troca de dispositivo)

Status do Token

Quando Tokens Se Tornam Invalidos

• Cliente desinstalou o aplicativo
• Cliente revogou permissao de notificacao
• Dispositivo foi resetado ou substituido
• Token expirou (raro)

Status de Entrega

Recibos Push do Expo

Quando uma notificacao e enviada, o Expo fornece:

1. Ticket ID: Confirmacao imediata do envio
2. Recibo: Status eventual de entrega

Valores de Status do Recibo

Tratamento de Erros

Erros comuns e resolucoes:

Melhores Praticas

Conteudo da Mensagem

1. Mantenha titulos curtos: Maximo de 30-50 caracteres
2. Seja especifico: Diga ao cliente o que aconteceu ou o que fazer
3. Inclua valor: Por que devem se importar?
4. Use personalizacao: Inclua nome ou detalhes relevantes
5. Chamada para acao: O que devem fazer em seguida?

Frequencia

1. Nao exagere nas notificacoes: Limite mensagens promocionais
2. Agrupe quando possivel: Combine atualizacoes relacionadas
3. Respeite fusos horarios: Envie durante horas acordadas
4. Apenas emergencias: Reserve para alertas realmente importantes

Horario

Tom

• Amigavel: "Sua viagem foi concluida!"
• Claro: "Pagamento de R$ 25,00 processado"
• Acionavel: "Verifique sua identidade para continuar andando"
• Evitar: MAIUSCULAS, pontuacao excessiva, excesso de emojis

Notificacoes em Massa

Limitacoes Atuais

O painel atualmente suporta apenas notificacoes individuais. Para notificacoes em massa:

1. Use a API com um loop
2. Implemente limite de taxa (max 400/minuto para Expo)
3. Considere uma ferramenta separada de campanha de notificacao

Padrao de API em Massa

// Exemplo: Enviar para varios clientes
const customerIds = ['cust1', 'cust2', 'cust3'];
const message = {
  title: 'Oferta Especial',
  body: 'Ganhe 20% de desconto neste fim de semana!'
};

for (const customerId of customerIds) {
  await fetch('/api/customers/notify', {
    method: 'POST',
    body: JSON.stringify({ customerId, ...message })
  });
  // Limite de taxa: espere 150ms entre envios
  await new Promise(r => setTimeout(r, 150));
}

Solucao de Problemas

Notificacao nao recebida

Verifique nesta ordem:

1. Cliente tem token push?

   • Visualize a pagina de detalhes do cliente
   • Verifique o campo expo_push_token
   • Se vazio, cliente nao concedeu permissao

2. Permissao habilitada?

   • Cliente deve conceder permissao de notificacao nas configuracoes iOS/Android
   • Podem ter desabilitado apos concessao inicial

3. Aplicativo instalado?

   • Token se torna invalido se aplicativo for desinstalado
   • Cliente precisa reinstalar e conceder permissao novamente

4. Cliente correto?

   • Verifique se o customerId corresponde ao destinatario pretendido
   • Verifique contas duplicadas

5. Mensagem entregue?

   • Verifique status do recibo push do Expo
   • Procure erros de entrega nos logs

6. Problemas de dispositivo?

   • Modo Nao Perturbe no dispositivo
   • Modo Foco bloqueando notificacoes
   • Modo de economia de energia limitando atividade em segundo plano

Cliente diz que recebe "muitas" notificacoes

• Revise gatilhos de notificacao automatica
• Verifique envios duplicados nos logs
• Verifique se as preferencias de notificacao estao sendo respeitadas
• Considere configuracao de limite

Notificacao aparece mas com conteudo errado

• Verifique problemas de codificacao no titulo/corpo
• Verifique se os dados nao estao truncados
• Procure caracteres especiais sendo escapados
• Teste com texto ASCII simples

Notificacoes atrasadas

• Expo usa agrupamento, pode atrasar alguns segundos
• APNs/FCM podem atrasar com base no dispositivo/rede
• Verifique se o dispositivo esta em modo de economia de energia
• Verifique conectividade de rede no dispositivo

Erros "DeviceNotRegistered"

Isso e normal quando:

• Cliente desinstalou o aplicativo
• Cliente trocou de dispositivo
• Token expirou (raro)

Resolucao: Remova token invalido do registro do cliente. Token sera atualizado quando cliente abrir o aplicativo novamente.

Integracao com Outros Sistemas

Sistema de Viagem

O motor de viagem envia notificacoes para:

• Confirmacao de inicio de viagem
• Eventos de pausar/retomar
• Avisos de bateria/zona
• Conclusao de viagem com resumo
• Notificacoes de encerramento automatico

Sistema de Pagamento

Processamento de pagamento aciona:

• Confirmacao de cobranca bem-sucedida
• Alertas de pagamento falho
• Notificacoes de reembolso
• Avisos de expiracao de cartao

Sistema de Identidade

Verificacao de identidade aciona:

• Prompt de verificacao necessaria
• Confirmacao de verificacao bem-sucedida
• Notificacao de requisito removido
• Notificacao de tentativa falha