API de Dispositivos

Lista os alertas registrados, do mais recente para o mais antigo, com o dispositivo e o sensor de origem, os canais de notificação disparados e a duração de cada ocorrência.

curl -s "https://ravi.exemplo.com/api/api.php?token=CHAVE&action=dispositivo&operation=alerts&only_active=true&limit=50"

{"alerts":[{"id":9012,"date":"2026-07-04 09:15:00","sensor_id":8623,"sensor_name":"Tráfego sfp-sfpplus1",
  "device_id":5,"device_name":"RB Borda","device_ip":"10.0.0.1","type":3,"type_text":"Alerta","tag":"ifMikrotik",
  "messages":["Tráfego acima do limite"],
  "notifications":{"telegram":1,"email":1,"whatsapp":0,"push":0},
  "resolved":false,"resolved_date":null,
  "duration":{"days":0,"hours":1,"minutes":23,"seconds":11,"total_seconds":4991,"formatted":"01:23:11"}}],
 "total":1,"active_count":1}

O campo type usa estes códigos, com o rótulo correspondente em type_text; qualquer outro valor volta com type_text Desconhecido:

• resolved indica se o alerta já foi resolvido; nesse caso resolved_date traz a data e duration é o tempo total. Para alertas ativos, a duração é contada até o momento da consulta.
• duration.formatted vem como HH:MM:SS, prefixado pela contagem de dias quando houver: por exemplo "06:35:20" para menos de um dia e "2d 05:30:45" a partir de um dia.
• Os quatro campos de notifications (telegram, email, whatsapp, push) são números, não booleanos: 0 = não enviado, 1 = enviado quando o problema surgiu, 2 = enviado na resolução do problema, 3 = falha no envio.
• total é quantos alertas vieram na resposta; active_count, quantos deles seguem ativos.

Busca por texto em toda a árvore de monitoramento e devolve os grupos, dispositivos e sensores que casam com o termo. Útil para uma barra de busca em um painel externo. O termo é comparado por trecho (contém), sem diferenciar maiúsculas: grupos pelo nome, dispositivos pelo nome ou pelo IP e sensores pelo nome ou pela tag.

curl -s "https://ravi.exemplo.com/api/api.php?token=CHAVE&action=dispositivo&operation=search&query=borda&type=all"

{"results":{
  "groups":[{"id":12,"name":"POP Centro","parent_id":0}],
  "devices":[{"id":5,"name":"RB Borda","ip":"10.0.0.1","group_id":12,"equipment":"Mikrotik"}],
  "sensors":[{"id":8623,"name":"Tráfego sfp-sfpplus1","device_id":5,"device_name":"RB Borda",
              "status":6,"status_text":"OK","tag":"ifMikrotik"}]}}

Com type diferente de all, apenas a lista correspondente é preenchida; as demais vêm vazias. Cada lista devolve no máximo 50 resultados por tipo: se alguma vier com 50 itens, refine o termo de busca. Nos dispositivos, equipment vem como o nome da marca (diferente do list_devices, que devolve o código numérico). Erro: Search query must be at least 2 characters.

Lista os grupos de um nível da árvore. Não é recursivo: devolve apenas o nível pedido, na ordem em que aparecem na tela.

curl -s "https://ravi.exemplo.com/api/api.php?token=CHAVE&action=dispositivo&operation=list_groups&parent_id=0"

{"groups":[{"id":12,"name":"POP Centro","parent_id":0},{"id":15,"name":"Backbone","parent_id":0}]}

Devolve um grupo com sua subárvore completa e um resumo de status. Diferente do list_groups (que traz só um nível), esta operação desce recursivamente pelos subgrupos e, por padrão, inclui os dispositivos e os sensores de cada nível.

curl -s "https://ravi.exemplo.com/api/api.php?token=CHAVE&action=dispositivo&operation=get_group&group_id=12"

{"group":{"id":12,"name":"POP Centro","parent_id":0,
  "subgroups":[{"id":18,"name":"Sala técnica","parent_id":12,"subgroups":[],"devices":[],"stats":{}}],
  "devices":[{"id":5,"name":"RB Borda","ip":"10.0.0.1","group_id":12,"equipment":"Mikrotik",
    "sensors":[{"id":301,"name":"Carga de CPU","device_id":5,"status":6,"status_text":"OK",
                "value":"12%","tag":"cpuMikrotik","unit":"%","schedule":"1m"}],
    "status":{"total_sensors":1,"sensors_ok":1,"sensors_alert":0,"sensors_error":0,
              "sensors_offline":0,"sensors_paused":0,"overall":"ok"}}],
  "stats":{"total_devices":8,"total_sensors":64,"sensors_ok":60,"sensors_alert":1,
           "sensors_error":0,"sensors_offline":2,"sensors_paused":1}}}

