416 lines
9.2 KiB
Markdown
416 lines
9.2 KiB
Markdown
# 🔔 Sistema de Alertas Automáticos de Vencimento
|
|
|
|
## 📋 Problema Identificado
|
|
|
|
**Situação:**
|
|
- Venda realizada em 20/10/2025
|
|
- Primeira parcela com vencimento em 24/10/2025
|
|
- **Alertas NÃO foram enviados:**
|
|
- ❌ 3 dias antes (21/10) - Não recebido
|
|
- ❌ No dia do vencimento (24/10) - Não recebido com PIX
|
|
|
|
**Causa:**
|
|
O sistema de alertas automáticos **não estava configurado** para rodar diariamente às 09:00.
|
|
|
|
---
|
|
|
|
## ✅ Solução Implementada
|
|
|
|
Criamos um sistema completo de alertas automáticos com:
|
|
|
|
1. **Script Node.js** que verifica parcelas e envia alertas
|
|
2. **Cron Job** configurado para executar às 09:00 (Brasília)
|
|
3. **Geração automática de PIX** no dia do vencimento
|
|
4. **Logs** de todas as execuções
|
|
|
|
---
|
|
|
|
## 🚀 Como Instalar
|
|
|
|
### Passo 1: Instalar o Cron Job
|
|
|
|
```bash
|
|
cd /home/tiago/Downloads/app_estoque_v1.0.0
|
|
chmod +x scripts/instalar-cron-alertas.sh
|
|
./scripts/instalar-cron-alertas.sh
|
|
```
|
|
|
|
O script irá:
|
|
- ✅ Configurar execução diária às 09:00 (horário de Brasília)
|
|
- ✅ Criar diretório de logs
|
|
- ✅ Perguntar se quer fazer um teste imediato
|
|
- ✅ Mostrar configuração final
|
|
|
|
### Passo 2: Configurar Variáveis de Ambiente
|
|
|
|
Crie/edite o arquivo `.env` na raiz do projeto:
|
|
|
|
```bash
|
|
# Supabase
|
|
SUPABASE_URL=https://ydhzylfnpqlxnzfcclla.supabase.co
|
|
SUPABASE_SERVICE_KEY=seu_service_key_aqui
|
|
# ou
|
|
SUPABASE_ANON_KEY=seu_anon_key_aqui
|
|
|
|
# Evolution API (configurar no painel admin)
|
|
# Mercado Pago (configurar no painel admin)
|
|
```
|
|
|
|
### Passo 3: Configurar no Painel Admin
|
|
|
|
Acesse o painel admin → Configurações e configure:
|
|
|
|
**Evolution API:**
|
|
- URL da API
|
|
- Nome da instância
|
|
- API Key
|
|
|
|
**Mercado Pago:**
|
|
- Access Token (para geração de PIX)
|
|
|
|
**Alertas WhatsApp:**
|
|
- Primeiro alerta: 3 dias antes ✅ ATIVO
|
|
- Segundo alerta: No dia (0 dias) ✅ ATIVO
|
|
- Alerta após vencimento: 3 dias após ✅ ATIVO
|
|
- Mensagens personalizadas para cada tipo
|
|
|
|
---
|
|
|
|
## 🕐 Como Funciona
|
|
|
|
### Execução Automática
|
|
|
|
**Horário:** Todos os dias às 09:00 (horário de Brasília)
|
|
|
|
**O que o script faz:**
|
|
|
|
1. **Busca configurações** do banco de dados
|
|
2. **Lista todas as parcelas pendentes**
|
|
3. **Calcula dias para vencimento** de cada parcela
|
|
4. **Verifica se deve enviar alerta:**
|
|
- Primeiro alerta: 3 dias antes? ✅
|
|
- Segundo alerta: No dia? ✅ + Gera PIX
|
|
- Alerta pós-vencimento: 3 dias após? ✅
|
|
5. **Substitui variáveis** na mensagem:
|
|
- `{cliente}` → Nome do cliente
|
|
- `{valor}` → R$ 150,00
|
|
- `{quando}` → "em 3 dias" ou "hoje" ou "há 3 dias"
|
|
- `{parcela}` → "1/3"
|
|
6. **Envia via WhatsApp** usando Evolution API
|
|
7. **Registra no histórico** de mensagens
|
|
8. **Gera log** completo da execução
|
|
|
|
---
|
|
|
|
## 📱 Tipos de Alertas
|
|
|
|
### 1. Primeiro Alerta (3 dias antes)
|
|
|
|
**Quando:** 21/10 às 09:00 para vencimento em 24/10
|
|
|
|
**Mensagem padrão:**
|
|
```
|
|
Olá João! 👋
|
|
|
|
Lembramos que você tem uma parcela no valor de R$ 150,00 com vencimento em 3 dias (24/10/2025).
|
|
|
|
Agradecemos a atenção!
|
|
```
|
|
|
|
### 2. Segundo Alerta (No dia do vencimento)
|
|
|
|
**Quando:** 24/10 às 09:00
|
|
|
|
**Mensagem padrão:**
|
|
```
|
|
Olá João! 👋
|
|
|
|
Sua parcela de R$ 150,00 vence hoje.
|
|
|
|
📱 PIX Copia e Cola:
|
|
```00020126580014br.gov.bcb.pix...```
|
|
|
|
Agradecemos!
|
|
```
|
|
|
|
**Ação extra:** Gera PIX automaticamente via Mercado Pago
|
|
|
|
### 3. Alerta Após Vencimento (3 dias após)
|
|
|
|
**Quando:** 27/10 às 09:00 para vencimento em 24/10
|
|
|
|
**Mensagem padrão:**
|
|
```
|
|
Olá João! 👋
|
|
|
|
Identificamos que a parcela 1/3 no valor de R$ 150,00 venceu há 3 dias (24/10/2025).
|
|
|
|
Por favor, regularize o pagamento.
|
|
```
|
|
|
|
---
|
|
|
|
## 📊 Monitoramento
|
|
|
|
### Ver Logs em Tempo Real
|
|
|
|
```bash
|
|
tail -f /home/tiago/Downloads/app_estoque_v1.0.0/logs/alertas-cron.log
|
|
```
|
|
|
|
### Exemplo de Log
|
|
|
|
```
|
|
🕐 Iniciando envio de alertas de vencimento...
|
|
⏰ Horário: 24/10/2025, 09:00:15
|
|
|
|
📋 Configurações carregadas:
|
|
- Primeiro alerta: 3 dias antes (ATIVO)
|
|
- Segundo alerta: 0 dias antes (ATIVO)
|
|
- Alerta pós-vencimento: 3 dias após (ATIVO)
|
|
|
|
📦 15 parcela(s) pendente(s) encontrada(s)
|
|
|
|
📤 Enviando segundo_alerta para João Silva (5543999762754)...
|
|
🔄 Gerando PIX para parcela 1...
|
|
✅ Enviado com sucesso!
|
|
|
|
📤 Enviando primeiro_alerta para Maria Santos (5543988776655)...
|
|
✅ Enviado com sucesso!
|
|
|
|
==================================================
|
|
📊 RESUMO DO ENVIO
|
|
==================================================
|
|
✅ Alertas enviados: 8
|
|
❌ Erros: 0
|
|
📦 Total de parcelas verificadas: 15
|
|
==================================================
|
|
|
|
✅ Script finalizado com sucesso!
|
|
```
|
|
|
|
---
|
|
|
|
## 🧪 Teste Manual
|
|
|
|
Para testar o sistema sem esperar às 09:00:
|
|
|
|
```bash
|
|
cd /home/tiago/Downloads/app_estoque_v1.0.0
|
|
node scripts/enviar-alertas-parcelas.js
|
|
```
|
|
|
|
Isso executará imediatamente e mostrará:
|
|
- Quais alertas seriam enviados
|
|
- Para quais clientes
|
|
- Resultado de cada envio
|
|
|
|
---
|
|
|
|
## 🔍 Verificar Cron Instalado
|
|
|
|
```bash
|
|
crontab -l
|
|
```
|
|
|
|
Deve mostrar algo como:
|
|
```
|
|
0 12 * * * TZ='America/Sao_Paulo' /usr/bin/node /home/tiago/Downloads/app_estoque_v1.0.0/scripts/enviar-alertas-parcelas.js >> /home/tiago/Downloads/app_estoque_v1.0.0/logs/alertas-cron.log 2>&1
|
|
```
|
|
|
|
**Nota:** `0 12` em UTC = 09:00 em Brasília (UTC-3)
|
|
|
|
---
|
|
|
|
## 🛠️ Troubleshooting
|
|
|
|
### Problema: Alertas não são enviados
|
|
|
|
**Verificar:**
|
|
|
|
1. **Cron está instalado?**
|
|
```bash
|
|
crontab -l | grep enviar-alertas-parcelas
|
|
```
|
|
|
|
2. **Script tem permissão de execução?**
|
|
```bash
|
|
ls -l scripts/enviar-alertas-parcelas.js
|
|
chmod +x scripts/enviar-alertas-parcelas.js
|
|
```
|
|
|
|
3. **Configurações estão corretas no admin?**
|
|
- Evolution API configurada
|
|
- Mercado Pago configurado
|
|
- Alertas ATIVOS (toggles verdes)
|
|
|
|
4. **Clientes têm WhatsApp cadastrado?**
|
|
```sql
|
|
SELECT nome_completo, whatsapp
|
|
FROM clientes
|
|
WHERE whatsapp IS NULL OR whatsapp = '';
|
|
```
|
|
|
|
5. **Parcelas estão com status "pendente"?**
|
|
```sql
|
|
SELECT * FROM venda_parcelas
|
|
WHERE status = 'pendente'
|
|
ORDER BY data_vencimento;
|
|
```
|
|
|
|
6. **Ver logs de erro:**
|
|
```bash
|
|
tail -100 logs/alertas-cron.log
|
|
```
|
|
|
|
### Problema: PIX não é gerado
|
|
|
|
**Verificar:**
|
|
|
|
1. **Mercado Pago Access Token configurado?**
|
|
- Painel Admin → Configurações → Mercado Pago
|
|
|
|
2. **Token válido?**
|
|
- Tokens expiram, gere um novo se necessário
|
|
|
|
3. **Testar geração manual:**
|
|
- Sistema de Vendas → Parcelas → Botão "PIX"
|
|
|
|
### Problema: Mensagens não chegam
|
|
|
|
**Verificar:**
|
|
|
|
1. **Evolution API está online?**
|
|
- Teste acessando a URL configurada
|
|
|
|
2. **Instância está conectada?**
|
|
- Verifique no painel da Evolution API
|
|
|
|
3. **WhatsApp do cliente correto?**
|
|
- Formato: apenas números (5543999762754)
|
|
- Com DDD e código do país
|
|
|
|
4. **Testar envio manual:**
|
|
- Sistema de Vendas → Chat WhatsApp
|
|
|
|
---
|
|
|
|
## 📅 Cronograma de Alertas
|
|
|
|
### Exemplo: Venda em 20/10, vencimento 24/10
|
|
|
|
| Data | Hora | Tipo de Alerta | Dias | Ação |
|
|
|------|------|----------------|------|------|
|
|
| 21/10 | 09:00 | Primeiro Alerta | -3 dias | Lembrete |
|
|
| 24/10 | 09:00 | Segundo Alerta | 0 dia (hoje) | Lembrete + PIX |
|
|
| 27/10 | 09:00 | Pós-Vencimento | +3 dias | Cobrança |
|
|
|
|
---
|
|
|
|
## 🔄 Desinstalar Cron
|
|
|
|
Se precisar remover o cron:
|
|
|
|
```bash
|
|
crontab -e
|
|
```
|
|
|
|
Remova a linha que contém `enviar-alertas-parcelas.js` e salve.
|
|
|
|
Ou automaticamente:
|
|
|
|
```bash
|
|
crontab -l | grep -v 'enviar-alertas-parcelas' | crontab -
|
|
```
|
|
|
|
---
|
|
|
|
## 📝 Personalizar Mensagens
|
|
|
|
No painel admin → Configurações → Alertas WhatsApp
|
|
|
|
**Variáveis disponíveis:**
|
|
- `{cliente}` - Primeiro nome do cliente
|
|
- `{valor}` - Valor formatado (R$ 150,00)
|
|
- `{quando}` - "em 3 dias", "hoje", "há 3 dias"
|
|
- `{parcela}` - "1/3", "2/5", etc.
|
|
|
|
**Exemplo de mensagem personalizada:**
|
|
```
|
|
Oi {cliente}! 😊
|
|
|
|
Sua parcela {parcela} de {valor} vence {quando}.
|
|
|
|
Qualquer dúvida, estamos aqui!
|
|
|
|
*Liberi Kids* 👗👕
|
|
```
|
|
|
|
---
|
|
|
|
## 🎯 Caso de Uso: Venda 20/10
|
|
|
|
**Configuração:**
|
|
- Primeiro alerta: 3 dias antes ✅
|
|
- Segundo alerta: No dia ✅
|
|
- Pós-vencimento: 3 dias após ✅
|
|
|
|
**Timeline:**
|
|
|
|
| Dia | Evento |
|
|
|-----|--------|
|
|
| **20/10** | Venda realizada, parcela 1 vence 24/10 |
|
|
| **21/10 09:00** | 🔔 Primeiro alerta enviado: "vence em 3 dias" |
|
|
| **24/10 09:00** | 🔔 Segundo alerta + PIX: "vence hoje" + QR Code |
|
|
| **27/10 09:00** | 🔔 Alerta pós-venc: "venceu há 3 dias" |
|
|
|
|
---
|
|
|
|
## ✅ Checklist de Verificação
|
|
|
|
Antes de considerar o sistema funcionando, verifique:
|
|
|
|
- [ ] Cron instalado e ativo (`crontab -l`)
|
|
- [ ] Horário correto (09:00 Brasília = 12:00 UTC)
|
|
- [ ] Evolution API configurada no admin
|
|
- [ ] Mercado Pago configurado no admin
|
|
- [ ] Alertas ATIVOS (toggles verdes)
|
|
- [ ] Mensagens personalizadas configuradas
|
|
- [ ] Teste manual executado com sucesso
|
|
- [ ] Logs sendo gerados em `/logs/alertas-cron.log`
|
|
- [ ] Clientes com WhatsApp cadastrado
|
|
- [ ] Parcelas com status "pendente"
|
|
|
|
---
|
|
|
|
## 📞 Suporte
|
|
|
|
**Logs importantes:**
|
|
```bash
|
|
# Logs do cron
|
|
tail -f logs/alertas-cron.log
|
|
|
|
# Logs do servidor
|
|
tail -f logs/server.log
|
|
|
|
# Histórico de mensagens (SQL)
|
|
SELECT * FROM mensagens_whatsapp
|
|
ORDER BY created_at DESC
|
|
LIMIT 50;
|
|
|
|
# Parcelas pendentes
|
|
SELECT vp.*, v.id_venda, c.nome_completo, c.whatsapp
|
|
FROM venda_parcelas vp
|
|
JOIN vendas v ON vp.venda_id = v.id
|
|
JOIN clientes c ON v.cliente_id = c.id
|
|
WHERE vp.status = 'pendente'
|
|
ORDER BY vp.data_vencimento;
|
|
```
|
|
|
|
---
|
|
|
|
**Desenvolvido para: Liberi Kids - Moda Infantil** 👗👕
|
|
**Data: 24 de outubro de 2025**
|
|
**Versão: 1.0**
|
|
**Status: ✅ Pronto para Produção**
|