API de Concentradoras PPPoE

A API de Concentradoras permite gerenciar e monitorar concentradoras PPPoE (Point-to-Point Protocol over Ethernet) e seus usuários conectados no sistema Ravi Monitor.

Endpoint Base

GET /api.php?action=concentradora&token={seu_token}&operation={operacao}

Autenticação

Todas as requisições requerem um token de API válido:

GET /api.php?action=concentradora&token=seu_token_aqui&operation=list

Operações Disponíveis

1. Listar Concentradoras (list)

Lista todas as concentradoras ativas no sistema com informações resumidas.

Endpoint:

GET /api.php?action=concentradora&token={token}&operation=list

Exemplo de requisição:

curl "https://seu-servidor.com/api.php?action=concentradora&token=seu_token&operation=list"

Resposta de sucesso:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "nome": "PPPoE-Principal",
      "ip": "192.168.1.1",
      "marca": "MikroTik",
      "tipo": "RouterOS",
      "status": 2,
      "status_descricao": "Normal",
      "ultima_sincronizacao": "2025-01-20 14:30:00",
      "tempo_sincronizacao": "0.523",
      "alerta_pppoe_ativo": true,
      "ping_ativo": true,
      "dias_offline": 3,
      "cron_ativo": true,
      "dados_historicos_ativo": true,
      "alerta_linkdown_ativo": true,
      "usuarios_online": 245,
      "total_usuarios": 350
    }
  ]
}

Status possíveis:

1: Crítico
2: Normal
3: Aviso
4: Manutenção
5: Desconhecido
6: OK

2. Obter Concentradora (get)

Retorna informações detalhadas de uma concentradora específica.

Endpoint:

GET /api.php?action=concentradora&token={token}&operation=get&id={id}

Parâmetros obrigatórios:

id (int): ID da concentradora

Exemplo de requisição:

curl "https://seu-servidor.com/api.php?action=concentradora&token=seu_token&operation=get&id=1"

Resposta de sucesso:

{
  "success": true,
  "data": {
    "id": 1,
    "nome": "PPPoE-Principal",
    "ip": "192.168.1.1",
    "marca": "MikroTik",
    "tipo": "RouterOS",
    "status": 2,
    "status_descricao": "Normal",
    "ativo": true,
    "herdar_pai": 0,
    "snmp": "community_string",
    "versao_snmp": "2c",
    "porta_snmp": 161,
    "alerta_pppoe_ativo": true,
    "cron_ativo": true,
    "dias_offline": 3,
    "dados_historicos_ativo": true,
    "ping_ativo": true,
    "alerta_linkdown_ativo": true,
    "tamanho_pacotes": 56,
    "quantidade_pacotes": 4,
    "historico_trafego_ativo": true,
    "ultima_sincronizacao": "2025-01-20 14:30:00",
    "tempo_sincronizacao": "0.523",
    "usuarios_online": 245,
    "total_usuarios": 350
  }
}

Resposta de erro (404):

{
  "success": false,
  "error": "Concentradora não encontrada"
}

3. Listar Usuários PPPoE (get_users)

Lista os usuários PPPoE conectados ou desconectados de uma concentradora.

Endpoint:

GET /api.php?action=concentradora&token={token}&operation=get_users&id={id}

Parâmetros obrigatórios:

id (int): ID da concentradora

Parâmetros opcionais:

status (string): Filtro de status - all, online, offline (padrão: all)

Exemplo de requisição:

# Listar apenas usuários online
curl "https://seu-servidor.com/api.php?action=concentradora&token=seu_token&operation=get_users&id=1&status=online"

Resposta de sucesso:

{
  "success": true,
  "data": [
    {
      "username": "usuario@provedor",
      "ip": "100.64.0.1",
      "vlan": "100",
      "status": "online",
      "data_desconexao": null,
      "download_bytes": 1500000000,
      "upload_bytes": 450000000,
      "ping_ms": "15.2",
      "jitter_ms": "2.1",
      "packet_loss": "0.5"
    },
    {
      "username": "usuario2@provedor",
      "ip": "100.64.0.2",
      "vlan": "100",
      "status": "offline",
      "data_desconexao": "2025-01-20 07:45:00",
      "download_bytes": 2300000000,
      "upload_bytes": 680000000,
      "ping_ms": null,
      "jitter_ms": null,
      "packet_loss": null
    }
  ]
}

