Notificações

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

Canal	Provedor	Configuração necessária
E-mail	Brevo (SMTP)	`brevoApiKey` + `brevoEmailRemetente`
SMS	Brevo (SMS)	`brevoSmsApiKey` + `brevoSmsSender`
WhatsApp (templates)	Meta Business API	`whatsappToken` + `whatsappPhoneId`
WhatsApp (texto livre)	Evolution API	`EVOLUTION_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

Tipo	`diasAntes`	Disparo
`VENCIMENTO`	`> 0`	X dias antes do vencimento (configurável)
`VENCIMENTO`	`0`	No dia do vencimento
`INADIMPLENCIA`	`< 0`	X 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.

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.

string

Filtra pelo contrato específico.

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.

Gestão

Financeiro

Vistoria & Inventário

Plataforma

Visão Geral

Canais suportados

Tipos de notificação

Cron — Executar rotina diária

Disparar manualmente

Status das integrações

Histórico de notificações

Campo `canaisUsados`

​Visão Geral

​Canais suportados

​Tipos de notificação

​Cron — Executar rotina diária

​Disparar manualmente

​Status das integrações

​Histórico de notificações

​Campo canaisUsados

Visão Geral

Canais suportados

Tipos de notificação

Cron — Executar rotina diária

Disparar manualmente

Status das integrações

Histórico de notificações

Campo `canaisUsados`