API do sistema

Os endpoints desta página descrevem o roteador como um todo: seu status, suas verificações de saúde, seus backups e versões salvas da configuração, e os gráficos de tráfego que ele desenha. Para a URL base, a autenticação e o formato de erro, veja a visão geral da API.

Status e verificações

GET /status

Um resumo do roteador em uma única chamada: versão, se o serviço DHCP está rodando, quantos clientes legados por MAC estão cadastrados e online, clientes por rede e o modo de anti-spoofing.

curl -s http://ROUTER-IP:8880/status -H "X-API-Key: YOUR_API_KEY"

{
    "api": "DTVSOL DHCP API v1.0",
    "router_version": "2026.09.27",
    "dhcp_service": "running",
    "total_clients": 42,
    "online_clients": 37,
    "per_network": {
        "10.110.0.0/21": 42
    },
    "interfaces": 6,
    "antispoof": "strict",
    "server_time": "2026-09-28 10:15:00"
}

antispoof é o modo configurado (strict ou dynamic) quando o anti-spoofing está habilitado; caso contrário, off. online_clients conta os clientes cujo endereço é, neste momento, um vizinho ativo do roteador.

GET /doctor

O doctor de configuração: uma auditoria completa da configuração do roteador e do que sobrevive a uma reinicialização (endereços, VLANs, configuração de DHCP e de router advertisement, arquivos de dados, o armazenamento de configuração, NTP para as OLTs). Com ?olt=1 ele também verifica cada OLT cadastrada contra os registros do roteador. Ele apenas lê.

Nome	Em	Tipo	Observações
olt	query	boolean	1 verifica também as OLTs cadastradas (mais lento). Omitido: apenas o roteador.

curl -s "http://ROUTER-IP:8880/doctor?olt=1" -H "X-API-Key: YOUR_API_KEY"

{
    "ok": true,
    "code": 200,
    "generated": "2026-09-28 10:15:00",
    "count": 1,
    "counts": {
        "critical": 0,
        "warning": 1,
        "info": 0
    },
    "findings": [
        {
            "severity": "warning",
            "area": "dhcp",
            "problem": "…",
            "detail": "…",
            "fix": "…"
        }
    ]
}

ok é true quando não há achados critical. Cada achado traz uma severity (critical, warning ou info), a area a que se refere, o problem, um detail e uma correção sugerida em fix. O status HTTP é sempre 200; leia ok e counts.

O equivalente na CLI é dtvsol doctor (com as verificações de OLT) ou dtvsol doctor --no-olt.

GET /alerts

As condições que merecem atenção agora: o serviço DHCP parado, links de VLAN caídos, pools de endereços quase cheios, o pool de CGNAT, descartes do anti-spoofing, dispositivos desconhecidos, problemas de OLT e de fibra informados pelo coletor de OLT, e a licença. Ele apenas lê.

curl -s http://ROUTER-IP:8880/alerts -H "X-API-Key: YOUR_API_KEY"

{
    "count": 2,
    "generated": "2026-09-28 10:15:00",
    "alerts": [
        {
            "severity": "critical",
            "type": "dhcp",
            "message": "DHCP service is not running"
        },
        {
            "severity": "warning",
            "type": "olt",
            "olt": "olt-1",
            "message": "OLT olt-1: …"
        }
    ]
}

severity é critical, warning ou info. type é um de dhcp, interface, dhcp-pool, stranger, cgnat, spoof, olt, fiber ou licence; os alertas de OLT e de fibra também informam a olt (e, no caso de fibra, a porta e a ONT).

Para alarmes com histórico (disparados, normalizados, reconhecidos), veja a API de alarmes e saúde.

Backup e restauração

GET /backup

Baixa um backup completo do roteador como um arquivo .tar.gz: os diretórios etc/ e data/, com o banco de dados de configuração incluído como uma cópia consistente feita naquele momento. A resposta é o próprio arquivo (Content-Type: application/gzip, com um nome de arquivo em Content-Disposition como dtvsol-router-backup-20260928-101500.tar.gz).

Nota

O arquivo contém a configuração do roteador, incluindo a chave de API e as credenciais protegidas das OLTs. Guarde-o com a mesma segurança do próprio roteador.

curl -s http://ROUTER-IP:8880/backup -H "X-API-Key: YOUR_API_KEY" -OJ

Em caso de falha, a resposta é um JSON com status 500:

