Sistema de Notificações de Agendamentos

Sistema automatizado para buscar agendamentos da API Trinks, enriquecer dados dos clientes e enviar notificações via WhatsApp com confirmação interativa.

Estrutura do Projeto

notifications/
├── src/
│   ├── agendamentos/          # Módulo de leitura de agendamentos
│   │   └── ler-agendamentos-do-dia.py
│   ├── clientes/              # Módulo de enriquecimento de dados
│   │   └── enriquecer_dados.py
│   ├── notificacoes/          # Módulo de envio de notificações
│   │   ├── enviar.py
│   │   ├── webhook.py         # Servidor webhook para receber respostas
│   │   └── processar_resposta.py  # Processar confirmações
│   └── database/              # Módulo de banco de dados
│       └── schema.py
├── main.py                    # Script principal
├── .env                       # Variáveis de ambiente
├── notifications.db           # Banco SQLite (criado automaticamente)
└── WEBHOOK_SETUP.md           # Guia de configuração do webhook

Banco de Dados

O sistema usa SQLite com as seguintes tabelas:

agendamentos

• Armazena todos os agendamentos buscados da API
• Campos: id, cliente_id, cliente_nome, cliente_telefone, data_agendamento, horario, servico, status, etc.

clientes

• Armazena dados enriquecidos dos clientes
• Campos: id, cliente_id, nome, telefone, email, dados_completos

notificacoes

• Registra todas as notificações enviadas
• Campos: id, agendamento_id, cliente_id, telefone, tipo, mensagem, status, data_envio

Configuração

1. Variáveis de Ambiente

Edite o arquivo .env com suas credenciais:

API Trinks

TRINKS_API_TOKEN=seu_token_aqui
TRINKS_ESTABELECIMENTO_ID=seu_id_aqui

Twilio WhatsApp

TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=seu_auth_token_aqui
TWILIO_WHATSAPP_FROM=whatsapp:+14155238886

Para obter as credenciais Twilio:

1. Acesse Twilio Console
2. Copie o Account SID e Auth Token do dashboard
3. Para o número WhatsApp:
   • Sandbox (teste): Use whatsapp:+14155238886
   • Produção: Use seu número aprovado whatsapp:+55YYYYYYYYYY

Usando o Sandbox para Testes:

1. Acesse: https://console.twilio.com/us1/develop/sms/try-it-out/whatsapp-learn
2. Envie a mensagem de código para o número sandbox via WhatsApp
3. Exemplo: "join <seu-código>" para +1 (415) 523-8886
4. Agora pode testar enviando para números que fizeram join

2. Instalação de Dependências

O projeto usa UV para gerenciamento de pacotes:

uv sync

Como Usar

Fluxo Completo (Recomendado)

Executa todos os passos automaticamente:

uv run python main.py

Isso irá:

1. Buscar agendamentos do dia na API
2. Salvar no banco de dados
3. Enriquecer com dados dos clientes (telefones)
4. Enviar notificações com opção de confirmação

Executar Módulos Separadamente

1. Buscar apenas os agendamentos:

uv run python src/agendamentos/ler-agendamentos-do-dia.py

2. Enriquecer dados dos clientes:

uv run python src/clientes/enriquecer_dados.py

3. Enviar notificações:

uv run python src/notificacoes/enviar.py

4. Iniciar webhook para receber confirmações:

uv run python src/notificacoes/webhook.py

Veja WEBHOOK_SETUP.md para instruções de configuração.

Buscar Data Específica

Edite os scripts e descomente as linhas no final:

# Exemplo em main.py
executar_fluxo_completo("2026-01-10")

Funcionalidades

✅ Implementadas

• Buscar agendamentos da API Trinks
• Enriquecer dados com telefones dos clientes
• Enviar notificações via WhatsApp (Twilio)
• Sistema de confirmação interativa (SIM/NAO)
• Webhook para receber respostas dos clientes
• Atualização automática de status no banco
• Retry automático com backoff exponencial
• Registro completo de notificações

Confirmação Interativa

Quando um cliente recebe a notificação, ele pode responder:

Para confirmar:

• SIM, S, CONFIRMAR, CONFIRMO, OK

Para cancelar:

• NAO, N, CANCELAR, CANCELO

O sistema automaticamente:

1. Identifica o agendamento do cliente
2. Atualiza o status no banco de dados
3. Registra a confirmação/cancelamento
4. Envia mensagem de confirmação ao cliente

Veja WEBHOOK_SETUP.md para configurar o webhook.

Próximos Passos

Melhorias Sugeridas

• Adicionar agendamento automático (cron/scheduler)
• Migrar para WhatsApp Business API (produção)
• Adicionar logs estruturados
• Criar interface web (dashboard)
• Adicionar testes automatizados
• Configurar variáveis de ambiente para templates de mensagens
• Criar relatórios de envio
• Adicionar opção de reagendar via WhatsApp
• Implementar lembretes automáticos 24h antes

Dependências

• requests - Para chamadas à API Trinks
• python-dotenv - Para gerenciar variáveis de ambiente
• twilio - SDK oficial para Twilio WhatsApp API
• flask - Servidor web para webhook
• SQLite3 (built-in Python) - Banco de dados

Licença

Uso interno