• Cada nó de subgroups repete a mesma estrutura (subgroups, devices, stats), de forma recursiva.
• Nos dispositivos, equipment vem como o nome da marca (por exemplo "Mikrotik", "Outro"). Já list_devices e get_device devolvem o código numérico da marca (tabela do add_device).
• Cada sensor traz id, name, device_id, status, status_text, value (formatado), tag, unit e schedule. Os campos unit e schedule aparecem só aqui: o list_sensors não devolve esses dois.
• Cada dispositivo traz também um bloco status que resume o equipamento (campos na tabela abaixo).
• O bloco stats conta os sensores da subárvore por estado (sensors_ok, sensors_alert, sensors_error, sensors_offline, sensors_paused), útil para um resumo por POP.

Bloco status de cada dispositivo

Erros: Group ID is required, Group not found.

Cria um grupo. O grupo novo entra no fim da ordem do nível. Nome duplicado no mesmo nível é bloqueado (em níveis diferentes pode repetir).

curl -s -d "token=CHAVE&action=dispositivo&operation=add_group&name=POP Norte" https://ravi.exemplo.com/api/api.php

{"msg":"ok","group_id":77}

Erros: Group name is required, Group already exists at this level.

Edita um grupo existente com semântica PATCH: só altera o que for enviado; campos omitidos ficam como estão.

curl -s -d "token=CHAVE&action=dispositivo&operation=edit_group&group_id=77&name=POP Norte 2&ativasnmp=2&snmp_version=2&snmp_community=publica&snmp_port=161" https://ravi.exemplo.com/api/api.php

{"status":"success","group":{"id":77,"nome":"POP Norte 2","idGrupoPai":0}}

Erros: group_id is required, Group not found.

Exclui um grupo. Só funciona em grupo vazio: sem subgrupos e sem dispositivos. Esvazie antes, movendo o conteúdo com edit_device e edit_group.

curl -s -d "token=CHAVE&action=dispositivo&operation=delete_group&group_id=77" https://ravi.exemplo.com/api/api.php

{"msg":"ok"}

Erros: Group ID is required, Group not found, Cannot delete group with subgroups, Cannot delete group with devices.

Lista os dispositivos de um grupo. Não é recursivo.

curl -s "https://ravi.exemplo.com/api/api.php?token=CHAVE&action=dispositivo&operation=list_devices&group_id=12"

{"devices":[{"id":5,"name":"RB Borda","ip":"10.0.0.1","group_id":12,"equipment":2}]}

Devolve um dispositivo com todos os seus sensores (mesmo formato de sensor do list_sensors).

curl -s "https://ravi.exemplo.com/api/api.php?token=CHAVE&action=dispositivo&operation=get_device&device_id=5"

{"device":{"id":5,"name":"RB Borda","ip":"10.0.0.1","group_id":12,"equipment":2,
  "sensors":[{"id":301,"name":"Carga de CPU","device_id":5,"status":6,"status_text":"OK","value":"12%","tag":"cpuMikrotik"}]}}

Erros: Device ID is required, Device not found.

Contadores de status para painéis externos: total de dispositivos, total de sensores e sensores por estado.

curl -s "https://ravi.exemplo.com/api/api.php?token=CHAVE&action=dispositivo&operation=status_summary"

{"total_devices":42,"total_sensors":310,
 "status_counts":{"offline":2,"paused":5,"alert":1,"critical":0,"untested":3,"ok":299}}

Observação: os sub-estados internos (7 a 14 e 20) não entram nos 6 contadores, então a soma pode ficar ligeiramente abaixo de total_sensors em cenários com falha SNMP.

Devolve a árvore completa em uma única chamada: grupos com dispositivos e sensores, dispositivos da raiz e ainda as listas de OLTs, concentradoras, DNS e exportadores de Flow ativos. É a operação usada pelo Ambiente Dashboards para fontes remotas. Não recebe parâmetros.

curl -s "https://ravi.exemplo.com/api/api.php?token=CHAVE&action=dispositivo&operation=topology"

