API de planos

Um plano é uma velocidade de download/upload com nome, em Mbit/s. Clientes e serviços se referem a um plano pelo nome; o roteador limita o tráfego deles a essa velocidade, e toda OLT registrada mantém perfis e tabelas de taxa correspondentes (veja a API de OLT).

URL base, autenticação (X-API-Key), formato de erro e a API de ações estão descritos na visão geral da API.

Quando um plano é criado, alterado ou excluído, o roteador atualiza os perfis de todas as OLTs registradas em segundo plano (uma OLT por vez, o mesmo trabalho de POST /olt/sync). A resposta não espera por isso; o seu campo olt diz quantas OLTs estão sendo atualizadas, ou é null quando nenhuma OLT está registrada.

Leitura

GET /plans

Lista os planos, cada um com quantos clientes o usam. Qualquer método que não seja POST nem DELETE em /plans responde a mesma lista.

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

{
  "count": 2,
  "plans": [
    {
      "name": "plan_100_50",
      "down_mbps": 100,
      "up_mbps": 50,
      "comment": "Home 100",
      "created": "2026-09-01 10:00:00",
      "clients": 12
    },
    {
      "name": "plan_300_150",
      "down_mbps": 300,
      "up_mbps": 150,
      "comment": "",
      "created": "2026-09-01 10:05:00",
      "clients": 0
    }
  ]
}

A contagem clients inclui somente os clientes baseados em MAC.

Alteração

POST /plans

Altera o roteador

Cria um plano, ou atualiza as taxas e o comentário de um plano existente com o mesmo nome; as OLTs acompanham em segundo plano.

Cria um plano novo (201). Se já existe um plano com esse nome, os seus down_mbps, up_mbps e comment são substituídos (200) e todo cliente com controle de banda passa na hora para as novas taxas.

Nome	Em	Tipo	Observações
name	body	string	Obrigatório. Letras, dígitos, _ e -, de 1 a 40 caracteres.
down_mbps	body	integer	Obrigatório. 1–100.000.
up_mbps	body	integer	Obrigatório. 1–100.000.
comment	body	string	Texto livre opcional.

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "plan_100_50", "down_mbps": 100, "up_mbps": 50, "comment": "Home 100"}' \
  "http://ROUTER-IP:8880/plans"

{
  "ok": true,
  "code": 201,
  "message": "Plan created",
  "plan": {
    "name": "plan_100_50",
    "down_mbps": 100,
    "up_mbps": 50,
    "comment": "Home 100",
    "created": "2026-09-28 12:00:00"
  },
  "olt": "profiles are being created on 1 OLT(s) in the background"
}

Uma atualização responde "code": 200, "message": "Plan updated" e "olt": "profiles are being updated on …". Erros: 400 para um nome inválido ou taxas fora da faixa.

DELETE /plans/{name}

Altera o roteador

Exclui um plano; os seus perfis nas OLTs são removidos em segundo plano, a menos que alguma ONT ainda os use.

Recusado com 409 enquanto algum cliente ainda usar o plano. O nome também pode ir no corpo como name (e então DELETE /plans também funciona).

Nome	Em	Tipo	Observações
name	path	string	O plano a excluir.
name	body	string	Alternativa ao caminho; tem precedência quando presente.

curl -X DELETE -H "X-API-Key: YOUR_API_KEY" "http://ROUTER-IP:8880/plans/plan_300_150"

{
  "ok": true,
  "code": 200,
  "message": "Plan deleted",
  "olt": "profiles are being removed on 1 OLT(s) in the background"
}

Erros: 404 quando nenhum plano tem esse nome; 409 quando há clientes usando o plano:

{
  "ok": false,
  "code": 409,
  "error": "Plan 'plan_100_50' is used by 12 client(s); reassign them first",
  "clients": ["AA:BB:CC:DD:EE:FF", "..."]
}

Para dar um plano a um cliente, use POST /plan na API de clientes; para mudar o plano de um serviço, use a API de serviços.

Equivalentes na API de ações

Ação	Parâmetros de consulta	Equivale a
action=plan-list	—	GET /plans
action=plan-add	name, down_mbps, up_mbps, comment	POST /plans
action=plan-del	name	DELETE /plans/{name}