🧭 O que é e como funciona

O Revenda IPTV BR é um bot como serviço: o Admin fornece o cérebro (LLM da OpenRouter) e os Fornecedores plugam o bot no próprio painel IPTV (Xtream) via API. O bot entende comandos em português e executa ações no painel de quem chamou.

Também existe a camada de Revendedor: o fornecedor cria revendedores que consomem um auxiliar de dúvidas (IA + base de conhecimento) e recebem avisos ao vivo (sinal/VOD) — tudo sem acessar o painel do fornecedor.

👑 Tutorial do Admin (dono do bot)

1. Entrar: acesse /login com usuário admin e a senha forte (definida no deploy, em admin_pass.txt na VPS).
2. Chaves OpenRouter: vá em /admin/keys → "Adicionar chave".
   • Escolha Principal (só 1). As demais viram Fallbacks automaticamente.
   • Cole a chave sk-or-.... Ela é criptografada em repouso no banco (não fica em texto puro).
   • Adicione até 5 fallbacks com prioridade (menor = usado primeiro em falha da principal).
3. Modelo de LLM (operações): na mesma tela, defina o Modelo (ex: openai/gpt-4o-mini, anthropic/claude-3.5-sonnet, google/gemini-flash-1.5). Um modelo único vale para todas as chaves e clientes.
4. Modelo da Base de Conhecimento (economiza créditos): na mesma tela, campo "Modelo da Base de Conhecimento". Como as respostas dos revendedores vêm da base local + reescrita curta, use um modelo mais barato/rápido (ex: openai/gpt-4o-mini). Deixe em branco para usar o modelo acima. Respostas repetidas são cacheadas (0 créditos).
5. VPS em tempo real: no /admin veja CPU, RAM, Disco e Tráfego (atualiza sozinho a cada 3s).
6. OpenRouter: no painel admin veja tokens de entrada/saída totais, consumo por cliente e crédito restante (lido da própria OpenRouter). O crédito aparece só depois de cadastrar a chave principal.
7. Gerenciar clientes/fornecedores: em /admin/customers o admin cria manualmente as contas de fornecedor (usuário + senha + API key), além de bloquear (trava a API) ou gerar nova API key.

🧑‍💼 Tutorial do Fornecedor (quem compra o bot)

1. Acesso: o admin cria a conta manualmente (não há cadastro público) e entrega usuário + senha + API key única.
2. Seu painel IPTV (Xtream): em /dashboard → "Seu painel IPTV", cadastre URL / usuário / senha do seu painel Xtream. É nele que o bot cria, renova e suspende linhas. Senha criptografada no banco.
3. Testar no navegador: use /agent para conversar com o bot (ele opera o seu painel).
4. Integrar no seu sistema: chame a API do bot enviando comandos em texto (ver aba API).

📚 Base de conhecimento & Avisos (alimenta o auxiliar dos revendedores)

No /dashboard → "Base de conhecimento & Avisos":

• Status do SINAL / VOD: texto livre. Deixe em branco se normal. Ao preencher, vira aviso ao vivo para os revendedores.
• FAQ própria: observações, planos e regras do seu servidor (mesclado com a base estática que já vem no servidor).
• Webhook URL: endpoint seu que recebe eventos quando o status muda (veja aba API → Webhook). Você manda o WhatsApp pelo seu método — sem conta de terceiro.

🤝 Revendedores

No mesmo /dashboard → "Revendedores", crie contas de revendedor (subordinadas a você). Eles só consomem a base de conhecimento e os avisos — não acessam seu painel Xtream.

Comandos em linguagem natural (exemplos)

🤝 Painel do Revendedor

1. Quem cria: o fornecedor cria sua conta em /dashboard → Revendedores. Você recebe usuário + senha + API key.
2. Entrar: /login → vai para /reseller.
3. Avisos ao vivo: vê o status de SINAL e VOD que o fornecedor publicou.
4. Auxiliar de dúvidas (IA): em /agent (ou pela API) tire dúvidas de IPTV. A IA responde de forma humana e variada usando a base de conhecimento — não acessa o painel do fornecedor.
5. Integrar no seu próprio painel: use sua API key na rota POST /api/agent (ver aba API). Assim você embute o auxiliar dentro do seu painel de revendedor.

🔌 API do bot — POST /api/agent

Autentique com sua API key (header X-API-Key ou Authorization: Bearer). Envie prompt (texto livre, PT-BR).

• Fornecedor: o bot usa o LLM do admin e opera o seu painel Xtream (criar/renovar/suspender).
• Revendedor: o bot responde dúvidas usando a base de conhecimento (sem operar o painel).

cURL

Python

PHP

Resposta

Sem API key → 401. Sem chave OpenRouter cadastrada → mensagem de erro controlada (não quebra).

🔔 Webhook de avisos (eventos para o seu método mandar WhatsApp)

Ao mudar o status de SINAL/VOD, o bot faz POST JSON para a Webhook URL que o fornecedor cadastrou:

Você recebe o evento e formata a mensagem (ex: "Olá {name}, o sinal está {status}...") e envia pelo seu próprio WhatsApp. Sem provedor de WhatsApp terceiro.

🔐 Segurança & Segmentação dos dados

Banco: tudo vive em um SQLite na VPS do bot (/opt/revendaiptv/revenda.db). Backups = copiar esse arquivo.

❓ FAQ

Perdi a senha de admin: o implementador regera via admin_pass.txt na VPS.

Como cadastro um fornecedor? O admin cria manualmente em /admin/customers (sem cadastro público).

Como o revendedor pergunta? Ele entra em /reseller → /agent, ou chama a API com a API key dele. A resposta vem da base de conhecimento.

Quero gastar pouco com IA: deixe a base estática no servidor + use modelo barato na KB + aproveite o cache de respostas repetidas.

Como chega o aviso de sinal fora no WhatsApp? O fornecedor cadastra a Webhook URL; o bot dispara o evento; você formata e manda pelo seu método (sem terceiro).

A chave OpenRouter caiu (limite): o bot testa os fallbacks em ordem de prioridade automaticamente.

Como faço backup: copie /opt/revendaiptv/revenda.db da VPS.