Skip to main content

​
Visão Geral

O módulo de notificações é acionado por um cron job externo (servidor Ubuntu) que chama POST /notificacoes/cron/executar diariamente. A lógica percorre todas as parcelas pendentes e atrasadas de todos os locadores ativos, e dispara avisos pelos canais configurados.

​
Canais suportados

CanalProvedorConfiguração necessária
E-mailBrevo (SMTP)brevoApiKey + brevoEmailRemetente
SMSBrevo (SMS)brevoSmsApiKey + brevoSmsSender
WhatsApp (templates)Meta Business APIwhatsappToken + whatsappPhoneId
WhatsApp (texto livre)Evolution APIEVOLUTION_API_URL + EVOLUTION_GLOBAL_KEY
Evolution API e Meta WhatsApp são mutuamente exclusivos por disparo — se evolutionAtivo estiver habilitado, ele tem prioridade sobre o Meta.

​
Tipos de notificação

TipodiasAntesDisparo
VENCIMENTO> 0X dias antes do vencimento (configurável)
VENCIMENTO0No dia do vencimento
INADIMPLENCIA< 0X dias após o vencimento (parcelas ATRASADO)
Os dias de aviso são configuráveis por locador em configuracoes_notificacoes. Padrões: [3, 1, 0] para vencimento e [1, 3, 7] para inadimplência.

​
Cron — Executar rotina diária

Endpoint chamado pelo cron job do servidor. Não requer Firebase Auth — usa CRON_SECRET no header. 
POST /notificacoes/cron/executar
Authorization: Bearer <CRON_SECRET>
Resposta 200
{
  "sucesso": true,
  "totalGeral": 14,
  "resultados": [
    {
      "userId": "uid123",
      "totalEnviadas": 8,
      "detalhes": [
        {
          "locatario": "João da Silva",
          "tipo": "VENCIMENTO",
          "diasAntes": 3,
          "valor": 2500
        }
      ]
    }
  ]
}
Qualquer requisição sem o header Authorization: Bearer <CRON_SECRET> retorna 401. Configure CRON_SECRET no .env do servidor.

​
Disparar manualmente

Requer autenticação e role SUPER_ADMIN ou ADMIN. Útil para testar o fluxo sem esperar o cron.
​
userId
string
Se informado, dispara apenas para o locador especificado. Se omitido, processa todos os locadores ativos.
POST /notificacoes/disparar
Cookie: imob_session=<session_cookie>
Content-Type: application/json

{
  "userId": "uid123"
}

​
Status das integrações

Retorna se cada canal está ativo e configurado. Requer role ADMIN. 
GET /notificacoes/status
Cookie: imob_session=<session_cookie>
Resposta 200
{
  "email": {
    "ativo": true,
    "configurado": true
  },
  "sms": {
    "ativo": false,
    "configurado": false
  },
  "whatsapp": {
    "ativo": true,
    "configurado": true
  }
}

​
Histórico de notificações

Retorna as últimas notificações enviadas do usuário autenticado, ordenadas por enviadoEm decrescente.
​
contratoId
string
Filtra pelo contrato específico.
​
limite
number
default:"50"
Número máximo de registros retornados.
GET /notificacoes/historico?contratoId=con789&limite=20
Cookie: imob_session=<session_cookie>
Resposta 200
[
  {
    "id": "notif001",
    "userId": "uid123",
    "contratoId": "con789",
    "contaId": "fin001",
    "locatarioNome": "João da Silva",
    "locatarioEmail": "joao@email.com",
    "tipo": "VENCIMENTO",
    "assunto": "Lembrete: Seu aluguel vencerá em 3 dia(s)",
    "canaisUsados": ["email", "whatsapp_evolution"],
    "diasAntes": 3,
    "valor": 2500,
    "enviadoEm": "2025-02-01T08:00:00.000Z"
  }
]

​
Campo canaisUsados

Array com os canais que efetivamente receberam a notificação naquele disparo. Valores possíveis: email, sms, whatsapp_meta, whatsapp_evolution.