API pública do Ravi Monitor

Visão geral

A API pública permite que sistemas externos do provedor (ERP, CRM, scripts de automação, painéis próprios, sistemas de provisionamento) consultem e operem o Ravi Monitor sem abrir a interface web. Casos de uso típicos:

• Provisionar e excluir ONTs na OLT a partir do sistema de gestão do provedor.
• Consultar status de grupos, dispositivos e sensores monitorados, e também criar, editar e excluir esses itens por API. Novo na 7.2
• Consultar sessões PPPoE das concentradoras: usuário online, histórico e tráfego.
• Gerenciar domínios e registros do DNS autoritativo.
• Enviar mensagens de WhatsApp pelo número pareado no Ravi.
• Acompanhar e gerenciar o ambiente Flow (anti-DDoS) por integração externa: tráfego ao vivo, eventos, mitigação, whitelist e mais. Novo na 7.2

Toda a API funciona sobre um endpoint único, com autenticação por chaves de API criadas na própria interface. Cada chave tem permissões independentes por área do sistema: OLT, Dispositivos, Concentradoras, DNS, WhatsApp e Flow.

Como as chamadas se organizam

Toda requisição informa dois parâmetros de roteamento, além do token:

Resumo das áreas disponíveis (cada uma tem sua página nesta documentação):

API atual e webservice legado

