🔧 API Koffice v2.0
A API Koffice é um sistema multitenancy robusto para automação de painéis IPTV. Permite renovação automatizada de clientes e geração de testes através de uma API REST segura e escalável.
http://localhost:3000📅 Última Atualização: 17 de Junho de 2025
👨💻 Sistema: Koffice System
🚀 Características Principais
Múltiplos usuários isolados com dados completamente separados
Renovação automática de clientes e geração de testes
Proteção robusta contra abuso e sobrecarga
Rastreamento completo de todas as operações
Autenticação por tokens seguros e criptografados
Gerenciamento completo de usuários e configurações
📊 Estrutura da Resposta de Sucesso
| Campo | Tipo | Descrição |
|---|---|---|
status |
string | Status da operação ("sucesso" ou "erro") |
mensagem |
string | Mensagem descritiva do resultado |
dados.cliente |
string | Nome do cliente que foi renovado |
dados.meses_renovados |
integer | Quantidade de meses adicionados |
dados.nova_data_vencimento |
string | Nova data de vencimento (formato DD/MM/YYYY HH:MM) |
dados.operacao_id |
string | ID único da operação para rastreamento |
request_id |
string|null | ID da requisição (usado para debugging) |
execution_time_ms |
integer | Tempo de execução em milissegundos |
tenant |
string | Nome/identificação do tenant |
timestamp |
string | Data/hora da operação (formato YYYY-MM-DD HH:MM:SS) |
🔐 Autenticação
A API utiliza dois tipos de autenticação via headers HTTP para garantir máxima segurança:
🔑 Autenticação de Usuário
Para operações de usuário (renovar, testar, stats):
x-api-key: ffbb4c05b474514fea8265209574a30c0ccb5c7f5bf8deb167c6ba6b3872a3bd
🛡️ Autenticação Administrativa
Para gerenciamento de usuários e configurações do sistema:
x-admin-token: admin_token_dev_12345
⚡ Rate Limiting
| Tipo | Limite | Janela | Aplicação |
|---|---|---|---|
| Global | 100 requisições | 15 minutos | Por IP |
| Tenant | 30 requisições | 1 minuto | Por usuário |
| Operações Diárias | 1000 operações | 24 horas | Por tenant |
•
X-RateLimit-Limit: Limite máximo configurado•
X-RateLimit-Remaining: Requisições restantes no período•
X-RateLimit-Reset: Timestamp do próximo reset
🟢 GET /health
Verificação completa de saúde da API e conectividade com banco de dados. Ideal para monitoramento e health checks.
📋 Exemplo de Requisição
curl -X GET http://localhost:3000/health
{
"status": "sucesso",
"mensagem": "API Koffice Multitenancy funcionando",
"timestamp": "2025-06-17 20:45:30",
"version": "2.0.0-multitenancy",
"database": "conectado"
}
{
"status": "erro",
"mensagem": "Erro na verificação de saúde",
"timestamp": "2025-06-17 20:45:30",
"database": "erro"
}
🟢 GET /status
Status básico e rápido da API para verificações simples de conectividade.
📋 Exemplo de Requisição
curl -X GET http://localhost:3000/status
{
"status": "ativo",
"mensagem": "Koffice API funcionando",
"timestamp": "2025-06-17 20:45:30"
}
📦 POST /renovar
Renovar um cliente IPTV no painel usando o script renovar-multitenant.js. Automatiza completamente o processo de renovação com validações de segurança.
📝 Parâmetros
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
cliente |
string | ✅ Sim | Nome exato do cliente a ser renovado |
meses |
integer | ✅ Sim | Quantidade de meses para renovar (1-12) |
• >30 dias restantes: Renovação ignorada (cliente não precisa)
• ≤30 dias restantes: Renovação executada
• Vencido: Renovação executada normalmente
📅 Formato de Data:
•
nova_data_vencimento: Formato brasileiro DD/MM/YYYY HH:MM•
timestamp: Formato ISO YYYY-MM-DD HH:MM:SS
📋 Exemplo de Requisição
curl -X POST http://localhost:3000/renovar \
-H "Content-Type: application/json" \
-H "x-api-key: ffbb4c05b474514fea8265209574a30c0ccb5c7f5bf8deb167c6ba6b3872a3bd" \
-d '{
"cliente": "João Silva",
"meses": 3
}'
{
"status": "sucesso",
"mensagem": "Cliente renovado com sucesso",
"dados": {
"cliente": "João Silva",
"meses_renovados": 3,
"nova_data_vencimento": "19/09/2025 21:50",
"operacao_id": "op_123456789"
},
"request_id": null,
"execution_time_ms": 2340,
"tenant": "empresa-teste-ltda",
"timestamp": "2025-06-17 20:45:30"
}
{
"status": "erro",
"mensagem": "Meses deve ser um número entre 1 e 12",
"tenant": "empresa-teste-ltda",
"timestamp": "2025-06-17 20:45:30"
}
{
"status": "erro",
"mensagem": "Erro interno na renovação",
"detalhe": "Cliente não encontrado no painel",
"tenant": "empresa-teste-ltda",
"timestamp": "2025-06-17 20:45:30"
}
🧪 POST /teste
Gerar um teste IPTV para usuário final usando o script teste-multitenant.js. IMPORTANTE: Este endpoint gera um teste IPTV para o usuário final, não testa conectividade do painel.
🔄 Processo de Geração
Autentica com as credenciais do tenant
Procura pelo botão "TESTE IPTV" no painel
Clica no botão para gerar o teste IPTV
Obtém mensagem de resultado do teste gerado
Fornece informações estruturadas do teste
📋 Exemplo de Requisição
curl -X POST http://localhost:3000/teste \ -H "Content-Type: application/json" \ -H "x-api-key: ffbb4c05b474514fea8265209574a30c0ccb5c7f5bf8deb167c6ba6b3872a3bd"
{
"status": "sucesso",
"mensagem": "Teste IPTV gerado com sucesso",
"dados": {
"resultado_teste": "Seu teste foi criado com sucesso!\n\nSegue seus dados de acesso:\nUsuário: gq1lne2\nSenha: 6ilbu3x\nLista M3U: http://tinyurl.com/2bpxkvk4\n\nAtt. Servidor.",
"dados_estruturados": {
"texto_completo": "Seu teste foi criado com sucesso!\n\nSegue seus dados de acesso:\nUsuário: gq1lne2\nSenha: 6ilbu3x\nLista M3U: http://tinyurl.com/2bpxkvk4\n\nAtt. Servidor.",
"usuario": "gq1lne2",
"senha": "6ilbu3x",
"url_m3u": "http://tinyurl.com/2bpxkvk4",
"duracao": null
},
"seletor_usado": ".fast-test-message",
"timestamp": "2025-06-18 14:31:19"
},
"execution_time_ms": 11562,
"tenant": "Daniel Reis",
"timestamp": "2025-06-18 14:31:19"
}
{
"status": "sucesso",
"mensagem": "Teste IPTV executado (dados não capturados)",
"dados": {
"resultado_teste": "Teste executado com sucesso, mas dados específicos não foram encontrados",
"observacao": "O teste foi executado, mas não foi possível capturar usuário/senha/URLs. Verifique manualmente no painel.",
"seletor_usado": "execucao_sem_dados",
"timestamp": "2025-06-18 14:31:19"
},
"execution_time_ms": 8200,
"tenant": "Daniel Reis",
"timestamp": "2025-06-18 14:31:19"
}
{
"status": "erro",
"mensagem": "Erro ao gerar teste IPTV",
"detalhe": "Botão \"TESTE IPTV\" não encontrado no painel",
"execution_time_ms": 12000,
"tenant": "Daniel Reis",
"timestamp": "2025-06-18 14:31:19"
}
📊 Estrutura dos Dados Estruturados
| Campo | Tipo | Descrição |
|---|---|---|
texto_completo |
string | Texto original completo retornado pelo painel |
usuario |
string|null | Usuário IPTV extraído automaticamente |
senha |
string|null | Senha IPTV extraída automaticamente |
url_m3u |
string|null | URL da playlist M3U extraída automaticamente |
duracao |
string|null | Duração/validade do teste (quando disponível) |
null, mas o texto original sempre estará disponível.📅 Formato Temporal: Timestamps seguem o padrão brasileiro YYYY-MM-DD HH:MM:SS para consistência com outras operações.
📊 GET /stats
Verificar status completo e saúde do usuário/tenant, incluindo conectividade e limites de uso.
📋 Exemplo de Requisição
curl -X GET http://localhost:3000/stats \ -H "x-api-key: ffbb4c05b474514fea8265209574a30c0ccb5c7f5bf8deb167c6ba6b3872a3bd"
{
"status": "sucesso",
"tenant": "empresa-teste-ltda",
"connectivity": {
"panel_status": "conectado",
"last_test": "2025-06-17 20:30:15",
"last_operation": "2025-06-17 19:45:22"
},
"limits": {
"daily_operations": 45,
"daily_limit": 1000,
"remaining": 955,
"rate_limit_ok": true
},
"health": "ok",
"timestamp": "2025-06-17 20:45:30"
}
{
"status": "sucesso",
"tenant": "empresa-teste-ltda",
"connectivity": {
"panel_status": "conectado",
"last_test": "2025-06-17 20:30:15",
"last_operation": "2025-06-17 19:45:22"
},
"limits": {
"daily_operations": 995,
"daily_limit": 1000,
"remaining": 5,
"rate_limit_ok": true
},
"health": "warning",
"timestamp": "2025-06-17 20:45:30"
}
{
"status": "sucesso",
"tenant": "empresa-teste-ltda",
"connectivity": {
"panel_status": "erro",
"last_test": "2025-06-17 18:30:15",
"last_operation": "2025-06-17 17:45:22"
},
"limits": {
"daily_operations": 234,
"daily_limit": 1000,
"remaining": 766,
"rate_limit_ok": true
},
"health": "error",
"timestamp": "2025-06-17 20:45:30"
}
👤 POST /admin/users
Criar novo usuário/tenant no sistema com configurações personalizadas e geração automática de URLs.
📝 Parâmetros
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
nome |
string | ✅ Sim | Nome da empresa/usuário |
panel_url |
string | ✅ Sim | URL do painel IPTV |
panel_username |
string | ✅ Sim | Usuário do painel |
panel_password |
string | ✅ Sim | Senha do painel |
settings |
object | ❌ Não | Configurações específicas |
•
clients_url: Construída automaticamente adicionando /clients à URL original•
panel_login_url: Adicionado /login se não existirExemplos:
•
https://painel.com → https://painel.com/login + https://painel.com/clients•
https://painel.com/admin → https://painel.com/admin/login + https://painel.com/admin/clients
⚙️ Configurações Opcionais (settings)
| Campo | Tipo | Padrão | Descrição |
|---|---|---|---|
max_operations_per_day |
integer | 1000 | Limite diário de operações |
rate_limit_per_minute |
integer | 30 | Limite por minuto |
📋 Exemplo de Requisição
curl -X POST http://localhost:3000/admin/users \
-H "Content-Type: application/json" \
-H "x-admin-token: admin_token_dev_12345" \
-d '{
"nome": "Empresa Nova LTDA",
"panel_url": "https://painel-novo.exemplo.com",
"panel_username": "admin_empresa",
"panel_password": "senha_super_secreta",
"settings": {
"max_operations_per_day": 500,
"rate_limit_per_minute": 20
}
}'
{
"status": "sucesso",
"mensagem": "Usuário cadastrado com sucesso",
"data": {
"tenant_id": "290c8f0c-9b41-48ac-9f2a-86f52738662f",
"nome": "Empresa Nova LTDA",
"slug": "empresa-nova-ltda",
"panel_url": "https://painel-novo.exemplo.com/login",
"clients_url": "https://painel-novo.exemplo.com/clients",
"token": "ffbb4c05b474514fea8265209574a30c0ccb5c7f5bf8deb167c6ba6b3872a3bd",
"token_id": "da9f37d8-0880-420c-977a-7890f9e8a4de",
"settings": {
"created_via_api": true,
"notifications_enabled": true,
"rate_limit_per_minute": 20,
"max_operations_per_day": 500
}
},
"timestamp": "2025-06-17 20:45:30"
}
{
"status": "erro",
"mensagem": "Campos obrigatórios: nome, panel_url, panel_username, panel_password",
"timestamp": "2025-06-17 20:45:30"
}
✏️ PUT /admin/users/:slug
Atualizar dados de um usuário existente. URLs são automaticamente reconstruídas quando panel_url é alterada.
📋 Exemplo de Requisição
curl -X PUT http://localhost:3000/admin/users/empresa-nova-ltda \
-H "Content-Type: application/json" \
-H "x-admin-token: admin_token_dev_12345" \
-d '{
"panel_url": "https://novo-painel.exemplo.com/admin",
"panel_password": "nova_senha_segura",
"settings": {
"max_operations_per_day": 750,
"rate_limit_per_minute": 25
}
}'
{
"status": "sucesso",
"mensagem": "Usuário atualizado com sucesso",
"timestamp": "2025-06-17 20:45:30"
}
📋 GET /admin/users
Listar todos os usuários cadastrados no sistema com informações completas, excluindo senhas por segurança.
📋 Exemplo de Requisição
curl -X GET http://localhost:3000/admin/users \ -H "x-admin-token: admin_token_dev_12345"
{
"status": "sucesso",
"data": [
{
"id": "290c8f0c-9b41-48ac-9f2a-86f52738662f",
"name": "Empresa Teste LTDA",
"slug": "empresa-teste-ltda",
"settings": {
"created_via_api": true,
"notifications_enabled": true,
"rate_limit_per_minute": 30,
"max_operations_per_day": 1000
},
"status": "active",
"created_at": "2025-06-17T18:30:00.000Z",
"panel_login_url": "https://painel.exemplo.com/login",
"panel_clients_url": "https://painel.exemplo.com/clients",
"panel_username": "admin_empresa",
"total_tokens": 1
}
],
"total": 1,
"timestamp": "2025-06-17 20:45:30"
}
total_tokens mostra quantos tokens de API estão ativos para cada tenant.
🗑️ DELETE /admin/users/:slug
Remover usuário completamente do sistema. Esta operação é irreversível e remove todos os dados relacionados.
🗑️ Dados Removidos
Informações básicas e configurações
Senhas e dados de autenticação
Todos os tokens ativos e histórico
Histórico completo de operações
📋 Exemplo de Requisição
curl -X DELETE http://localhost:3000/admin/users/empresa-nova-ltda \ -H "x-admin-token: admin_token_dev_12345"
{
"status": "sucesso",
"mensagem": "Usuário removido completamente do sistema",
"dados_removidos": {
"tenant": "Empresa Nova LTDA",
"slug": "empresa-nova-ltda",
"removido_em": "2025-06-17 20:45:30"
},
"timestamp": "2025-06-17 20:45:30"
}
📋 Scripts Utilizados
A API Koffice utiliza scripts especializados para executar as operações de automação. Cada endpoint chama um script específico através do sistema multitenancy.
🧪 teste-multitenant.js
Chamado por: POST /teste
Função: Geração de teste IPTV para usuário final
🔄 Processo de Geração
Autentica com credenciais do tenant
Procura pelos botões de teste IPTV
Clica no botão para gerar teste
Obtém dados do teste gerado
🎯 Seletores Procurados
• button:has-text("TESTE IPTV")
• button:has-text("Teste IPTV")
• button:has-text("TESTE")
• button:has-text("Gerar Teste")
• .btn-teste
• .teste-iptv
🔄 renovar-multitenant.js
Chamado por: POST /renovar
Função: Renovação automática de clientes IPTV
🔄 Processo de Renovação
Autentica com credenciais do tenant
Acessa seção de clientes
Localiza cliente na tabela
Checa vencimento e necessidade
Adiciona meses especificados
Verifica sucesso da operação
• Headless: Execução sem interface gráfica
• Docker: Caminho do Chromium configurado
• Argumentos: Otimizado para containers
• Timeout: Configurável por tenant
❌ Códigos de Erro
📊 Códigos HTTP
| Código | Descrição | Quando Ocorre |
|---|---|---|
| 200 | OK | Operação realizada com sucesso |
| 201 | Created | Recurso criado com sucesso |
| 400 | Bad Request | Parâmetros inválidos ou ausentes |
| 401 | Unauthorized | Token de autenticação inválido |
| 404 | Not Found | Recurso não encontrado |
| 429 | Too Many Requests | Rate limit excedido |
| 500 | Internal Server Error | Erro interno do servidor |
📋 Estruturas de Erro
Erro Padrão
{
"status": "erro",
"mensagem": "Descrição do erro",
"timestamp": "2025-06-17 20:45:30"
}
Erro de Rate Limit
{
"status": "erro",
"mensagem": "Muitas requisições. Tente novamente em 15 minutos.",
"timestamp": "2025-06-17 20:45:30"
}
Erro de Autenticação
{
"status": "erro",
"mensagem": "Token de API inválido",
"timestamp": "2025-06-17 20:45:30"
}
Erro de Validação
{
"status": "erro",
"mensagem": "Parâmetros obrigatórios: cliente, meses",
"tenant": "empresa-teste-ltda",
"timestamp": "2025-06-17 20:45:30"
}
💡 Exemplos Completos
🚀 Fluxo Completo: Criar Usuário e Testar
1️⃣ Criar Usuário
#!/bin/bash
# Criar usuário e capturar token
RESPONSE=$(curl -s -X POST http://localhost:3000/admin/users \
-H "Content-Type: application/json" \
-H "x-admin-token: admin_token_dev_12345" \
-d '{
"nome": "Teste Completo LTDA",
"panel_url": "https://painel-teste.com",
"panel_username": "admin_teste",
"panel_password": "senha123",
"settings": {
"max_operations_per_day": 500,
"rate_limit_per_minute": 20
}
}')
# Extrair token usando Python
TOKEN=$(echo "$RESPONSE" | python3 -c "import sys, json; print(json.load(sys.stdin)['data']['token'])")
echo "🔑 Token gerado: $TOKEN"
2️⃣ Verificar Status do Usuário
curl -X GET http://localhost:3000/stats \ -H "x-api-key: $TOKEN"
3️⃣ Gerar Teste IPTV
curl -X POST http://localhost:3000/teste \ -H "Content-Type: application/json" \ -H "x-api-key: $TOKEN"
4️⃣ Renovar Cliente
curl -X POST http://localhost:3000/renovar \
-H "Content-Type: application/json" \
-H "x-api-key: $TOKEN" \
-d '{
"cliente": "João Silva",
"meses": 6
}'
💻 Integração com JavaScript
class KofficeAPI {
constructor(baseURL, apiKey, adminToken = null) {
this.baseURL = baseURL;
this.apiKey = apiKey;
this.adminToken = adminToken;
}
async request(method, endpoint, data = null, isAdmin = false) {
const headers = {
'Content-Type': 'application/json'
};
if (isAdmin && this.adminToken) {
headers['x-admin-token'] = this.adminToken;
} else if (this.apiKey) {
headers['x-api-key'] = this.apiKey;
}
const config = {
method,
headers,
body: data ? JSON.stringify(data) : null
};
const response = await fetch(`${this.baseURL}${endpoint}`, config);
return await response.json();
}
// Métodos de usuário
async renovarCliente(cliente, meses) {
return await this.request('POST', '/renovar', { cliente, meses });
}
async gerarTeste() {
return await this.request('POST', '/teste');
}
async verificarStatus() {
return await this.request('GET', '/stats');
}
// Métodos administrativos
async criarUsuario(dados) {
return await this.request('POST', '/admin/users', dados, true);
}
async atualizarUsuario(slug, dados) {
return await this.request('PUT', `/admin/users/${slug}`, dados, true);
}
async listarUsuarios() {
return await this.request('GET', '/admin/users', null, true);
}
async removerUsuario(slug) {
return await this.request('DELETE', `/admin/users/${slug}`, null, true);
}
}
// Exemplo de uso
const api = new KofficeAPI(
'http://localhost:3000',
'ffbb4c05b474514fea8265209574a30c0ccb5c7f5bf8deb167c6ba6b3872a3bd',
'admin_token_dev_12345'
);
// Usar a API
(async () => {
try {
// Criar usuário
const novoUsuario = await api.criarUsuario({
nome: 'Nova Empresa LTDA',
panel_url: 'https://painel.empresa.com',
panel_username: 'admin',
panel_password: 'senha123'
});
console.log('✅ Usuário criado:', novoUsuario);
// Gerar teste
const teste = await api.gerarTeste();
console.log('🧪 Teste gerado:', teste);
// Renovar cliente
const renovacao = await api.renovarCliente('João Silva', 3);
console.log('🔄 Renovação:', renovacao);
} catch (error) {
console.error('❌ Erro:', error);
}
})();
• Use o fluxo completo para testar novas integrações
• Implemente tratamento de erro robusto em produção
• Monitore rate limits para evitar bloqueios
• Mantenha logs detalhados para troubleshooting
🔧 Troubleshooting
❗ Problemas Comuns
🔐 Erro 401 - Token Inválido
Token de API inválido
Soluções:
- Verifique se o token está correto e não contém espaços extras
- Confirme se o token não expirou ou foi revogado
- Use o header correto:
x-api-keypara usuários,x-admin-tokenpara admin
⚡ Erro 429 - Rate Limit
Muitas requisições
Soluções:
- Aguarde o período de reset (verifique header
X-RateLimit-Reset) - Implemente backoff exponencial na sua aplicação
- Monitore headers de rate limit em cada resposta
- Distribua operações ao longo do tempo
🔌 Erro 500 - Conectividade Painel
Falha na conectividade com o painel
Soluções:
- Verificar se a URL do painel está correta e acessível
- Validar credenciais de login do painel
- Testar conectividade de rede entre API e painel
- Verificar se o painel não está em manutenção
⏱️ Timeout em Operações
Operações demoram muito
Soluções:
- Verificar performance do painel IPTV
- Aguardar entre requisições consecutivas
- Monitorar logs do sistema para identificar gargalos
- Considerar horários de menor uso do painel
📊 Monitoramento e Logs
🐳 Verificar Logs do Container
# Logs em tempo real docker logs koffice_api_dev --tail 50 --follow # Logs com timestamp docker logs koffice_api_dev --timestamps # Filtrar por erro docker logs koffice_api_dev 2>&1 | grep -i error
🏥 Health Check do Sistema
# Status básico curl http://localhost:3000/status # Verificação completa curl http://localhost:3000/health # Status do tenant curl -H "x-api-key: SEU_TOKEN" http://localhost:3000/stats
📈 Monitorar Rate Limits
#!/bin/bash # Fazer requisição e capturar headers RESPONSE=$(curl -s -I -H "x-api-key: SEU_TOKEN" http://localhost:3000/stats) # Extrair informações de rate limit echo "$RESPONSE" | grep -i "x-ratelimit" # Exemplo de saída: # X-RateLimit-Limit: 30 # X-RateLimit-Remaining: 25 # X-RateLimit-Reset: 1640995200
🛠️ Dicas de Desenvolvimento
Use logs detalhados para identificar problemas específicos
Implemente timeouts adequados nas suas requisições
Use retry com backoff para operações críticas
Monitore métricas de sucesso e falha continuamente
/health e /stats para detectar problemas antes que afetem os usuários finais.
📦 Versão 2.0.0-multitenancy
🌐 Sistema: Multitenancy com isolamento completo
🔧 Scripts: Automatização para painel Koffice sem recaptcha
🔗 Integração: Pronto para n8n, PHP, Python e qualquer cliente HTTP
Desenvolvido pela equipe Koffice System