> ## Documentation Index
> Fetch the complete documentation index at: https://docs.patrimonion.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Notificações

> Disparo automático e manual de avisos de vencimento e inadimplência via e-mail, SMS e WhatsApp. Histórico completo por contrato.

## 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` |

<Info>
  Evolution API e Meta WhatsApp são mutuamente exclusivos por disparo — se `evolutionAtivo` estiver habilitado, ele tem prioridade sobre o Meta.
</Info>

### 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.

```http theme={null}
POST /notificacoes/cron/executar
Authorization: Bearer <CRON_SECRET>
```

```json Resposta 200 theme={null}
{
  "sucesso": true,
  "totalGeral": 14,
  "resultados": [
    {
      "userId": "uid123",
      "totalEnviadas": 8,
      "detalhes": [
        {
          "locatario": "João da Silva",
          "tipo": "VENCIMENTO",
          "diasAntes": 3,
          "valor": 2500
        }
      ]
    }
  ]
}
```

<Warning>
  Qualquer requisição sem o header `Authorization: Bearer <CRON_SECRET>` retorna `401`. Configure `CRON_SECRET` no `.env` do servidor.
</Warning>

***

## Disparar manualmente

Requer autenticação e role `SUPER_ADMIN` ou `ADMIN`. Útil para testar o fluxo sem esperar o cron.

<ParamField body="userId" type="string">
  Se informado, dispara apenas para o locador especificado. Se omitido, processa todos os locadores ativos.
</ParamField>

```http theme={null}
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`.

```http theme={null}
GET /notificacoes/status
Cookie: imob_session=<session_cookie>
```

```json Resposta 200 theme={null}
{
  "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.

<ParamField query="contratoId" type="string">
  Filtra pelo contrato específico.
</ParamField>

<ParamField query="limite" type="number" default="50">
  Número máximo de registros retornados.
</ParamField>

```http theme={null}
GET /notificacoes/historico?contratoId=con789&limite=20
Cookie: imob_session=<session_cookie>
```

```json Resposta 200 theme={null}
[
  {
    "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`.