4.8 KiB
4.8 KiB
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:
# 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 HTTPform-data- Para upload de formulárioshttps- 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
- Verificar credenciais no
.env - Testar login manual no TopSapp
- Verificar conectividade com o servidor
Timeout de Conexão
- Verificar conectividade de rede
- Confirmar se os serviços estão online
- 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
buscar cliente João da Silvaver faturas 123.456.789-10gerar boleto 12345bloquear cliente 456(se necessário)
Verificação de Status
status topsapp- Verificar configurações
- Testar conectividade
Operações por Localização
buscar cliente Guarai João→ Busca apenas em Guarai/Colmeiabuscar cliente Pedro Afonso Maria→ Busca apenas em Pedro Afonsobuscar cliente João→ Busca em todas as instâncias