{
    "error": "Backup failed",
    "detail": "…"
}

O equivalente na CLI é dtvsol backup [outfile.tar.gz].

POST /restore

Altera o roteador

Substitui a configuração do roteador pelo conteúdo de um arquivo de backup e reaplica todos os serviços.

Restaura um arquivo de backup que já está no roteador (envie-o antes, por exemplo com scp). Antes de descompactar, a configuração atual é salva como uma nova versão de configuração, de modo que a própria restauração pode ser desfeita com dtvsol config restore <undo_version> --yes. Depois de descompactar, o roteador reescreve os arquivos de hosts do DHCP e reaplica o controle de banda, a contabilização, o CGNAT, os redirecionamentos de porta, o anti-spoofing e as regras de firewall.

Nome	Em	Tipo	Observações
file	body	string	Caminho do arquivo .tar.gz no roteador. Obrigatório.

curl -s -X POST http://ROUTER-IP:8880/restore \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file": "/root/dtvsol-router-backup-20260928-101500.tar.gz"}'

{
    "ok": true,
    "code": 200,
    "message": "Restored and services reapplied",
    "documents": ["clients", "services"],
    "undo_version": 57
}

Erros: 400 quando o arquivo não existe ("Provide an existing backup file path (upload it to the router first)") ou não é um tar.gz válido; 500 quando a extração falha, ou quando o arquivo foi descompactado mas nem todos os seus documentos de configuração puderam ser importados — essa resposta inclui undo_version e uma dica next com o comando que volta à configuração anterior à restauração.

O equivalente na CLI é dtvsol restore <file.tar.gz>.

Versões de configuração (action API)

O roteador mantém versões salvas da sua configuração no seu banco de dados, como a configuração salva na flash de um switch. Via HTTP, elas só são acessíveis pela action API (/api?action=…); os parâmetros vão na query string ou, para POST, em um corpo JSON (o corpo prevalece; a query string completa o que faltar no corpo). O equivalente na CLI é dtvsol config ….

Ação	Método	Parâmetros	O que faz
action=config-status	GET	—	Com qual versão salva a configuração em execução coincide, o id da versão mais recente e se há mudanças não salvas (arquivos adicionados, removidos, alterados).
action=config-versions	GET	n (padrão 30, 1–1000)	As versões salvas mais recentes: id, saved_at, saved_by, comment, auto, files, bytes, digest.
action=config-save	POST	comment (opcional, até 200 caracteres)	Altera o roteador: salva a configuração em execução como uma nova versão. Um GET é recusado com 405. Responde 201.
action=config-diff	GET	from (id de versão, obrigatório), to (id de versão ou running, padrão running)	O que mudou entre duas versões, ou entre uma versão e a configuração em execução.
action=config-show	GET	id (id de versão, obrigatório), path (opcional)	Sem path: a lista de arquivos daquela versão. Com path: o conteúdo desse arquivo, com senhas, chaves e tokens mascarados.

A restauração de uma versão salva é feita pela CLI: dtvsol config restore <id> --yes.

curl -s "http://ROUTER-IP:8880/api?action=config-status" -H "X-API-Key: YOUR_API_KEY"

{
    "ok": true,
    "saved": {
        "id": 57,
        "saved_at": "2026-09-28 09:00:00",
        "comment": "before maintenance"
    },
    "latest": 57,
    "unsaved": true,
    "changes": {
        "added": [],
        "removed": [],
        "changed": ["data/services.json"]
    },
    "code": 200
}

curl -s -X POST "http://ROUTER-IP:8880/api?action=config-save" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"comment": "new plans for October"}'

{
    "ok": true,
    "saved": true,
    "version": 58,
    "files": 24,
    "message": "…",
    "code": 201
}

curl -s "http://ROUTER-IP:8880/api?action=config-diff&from=57&to=running" -H "X-API-Key: YOUR_API_KEY"

{
    "ok": true,
    "from": 57,
    "to": "running",
    "changes": {
        "added": [],
        "removed": [],
        "changed": ["data/services.json"]
    },
    "diff": "…",
    "code": 200
}

curl -s "http://ROUTER-IP:8880/api?action=config-show&id=57" -H "X-API-Key: YOUR_API_KEY"

{
    "ok": true,
    "version": 57,
    "files": ["etc/config.php", "data/services.json"],
    "code": 200
}

