# 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