{"topology":{
  "groups":[{"id":12,"name":"POP Centro","parent_id":0,
    "devices":[{"id":5,"name":"RB Borda","group_id":12,
      "sensors":[{"id":301,"name":"Carga de CPU","status":6}]}]}],
  "devices":[],
  "olts":[{"id":1,"name":"OLT Central","ip":"10.0.0.9","status":1}],
  "concentradoras":[{"id":1,"name":"BNG-01","ip":"10.0.0.8","status":1}],
  "dns":[{"id":1,"name":"DNS Recursivo","primario":"10.0.0.53","secundario":"10.0.0.54"}],
  "flow":[{"id":0,"name":"Visão geral","ip":""},{"id":3,"name":"NE8000","ip":"10.0.0.7"}]
}}

• Os grupos vêm achatados, todos com parent_id; o cliente monta a hierarquia.
• O status dos sensores já vem colapsado nos códigos 1 a 6.
• Só aparecem OLTs e concentradoras ativas e exportadores de Flow ativos. O item de Flow com id=0 é sintético e representa a visão geral de todos os exportadores.
• Em bases grandes a resposta é volumosa: faça cache no cliente em vez de chamar em loop curto.

Cria um dispositivo. Ele nasce sem sensores: crie-os em seguida com add_sensor ou ligue o auto-sensor do dispositivo ou do grupo.

curl -s -d "token=CHAVE&action=dispositivo&operation=add_device&name=RB Borda&ip=10.0.0.1&group_id=77&equipment=2" https://ravi.exemplo.com/api/api.php

{"msg":"ok","device_id":123}

Erros: Device name and IP are required, Invalid IP address, Device with this name or IP already exists. A checagem de duplicidade é global: mesmo nome ou mesmo IP em qualquer grupo bloqueia a criação.

Códigos de marca (equipment)

Mesmos códigos da tela de dispositivo. A marca importa: a descoberta automática de sensores e a filtragem de modelos do catálogo são dirigidas por ela.

Edita um dispositivo com semântica PATCH: só o que for enviado muda. Após salvar, o sistema reprocessa em segundo plano os auto-sensores do dispositivo e regenera a proteção SNMP do servidor, os mesmos efeitos do salvar da tela.

curl -s -d "token=CHAVE&action=dispositivo&operation=edit_device&device_id=123&herdar_snmp=2&snmp_version=2&snmp_community=noc&snmp_port=161" https://ravi.exemplo.com/api/api.php

{"status":"success","device":{"id":123,"nome":"RB Borda","ip":"10.0.0.1","idGrupoPai":12}}

Erros: device_id is required, Device not found, Invalid IP address.

Exclui o dispositivo e todos os seus sensores.

curl -s -d "token=CHAVE&action=dispositivo&operation=delete_device&device_id=123" https://ravi.exemplo.com/api/api.php

{"msg":"ok"}

Erros: Device ID is required, Device not found.

Lista os sensores de um dispositivo. O campo value já vem formatado como na tela (número + unidade do catálogo, por exemplo "87.5 mbps"); para sensores pausados, offline ou novos vem o texto do estado (Pausado, Offline, Sensor não testado).

curl -s "https://ravi.exemplo.com/api/api.php?token=CHAVE&action=dispositivo&operation=list_sensors&device_id=5"

{"sensors":[{"id":301,"name":"Carga de CPU","device_id":5,"status":6,"status_text":"OK","value":"12%","tag":"cpuMikrotik"}]}

Erro: Device ID is required.

Detalha um sensor: identificação, status, valores atuais (crus e médias por coletor), unidade, cronograma, o modelo de catálogo de origem e, quando há uma condição de alerta ativa, o campo context com as condições que dispararam. É a leitura mais completa de um sensor individual.

curl "https://SEU-SERVIDOR/api/api.php?action=dispositivo&operation=get_sensor&sensor_id=8623&token=SEU_TOKEN"

{"sensor":{"id":8623,"name":"Tráfego sfp-sfpplus1","device_id":5,"device_name":"RB Borda",
  "device_ip":"10.0.0.1","status":6,"status_text":"OK","tag":"ifMikrotik","unit":"mbps",
  "schedule":"1m","error_count":0,
  "values":[{"name":"Download","raw_value":"87500000","extension":"mbps","average":"84.2"},
            {"name":"Upload","raw_value":"12300000","extension":"mbps","average":"11.8"}],
  "raw_values":{"value1":"87500000","value2":"12300000","value3":"","value4":""},
  "averages":{"avg1":"84.2","avg2":"11.8","avg3":"","avg4":""},
  "model":{"id":45,"name":"Tráfego de interface","protocol":1,"type":2}}}