Erros: 400 para from/id ausente ou não numérico, ou um to que não seja nem um id de versão nem running; 404 para uma versão (ou um arquivo de uma versão) que não existe; 500 quando o armazenamento não pode ser lido.

Gráficos de tráfego

Os gráficos são devolvidos como imagens PNG (Content-Type: image/png). Quando nenhum gráfico pode ser desenhado, a resposta é um JSON: {"error": "…"} com status 400 (parâmetros inválidos), 404 (ainda sem dados — as amostras são coletadas a cada minuto) ou 500 (falha ao desenhar).

GET /graph/{name}

Tráfego de um assinante ou de uma interface. {name} é um id de serviço (svc_ seguido de 8 dígitos hexadecimais), o endereço MAC de um cliente ou o nome de uma interface (por exemplo vlan100).

Nome	Em	Tipo	Observações
name	path	string	Id de serviço, endereço MAC ou nome de interface.
period	query	string	hour (últimas 3 horas), day (padrão), week, month ou year.

curl -s "http://ROUTER-IP:8880/graph/vlan100?period=week" \
  -H "X-API-Key: YOUR_API_KEY" -o graph.png

GET /graph/oltport

Tráfego de uma porta PON de OLT, de uma porta de uplink ou de uma placa inteira (todas as suas portas), a partir das amostras do coletor de OLT.

Nome	Em	Tipo	Observações
olt	query	string	Nome da OLT cadastrada. Obrigatório.
port	query	string	F/S/P para uma porta, ou F/S para uma placa inteira. Obrigatório.
pon	query	boolean	1 (padrão): uma porta PON; 0: uma porta de uplink.
period	query	string	hour, day (padrão), week, month, quarter, year ou 2years.

curl -s "http://ROUTER-IP:8880/graph/oltport?olt=olt-1&port=0/1/3&period=month" \
  -H "X-API-Key: YOUR_API_KEY" -o graph.png

GET /graph/ont

Tráfego ou contadores de erro de uma ONT, como vistos pela OLT.

Nome	Em	Tipo	Observações
olt	query	string	Nome da OLT cadastrada. Obrigatório.
port	query	string	Porta PON F/S/P. Obrigatório.
ont	query	integer	Id da ONT nessa porta. Obrigatório.
what	query	string	traffic (padrão) ou errors.
period	query	string	hour, day (padrão), week, month, quarter, year ou 2years.

curl -s "http://ROUTER-IP:8880/graph/ont?olt=olt-1&port=0/1/3&ont=12&what=errors" \
  -H "X-API-Key: YOUR_API_KEY" -o graph.png

GET /services/{id}/graph

Tráfego de um serviço. {id} é qualquer coisa que identifique o serviço (veja a API de serviços).

Nome	Em	Tipo	Observações
id	path	string	Id do serviço ou outra chave do serviço.
source	query	string	router (padrão): tráfego através do roteador; olt: tráfego da sua ONT conforme contado pela OLT; errors: os contadores de erro da ONT.
period	query	string	Para router: hour, day (padrão), week, month, year. Para olt/errors: também quarter e 2years.

curl -s "http://ROUTER-IP:8880/services/svc_1a2b3c4d/graph?source=olt&period=week" \
  -H "X-API-Key: YOUR_API_KEY" -o graph.png

Erros: 404 "No such service", ou "This service has no ONT" para source=olt|errors em um serviço sem ONT.

Licença

A licença do roteador não é exposta pela API HTTP. Ela é gerenciada no roteador pela CLI:

Comando	O que faz
dtvsol licence status	Mostra se o roteador está inscrito, o provedor da licença, se a licença é válida (e, se não, por quê), sua data de expiração com os dias restantes, a última renovação (horário e resultado) e uma observação sobre o relógio.
dtvsol licence refresh	Obtém uma licença nova agora (um temporizador também faz isso diariamente).
dtvsol licence enrol <id> <token|->	Inscreve o roteador com o id e o token emitidos para ele; - lê o token da entrada padrão.

Uma licença prestes a expirar ou inválida também aparece como um alerta licence em GET /alerts.

Equivalentes na action API

Ação	Equivale a
action=status	GET /status
action=doctor (&olt=1)	GET /doctor
action=alerts	GET /alerts
action=config-status	dtvsol config status
action=config-versions	dtvsol config versions [n]
action=config-save (POST)	dtvsol config save ["comment"]
action=config-diff	dtvsol config diff <a> [b|running]
action=config-show	dtvsol config show <id> [path]