4. Obter Detalhes do Usuário (get_user_details)

Retorna informações detalhadas de um usuário PPPoE específico.

Endpoint:

GET /api.php?action=concentradora&token={token}&operation=get_user_details&username={username}&concentradora_id={id}

Parâmetros obrigatórios:

username (string): Nome do usuário PPPoE
concentradora_id (int): ID da concentradora

Exemplo de requisição:

curl "https://seu-servidor.com/api.php?action=concentradora&token=seu_token&operation=get_user_details&username=usuario@provedor&concentradora_id=1"

Resposta de sucesso:

{
  "success": true,
  "data": {
    "concentradora_id": 1,
    "concentradora_nome": "PPPoE-Principal",
    "username": "usuario@provedor",
    "interface": "pppoe-out1",
    "mac": "AA:BB:CC:DD:EE:FF",
    "ip": "100.64.0.1",
    "vlan": "100",
    "status": "online",
    "data_conexao": "2025-01-20 08:15:00",
    "data_desconexao": null,
    "uptime_conexao": "6h 15m",
    "download_bytes": 1500000000,
    "upload_bytes": 450000000,
    "ping_ms": "15.2",
    "jitter_ms": null,
    "linkdown_count": 0,
    "ultima_sincronizacao": "2025-01-20 14:30:00",
    "historico_ping": []
  }
}

Resposta de erro (404):

{
  "success": false,
  "error": "Usuário não encontrado"
}

5. Obter Histórico de Conexões (get_user_history)

Retorna o histórico de conexões/desconexões de um usuário PPPoE.

Endpoint:

GET /api.php?action=concentradora&token={token}&operation=get_user_history&username={username}&concentradora_id={id}

Parâmetros obrigatórios:

username (string): Nome do usuário PPPoE
concentradora_id (int): ID da concentradora

Exemplo de requisição:

curl "https://seu-servidor.com/api.php?action=concentradora&token=seu_token&operation=get_user_history&username=usuario@provedor&concentradora_id=1"

Resposta de sucesso:

{
  "success": true,
  "data": [
    {
      "data_conexao": "2025-01-20 08:15:00",
      "data_desconexao": "2025-01-20 14:30:00",
      "duracao": "0 dias, 06:15:00",
      "duracao_segundos": 22500,
      "ip": "100.64.0.1",
      "vlan": "100",
      "download_bytes": 1500000000,
      "upload_bytes": 450000000
    },
    {
      "data_conexao": "2025-01-19 22:00:00",
      "data_desconexao": "2025-01-20 07:45:00",
      "duracao": "0 dias, 09:45:00",
      "duracao_segundos": 35100,
      "ip": "100.64.0.1",
      "vlan": "100",
      "download_bytes": 2300000000,
      "upload_bytes": 680000000
    }
  ]
}

6. Obter Histórico de Tráfego (get_user_traffic)

OBSERVAÇÃO: Dados de tráfego granular não estão disponíveis nesta API. Use get_user_history para obter dados de tráfego total por sessão.

Endpoint:

GET /api.php?action=concentradora&token={token}&operation=get_user_traffic&username={username}&concentradora_id={id}

Parâmetros obrigatórios:

username (string): Nome do usuário PPPoE
concentradora_id (int): ID da concentradora

Exemplo de requisição:

curl "https://seu-servidor.com/api.php?action=concentradora&token=seu_token&operation=get_user_traffic&username=usuario@provedor&concentradora_id=1"

Resposta:

{
  "success": true,
  "data": [],
  "message": "Dados de tráfego granular não disponíveis. Use get_user_history para obter tráfego por sessão."
}

Observações:

Esta operação retorna array vazio pois dados históricos granulares não estão disponíveis
Para dados de tráfego, use a operação get_user_history que retorna download_bytes e upload_bytes por sessão
Os valores de tráfego são retornados em bytes
Para converter para MB: bytes / 1024 / 1024
Para converter para GB: bytes / 1024 / 1024 / 1024

7. Buscar Concentradoras (search)

Busca concentradoras por nome ou endereço IP.

Endpoint:

GET /api.php?action=concentradora&token={token}&operation=search&query={termo}

Parâmetros obrigatórios:

query (string): Termo de busca (nome ou IP)

Exemplo de requisição:

curl "https://seu-servidor.com/api.php?action=concentradora&token=seu_token&operation=search&query=mikrotik"