Instalações antigas podem ter integrações apontando para o webservice legado (/webservice/*.php), que autentica com usuário e senha de um login web passados na URL. Esse mecanismo é mantido apenas por compatibilidade. Toda integração nova deve usar a API descrita aqui, em /api/api.php, com chave de API e permissões por área.

Criar uma chave de API Somente Master

A chave de API é uma string aleatória de 32 caracteres alfanuméricos, gerada automaticamente pelo sistema e armazenada criptografada. Ela é a única credencial da API: não há usuário, senha nem sessão. Criar, alterar e excluir chaves exige estar logado com a conta Master.

Passo a passo

1. No menu superior, clique no ícone de engrenagem para abrir Configurações.
2. Abra a aba Integrações e localize o card Gerenciamento de API.
3. Clique em Nova Chave API. Se ainda não existir nenhuma chave, o card mostra o estado vazio Nenhuma chave API configurada com o mesmo botão.
4. Na modal Gerenciamento de Chave API, o campo Chave API já vem preenchido com a chave gerada. Clique em Copiar e guarde a chave em um local seguro agora.
5. Preencha Descrição (opcional) com o nome da integração (por exemplo, "Integração ERP" ou "Painel NOC"). Depois que a chave for mascarada, a descrição é a única forma de identificá-la.
6. Em Permissões de Acesso, marque as áreas que a integração vai usar. É obrigatório marcar pelo menos uma; caso contrário o formulário exibe o aviso "Por favor, selecione pelo menos uma permissão de acesso." e não envia.
7. Clique em Criar Chave API. A tela volta para a aba Integrações com a mensagem API criada com sucesso, e a chave aparece na lista do card com um cronômetro regressivo de 2 horas.

Permissões por área

As seis caixas de permissão aparecem nesta ordem na modal:

Aplique o princípio do menor privilégio: marque apenas as áreas que a integração realmente usa. A linha Selecionar todas é útil só para testes.

Janela de cópia de 2 horas

A chave fica visível e copiável por até 2 horas após a criação. Passado esse prazo, ela aparece mascarada na lista (apenas os 4 últimos caracteres) e o botão de copiar é desabilitado. Importante: a chave continua válida para sempre; o que expira é somente a visualização. Se você não copiou a chave a tempo, não existe forma de recuperá-la: exclua e crie outra.

Alterar uma chave

Na lista do card, cada chave tem os botões Alterar e Excluir. O botão Alterar reabre a modal com o título Alterar Chave API, onde é possível mudar a descrição e as permissões, confirmando em Atualizar Chave API.

Excluir (revogar) uma chave

1. Na lista do card Gerenciamento de API, clique em Excluir na linha da chave.
2. Confirme no diálogo Excluir API ("Tem certeza que deseja excluir esta chave API?").
3. A chave é removida na hora, com a mensagem API excluída com sucesso!. A revogação é imediata: a próxima chamada com essa chave recebe HTTP 401 Invalid token.

Autenticação

Todas as chamadas vão para um único endpoint no seu servidor Ravi:

https://<SEU-SERVIDOR-RAVI>/api/api.php

A autenticação é feita exclusivamente pelo parâmetro token, enviado junto com os demais parâmetros da chamada. Não é um header HTTP: mesmo que o cliente envie Authorization, ele não é lido. Os métodos aceitos são GET e POST (form-urlencoded), e todos os parâmetros funcionam nos dois. Evite enviar o mesmo parâmetro por GET e POST na mesma chamada: a precedência varia conforme a área.

Parâmetros obrigatórios em toda chamada:

Não há sessão, cookie nem login: cada chamada é independente e autossuficiente. Também não há usuário associado à chave; a chave dá acesso direto às áreas liberadas.

Primeira chamada: exemplo mínimo completo

O exemplo abaixo lista os grupos de dispositivos (requer a permissão Acesso a Dispositivos na chave). Troque a URL e o token pelos seus.

# POST com form-urlencoded (recomendado em produção)
curl -s -X POST "https://ravi.seuprovedor.com.br/api/api.php" \
  -d "token=aB3xK9mP2qR7sT1vW5yZ8cD4fG6hJ0kL" \
  -d "action=dispositivo" \
  -d "operation=list_groups"

<?php
$url = 'https://ravi.seuprovedor.com.br/api/api.php';
$dados = [
    'token'     => 'aB3xK9mP2qR7sT1vW5yZ8cD4fG6hJ0kL',
    'action'    => 'dispositivo',
    'operation' => 'list_groups',
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($dados));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$corpo  = curl_exec($ch);
$codigo = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$resposta = json_decode($corpo, true);

// Trate como erro: HTTP >= 400 OU corpo com "msg" / "status":"error" / "success":false
if ($codigo >= 400 || isset($resposta['msg']) || ($resposta['status'] ?? '') === 'error' || ($resposta['success'] ?? true) === false) {
    die('Erro na API: ' . $corpo);
}

print_r($resposta['groups']);

import requests

URL   = "https://ravi.seuprovedor.com.br/api/api.php"
TOKEN = "aB3xK9mP2qR7sT1vW5yZ8cD4fG6hJ0kL"

r = requests.post(URL, data={
    "token": TOKEN,
    "action": "dispositivo",
    "operation": "list_groups",
}, timeout=30)

corpo = r.json()

# Trate como erro: HTTP >= 400 OU corpo com "msg" / "status":"error" / "success":false
if r.status_code >= 400 or "msg" in corpo or corpo.get("status") == "error" or corpo.get("success") is False:
    raise RuntimeError(f"Erro na API: {r.text}")

print(corpo["groups"])

Resposta esperada (a permissão está correta e existem grupos cadastrados):

{"groups":[{"id":1,"name":"Backbone","parent_id":0}, ...]}

O mesmo padrão vale para qualquer área. Por exemplo, um resumo do ambiente Flow (permissão Acesso a Flow):

curl -s -X POST "https://ravi.seuprovedor.com.br/api/api.php" \
  -d "token=aB3xK9mP2qR7sT1vW5yZ8cD4fG6hJ0kL" \
  -d "action=flow" \
  -d "operation=overview"
# → {"status":"success","data":{"collector_online":true,"flows_per_sec":..., "events_active":0, ...}}

Ordem de validação do gateway

Toda chamada passa pelas validações abaixo, nesta ordem, antes de chegar à área pedida:

1. token ausente: HTTP 400 com {"status":"error","message":"Token not provided"}.
2. action ausente: HTTP 400 com {"status":"error","message":"Action not provided"}.
3. Token não corresponde a nenhuma chave cadastrada: HTTP 401 com Invalid token.
4. Chave válida mas sem a permissão da área: HTTP 403 com Access denied for <area> (por exemplo, Access denied for flow).
5. action fora da lista de áreas: HTTP 400 com Invalid action.
6. Tudo certo: a área valida a operation e seus parâmetros próprios e responde.

Teste de conectividade

Antes de integrar uma área específica, você pode validar de uma vez o endereço do servidor e a validade do token com a ação ping (a ação status é um apelido equivalente). Ela não exige operation nem permissão de área: basta um token válido.

curl -s "https://ravi.seuprovedor.com.br/api/api.php?action=ping&token=SEU_TOKEN"

{"status":"success","data":{"status":"online","versao":"2.0","servidor":"Ravi Monitor"}}

Uma resposta com "status":"success" confirma que o servidor está no ar e que o token é válido. Token ausente ou inválido cai nas mesmas respostas de erro do gateway (Token not provided, Invalid token). Use o ping como primeiro passo de qualquer integração e como monitor de saúde da API.

Formato das respostas

Toda resposta vem com Content-Type: application/json; charset=utf-8. Erros internos do servidor nunca vazam para o corpo da resposta; eles vão para o log do servidor, preservando o JSON.

Os erros do gateway (token, permissão, área) sempre usam o envelope {"status":"error","message":"..."}. Já o corpo de sucesso varia conforme a área, por herança de gerações diferentes da API. A página de cada área mostra o formato real; o resumo é este:

Mensagens de erro comuns

As mensagens de erro do gateway vêm em inglês no corpo da resposta:

Limites e boas práticas

O que você precisa saber sobre limites da API:

• Controle de carga: dimensione a integração com moderação: evite paralelismo alto e polling agressivo, e aplique backoff em caso de erro. Consultas ao vivo acompanham bem intervalos de 5 a 10 segundos.
• Evite polling agressivo: para dados "ao vivo" do Flow, intervalos de 5 a 10 segundos já acompanham a atualização do coletor; faça backoff em caso de erro.
• Configure o timeout do cliente com folga: algumas operações demoram porque conversam com equipamentos reais. As operações de OLT, por exemplo, abrem sessão SSH ou Telnet com o equipamento antes de responder. Use 60 segundos ou mais para operações de OLT (30 segundos atendem as consultas comuns) e trate o estouro de tempo na integração em vez de repetir a chamada às cegas.
• Sem expiração de chave: a chave vale até ser excluída. A janela de 2 horas se aplica apenas à visualização e cópia na tela.
• Sem limite de quantidade de chaves: crie quantas precisar. Ainda assim, mantenha poucas chaves e apague as sem uso: cada chamada valida o token contra todas as chaves cadastradas, e menos chaves também facilitam a auditoria.
• Recursos dependem do servidor: a API não substitui a configuração dos recursos na tela. Por exemplo, action=flow pressupõe o ambiente Flow configurado e rodando (que depende de plano elegível), e action=whatsapp pressupõe o WhatsApp pareado. Se o Flow responde com collector_online:false ou dados vazios, o ambiente não está ativo naquele servidor.

Checklist de segurança

• Uma chave por integração, com Descrição (opcional) sempre preenchida: é o único jeito de identificar a chave depois que ela é mascarada.
• Menor privilégio: marque só as áreas que a integração usa. Selecionar todas apenas para testes.
• Copie a chave e guarde em um cofre de senhas no momento da criação (janela de 2 horas).
• Use HTTPS e POST; nunca embuta a chave em uma página web pública.
• Revogue (botão Excluir) as chaves de integrações desativadas; a revogação vale já na chamada seguinte.
• Rotacione as chaves periodicamente. Como a chave não expira, a rotação é manual: crie uma chave nova, atualize o token na integração e exclua a antiga.
• Não use Alterar em chaves com mais de 2 horas (nem para a rotação); exclua e recrie.

Problemas frequentes