• values traz um item por coletor ativo, cada um com name, raw_value, extension (unidade) e average; raw_values e averages expõem os quatro campos crus (value1..4 e avg1..4).
• status segue a tabela de status da Visão geral; status_text é o rótulo no idioma do sistema.
• model identifica o modelo de catálogo de origem.
• O campo context só aparece quando o sensor tem uma condição de alerta ativa: é a lista das condições que dispararam, cada item com a descrição do problema (campo descricao) e os dados da condição. Sensor normal (sem mensagem ativa) vem sem o campo context.

Erros: Sensor ID is required, Sensor not found.

Devolve o histórico de leituras de um sensor em um intervalo de datas, com estatísticas opcionais por coletor. Serve para gráficos externos e relatórios.

curl -s "https://ravi.exemplo.com/api/api.php?token=CHAVE&action=dispositivo&operation=get_sensor_history&sensor_id=8623&start_date=2026-07-01&end_date=2026-07-04"

{"sensor_id":8623,"sensor_name":"Tráfego sfp-sfpplus1","sensor_tag":"ifMikrotik",
 "start_date":"2026-07-01","end_date":"2026-07-04",
 "data":[{"timestamp":"2026-07-01 00:01:00","status":6,"status_text":"OK",
          "values":[{"name":"Download","value":"84.2","unit":"mbps"},
                    {"name":"Upload","value":"11.8","unit":"mbps"}]}],
 "total_records":5760,"returned_records":5760,
 "statistics":{"total_records":5760,"status_summary":{"6":5740,"3":20},
   "values_stats":{"Download":{"min":"0.4","max":"120.7","average":"84.2","unit":"mbps",
     "count":5760,"min_date":"2026-07-02 04:12:00","max_date":"2026-07-03 21:33:00"}}}}

• Cada item de data traz o timestamp, o status/status_text da leitura e os values por coletor (nome, valor e unidade).
• total_records é quanto existe no período; returned_records é quanto veio depois de aplicar o limit.
• Em statistics.values_stats, cada chave é um coletor do sensor, com mínimo, máximo, média, unidade, contagem e as datas do mínimo e do máximo. status_summary conta os registros por código de status.

Erros: Sensor ID is required, Invalid date format. Use YYYY-MM-DD.

Cria um ou mais sensores a partir de um modelo do catálogo. Reformulada na 7.2: a criação é real, com consulta SNMP validada na hora. Os parâmetros extras dependem do protocolo do modelo (descubra-o com sensor_modelos).

O que acontece por tipo de modelo:

• SNMP simples (protocolo 1, tipo 1): a API faz uma consulta SNMP real nos OIDs do modelo usando a cascata SNMP. Se qualquer OID falhar, o sensor não é criado. As condições de alerta são avaliadas na hora: o sensor nasce com status 6 (OK) ou 3 (Alerta).
• Interface (protocolo 1, tipo 2): exige itens (fluxo: sensor_descobrir, escolher, add_sensor). Cria um sensor por item, com status inicial 5 (Não testado). Sem itens, falha com "Nenhuma interface informada (use sensor_descobrir)".
• Ping (protocolo 2): cria com status 5 e parâmetros padrão de ping. Deduplicação por IP: se já existe ping para aquele IP no dispositivo, o item conta como duplicado.
• Agregador (protocolo 8): soma os valores dos sensores-fonte. Deduplicação por conjunto de IDs e por nome. Falhas possíveis: "Selecione ao menos 2 sensores", "Sensores de tipos diferentes", "Sensores nao encontrados".

curl -s -d 'token=CHAVE&action=dispositivo&operation=add_sensor&device_id=123&model_id=45&itens=[{"index":"7","nome":"sfp-sfpplus1"}]' https://ravi.exemplo.com/api/api.php

{"status":"success","message":"criados=3 duplicados=1 falhas=0",
 "criados":[{"id":501,"nome":"sfp-sfpplus1","statusAlert":"5","idDispositivo":123}],
 "duplicados":[{"error":"Ja existe um ping para este IP"}],
 "falhas":[]}

A resposta sempre traz os três conjuntos criados, duplicados e falhas; o status é success se pelo menos um sensor foi criado. Falhas típicas dentro de falhas: SNMP nao configurado, Falha na consulta SNMP, mensagens de OID (com o OID problemático no campo oid), Modelo sem coletores, Protocolo nao suportado: N. Erros diretos: device_id and model_id are required, Device not found.