Resposta de sucesso:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "nome": "PPPoE-MikroTik-Principal",
      "ip": "192.168.1.1",
      "marca": "MikroTik",
      "tipo": "RouterOS",
      "status": 2,
      "status_descricao": "Normal",
      "ultima_sincronizacao": "2025-01-20 14:30:00",
      "tempo_sincronizacao": "0.523",
      "usuarios_online": 245
    }
  ]
}

8. Estatísticas Gerais (statistics)

Retorna estatísticas gerais sobre concentradoras e usuários PPPoE.

Endpoint:

GET /api.php?action=concentradora&token={token}&operation=statistics

Exemplo de requisição:

curl "https://seu-servidor.com/api.php?action=concentradora&token=seu_token&operation=statistics"

Resposta de sucesso:

{
  "success": true,
  "data": {
    "total_concentradoras": 5,
    "concentradoras_por_status": [
      {
        "status": 2,
        "status_descricao": "Normal",
        "total": 4
      },
      {
        "status": 3,
        "status_descricao": "Aviso",
        "total": 1
      }
    ],
    "total_usuarios_pppoe": 1250,
    "usuarios_online": 847,
    "usuarios_offline": 403,
    "top_concentradoras": [
      {
        "id": 1,
        "nome": "PPPoE-Principal",
        "ip": "192.168.1.1",
        "usuarios_online": 245
      },
      {
        "id": 2,
        "nome": "PPPoE-Secundario",
        "ip": "192.168.1.2",
        "usuarios_online": 198
      }
    ]
  }
}

Códigos de Resposta HTTP

200 OK: Requisição bem-sucedida
400 Bad Request: Parâmetros inválidos ou ausentes
403 Forbidden: Token inválido ou sem permissão
404 Not Found: Recurso não encontrado
500 Internal Server Error: Erro no servidor

Tratamento de Erros

Todas as respostas de erro seguem o padrão:

{
  "success": false,
  "error": "Descrição do erro"
}

Exemplos de Uso

PHP

<?php
$token = 'seu_token_aqui';
$baseUrl = 'https://seu-servidor.com/api.php';

// Listar concentradoras
$url = $baseUrl . '?action=concentradora&token=' . $token . '&operation=list';
$response = file_get_contents($url);
$data = json_decode($response, true);

if ($data['success']) {
    foreach ($data['data'] as $concentradora) {
        echo "Concentradora: " . $concentradora['nome'] . "\n";
        echo "Usuários online: " . $concentradora['usuarios_online'] . "\n\n";
    }
}
?>

Python

import requests

token = 'seu_token_aqui'
base_url = 'https://seu-servidor.com/api.php'

# Obter usuários online de uma concentradora
params = {
    'tipo': 'concentradora',
    'token': token,
    'operation': 'get_users',
    'id': 1,
    'status': 'online'
}

response = requests.get(base_url, params=params)
data = response.json()

if data['success']:
    for user in data['data']:
        print(f"Usuário: {user['username']}")
        print(f"IP: {user['ip']}")
        print(f"Status: {user['status']}")
        print(f"Ping: {user['ping_ms']}ms\n")

JavaScript (Node.js)

const axios = require('axios');

const token = 'seu_token_aqui';
const baseUrl = 'https://seu-servidor.com/api.php';

// Obter estatísticas
async function getStatistics() {
    try {
        const response = await axios.get(baseUrl, {
            params: {
                tipo: 'concentradora',
                token: token,
                operation: 'statistics'
            }
        });

        if (response.data.success) {
            console.log('Total de concentradoras:', response.data.data.total_concentradoras);
            console.log('Usuários online:', response.data.data.usuarios_online);
            console.log('Usuários offline:', response.data.data.usuarios_offline);
        }
    } catch (error) {
        console.error('Erro:', error.message);
    }
}

getStatistics();

Notas Importantes

Performance: Para concentradoras com muitos usuários, use paginação para evitar timeouts
Cache: Considere implementar cache local para dados que não mudam frequentemente
Rate Limiting: Evite fazer requisições excessivas em curto período de tempo
Segurança: Nunca exponha seu token de API em código client-side ou repositórios públicos
Bytes vs. Bits: Os valores de tráfego são retornados em bytes. Para converter para Mbps, considere o intervalo de coleta

Suporte

Para mais informações ou reportar problemas, consulte a documentação principal da API ou entre em contato com o suporte técnico.