Add TopSapp preliminary support

Signed-off-by: Rodrigo B. de Sousa Martins <rodrigo.sousa.577@gmail.com>
2025-08-08 18:40:39 -03:00
1 parent d4c37a3f78
commit 723ad8c268
@@ -0,0 +1,202 @@
+# Integração TopSapp - Bot de Ajuda
+
+## 📋 Visão Geral
+
+Esta integração permite ao bot interagir com o sistema TopSapp para gerenciar clientes, faturas e serviços através de comandos naturais no Telegram.
+
+## 🏢 Instâncias Configuradas
+
+### Guarai/Colmeia
+- **Host**: 131.0.192.6
+- **Porta**: 443 (HTTPS)
+- **Localização**: Guarai e Colmeia
+
+### Pedro Afonso
+- **Host**: 45.189.140.18  
+- **Porta**: 443 (HTTPS)
+- **Localização**: Pedro Afonso
+
+## ⚙️ Configuração
+
+### 1. Variáveis de Ambiente
+
+Adicione as seguintes variáveis no arquivo `.env`:
+
+```bash
+# TopSapp - Instância Guarai/Colmeia
+TOPSAPP_GUARAI_USER=seu_usuario_guarai
+TOPSAPP_GUARAI_PASS=sua_senha_guarai
+
+# TopSapp - Instância Pedro Afonso  
+TOPSAPP_PEDRO_AFONSO_USER=seu_usuario_pedro_afonso
+TOPSAPP_PEDRO_AFONSO_PASS=sua_senha_pedro_afonso
+```
+
+### 2. Dependências
+
+As seguintes dependências são necessárias:
+- `axios` - Para requisições HTTP
+- `form-data` - Para upload de formulários
+- `https` - Para certificados SSL personalizados
+
+## 🔧 Comandos Disponíveis
+
+### 📊 Status do Sistema
+```
+status topsapp
+verificar topsapp
+```
+
+### 🔍 Buscar Clientes
+```
+buscar cliente João da Silva
+buscar cliente 123.456.789-10
+buscar cliente Guarai João (específica instância)
+buscar cliente Pedro Afonso Maria
+```
+
+### 📄 Ver Faturas
+```
+ver faturas 123.456.789-10
+ver faturas cliente123
+ver faturas Guarai 123.456.789-10
+```
+
+### 💸 Gerar Boletos
+```
+gerar boleto 12345
+gerar boleto fatura123
+```
+
+### 🔒 Bloquear Clientes
+```
+bloquear cliente 456
+bloquear 789
+```
+
+### 🔓 Liberar Clientes
+```
+liberar cliente 456
+liberar 789
+```
+
+## 🚀 Funcionalidades
+
+### ✅ Autenticação Automática
+- Login automático com credenciais configuradas
+- Gerenciamento de sessões com expiração
+- Renovação automática de tokens
+
+### 🌐 Multi-instância
+- Detecção automática da instância por localização
+- Roteamento de requisições para servidor correto
+- Suporte a múltiplas configurações
+
+### 📋 Gestão de Clientes
+- Busca por nome, CPF ou ID
+- Visualização de dados completos
+- Histórico de serviços e faturas
+
+### 💰 Sistema de Faturamento
+- Listagem de faturas pendentes e pagas
+- Geração de boletos em PDF
+- Linha digitável para pagamento
+
+### 🔐 Controle de Serviços
+- Bloqueio de serviços em massa
+- Liberação de serviços bloqueados
+- Confirmação antes de ações críticas
+
+### 📊 Relatórios e Status
+- Status de configuração do sistema
+- Estatísticas de uso por instância
+- Monitoramento de conectividade
+
+## 🔧 Arquitetura
+
+### Classes Principais
+
+#### `TopSappAPI`
+- Gerencia autenticação e sessões
+- Executa requisições para a API
+- Converte Base64 para PDF
+
+#### `TopSappConfig`
+- Carrega configurações do ambiente
+- Valida credenciais disponíveis
+- Fornece dados de instâncias
+
+#### `TopSappManager`
+- Interface principal para o bot
+- Coordena operações complexas
+- Trata erros e formatação
+
+## 📝 Logs e Debug
+
+O sistema gera logs detalhados:
+- `🎯` - Inicialização de componentes
+- `🔐` - Operações de autenticação
+- `📡` - Requisições para API
+- `✅` - Operações bem-sucedidas
+- `❌` - Erros e falhas
+
+## ⚠️ Considerações de Segurança
+
+- Certificados SSL auto-assinados são aceitos
+- Sessões expiram automaticamente em 30 minutos
+- Credenciais são armazenadas em variáveis de ambiente
+- Timeout de 10 segundos para requisições
+
+## 🐛 Troubleshooting
+
+### Erro de Autenticação
+1. Verificar credenciais no `.env`
+2. Testar login manual no TopSapp
+3. Verificar conectividade com o servidor
+
+### Timeout de Conexão
+1. Verificar conectividade de rede
+2. Confirmar se os serviços estão online
+3. Ajustar timeout se necessário
+
+### Erro de Certificado SSL
+- O sistema já está configurado para aceitar certificados auto-assinados
+- Verificar se o hostname está correto
+
+## 📈 Métricas de Performance
+
+- Sessões mantidas por até 30 minutos
+- Timeout de requisições: 10 segundos
+- Suporte a operações simultâneas
+- Cache de configurações carregadas
+
+## 🔄 Manutenção
+
+### Limpeza de Sessões
+- Sessões expiradas são limpas automaticamente
+- Intervalo de limpeza: 10 minutos
+
+### Renovação de Tokens
+- Detecção automática de expiração
+- Re-autenticação transparente
+- Sem interrupção do serviço
+
+---
+
+## 💡 Exemplos de Uso
+
+### Fluxo Completo de Atendimento
+1. `buscar cliente João da Silva`
+2. `ver faturas 123.456.789-10` 
+3. `gerar boleto 12345`
+4. `bloquear cliente 456` (se necessário)
+
+### Verificação de Status
+1. `status topsapp`
+2. Verificar configurações
+3. Testar conectividade
+
+### Operações por Localização
+- `buscar cliente Guarai João` → Busca apenas em Guarai/Colmeia
+- `buscar cliente Pedro Afonso Maria` → Busca apenas em Pedro Afonso
+- `buscar cliente João` → Busca em todas as instâncias