203 lines
4.8 KiB
Markdown
203 lines
4.8 KiB
Markdown
# 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
|