Edita propriedades de um sensor com semântica PATCH, com uma exceção importante para sensores de ping (veja o aviso abaixo).

curl -s -d "token=CHAVE&action=dispositivo&operation=edit_sensor&sensor_id=501&nome=Uplink SFP+1&cronograma=1m" https://ravi.exemplo.com/api/api.php

{"status":"success"}

Erros: sensor_id is required, Sensor not found, nome obrigatorio.

Pausa um sensor (status 2). Sensor pausado não é coletado nem gera alerta. Útil para silenciar por script durante manutenções.

curl -s -d "token=CHAVE&action=dispositivo&operation=pause_sensor&sensor_id=501" https://ravi.exemplo.com/api/api.php

{"msg":"ok"}

Erros: Sensor ID is required, Sensor not found.

Retoma um sensor pausado: ele volta ao status 5 (Não testado) e assume o status real no próximo ciclo de coleta.

curl -s -d "token=CHAVE&action=dispositivo&operation=resume_sensor&sensor_id=501" https://ravi.exemplo.com/api/api.php

{"msg":"ok"}

Erros: Sensor ID is required, Sensor not found.

Exclui um sensor. Esta operação simples não limpa históricos e arquivos auxiliares; para a limpeza completa de um dispositivo use delete_all_sensors.

curl -s -d "token=CHAVE&action=dispositivo&operation=delete_sensor&sensor_id=501" https://ravi.exemplo.com/api/api.php

{"msg":"ok"}

Erros: Sensor ID is required, Sensor not found.

Exclui todos os sensores de um dispositivo em uma única chamada, espelhando o botão equivalente da tela: remove os sensores, os registros de histórico e alertas associados e os caches de dados em disco. A limpeza é tolerante a falhas parciais nos históricos.

curl -s -d "token=CHAVE&action=dispositivo&operation=delete_all_sensors&device_id=123" https://ravi.exemplo.com/api/api.php

{"status":"success","excluidos":14,"message":"14 sensor(es) excluído(s)"}

Dispositivo sem sensores devolve excluidos: 0 ainda com sucesso. Erros: device_id is required, Device not found.

Lista as categorias do catálogo de sensores (incluindo os grupos de marca), já no idioma do sistema.

curl -s "https://ravi.exemplo.com/api/api.php?token=CHAVE&action=dispositivo&operation=sensor_categorias&device_id=123"

{"status":"success","lang":1,"cats":[{"id":4,"nome":"Mikrotik"},{"id":9,"nome":"Ping"}],"hostIp":"10.0.0.1"}

lang indica o idioma do sistema (1 = português, 2 = inglês, 3 = espanhol); os nomes das categorias já vêm nesse idioma.

Lista os modelos do catálogo por categoria e/ou termo de busca. Os campos que interessam para criar um sensor são o id (vira o model_id) e o par protocolo/tipo, que define quais parâmetros o add_sensor exige.

curl -s "https://ravi.exemplo.com/api/api.php?token=CHAVE&action=dispositivo&operation=sensor_modelos&group_id=4&term=trafego"

{"status":"success","models":[{"id":45,"nome_pt":"Tráfego de interface","tag":"ifMikrotik","protocolo":1,"tipo":2}]}

Descoberta SNMP de interfaces para modelos de interface (protocolo 1, tipo 2, como tráfego de portas). Roda um SNMP walk síncrono no equipamento e devolve as interfaces encontradas, prontas para serem repassadas ao add_sensor no parâmetro itens.

curl -s -d "token=CHAVE&action=dispositivo&operation=sensor_descobrir&device_id=123&model_id=45&timeout=120" https://ravi.exemplo.com/api/api.php

{"status":"success","itens":[{"index":"7","nome":"sfp-sfpplus1","valor1":"..."}],"total":48,"truncado":false}

• O index pode ser composto (por exemplo "idx|id2") em modelos que usam dois índices: repasse o valor exatamente como veio.
• A chamada HTTP fica aberta até o walk terminar (até 240 segundos). Ajuste o timeout do seu cliente HTTP para um valor maior que o timeout pedido.

Erros: device_id and model_id are required, Device not found, Sem retorno da descoberta (timeout ou SNMP) (equipamento não respondeu dentro do prazo, SNMP errado ou modelo sem dados).