API de clientes

Um cliente é o registro de assinante legado, baseado em MAC: um endereço MAC fixado a um endereço IPv4 fixo (e opcionalmente a um endereço IPv6) em uma das redes do roteador, atendido por DHCP, com um plano de velocidade opcional, um indicador de suspensão e uma data de término opcional. Integrações novas que provisionam ONTs usam a API de serviços; os clientes continuam existindo para sistemas de cobrança e redes baseados no MAC do CPE.

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.

Endereços MAC são aceitos em qualquer formato comum (aa-bb-cc-dd-ee-ff, aabbccddeeff, AA:BB:CC:DD:EE:FF) e são armazenados em maiúsculas com dois-pontos.

Leitura

GET /clients

Lista os clientes cadastrados, cada um com os endereços IPv6 que ele está de fato usando e qualquer prefixo delegado a ele.

Nome	Em	Tipo	Observações
network	query	CIDR	Só os clientes cujo endereço IPv4 está nesta rede, por exemplo 10.110.0.0/21.
q	query	string	Busca sem diferenciar maiúsculas de minúsculas em MAC, IP, IPv6, hostname, comentário, interface e rede.

curl -H "X-API-Key: YOUR_API_KEY" "http://ROUTER-IP:8880/clients?network=10.110.0.0/21"

{
  "count": 1,
  "clients": [
    {
      "mac": "AA:BB:CC:DD:EE:FF",
      "ip": "10.110.0.2",
      "ipv6": null,
      "plan": "plan_100_50",
      "suspended": false,
      "auto_suspended": false,
      "expires": null,
      "hostname": "client-aabbccddeeff",
      "network": "10.110.0.0/21",
      "network6": null,
      "iface": "vlan100",
      "gateway": "10.110.0.1",
      "comment": "",
      "created": "2026-09-01 10:00:00",
      "ipv6_actual": "XXXX:XXXX:100::25",
      "ipv6_all": ["XXXX:XXXX:100::25"],
      "ipv6_state": "REACHABLE",
      "prefix6_delegated": []
    }
  ]
}

GET /clients/{mac}

Um cliente. {mac} também pode ser o endereço IPv4 do cliente, o seu endereço IPv6 ou o seu hostname (sem diferenciar maiúsculas de minúsculas).

Nome	Em	Tipo	Observações
mac	path	string	MAC, IPv4, IPv6 ou hostname.

curl -H "X-API-Key: YOUR_API_KEY" http://ROUTER-IP:8880/clients/AA:BB:CC:DD:EE:FF

{
  "client": {
    "mac": "AA:BB:CC:DD:EE:FF",
    "ip": "10.110.0.2",
    "hostname": "client-aabbccddeeff",
    "network": "10.110.0.0/21",
    "iface": "vlan100",
    "gateway": "10.110.0.1",
    "plan": "plan_100_50",
    "suspended": false,
    "expires": null
  }
}

404 {"error": "Client not found"} quando nada corresponde.

GET /clients/active

Quem está online agora: todos os clientes e todos os serviços com o seu estado de vizinhança (ARP/NDP), mais as concessões DHCP dinâmicas que não pertencem a nenhum dos dois. status é online (REACHABLE, DELAY, PROBE, PERMANENT), recent (STALE) ou offline. mac_mismatch é true quando o endereço é respondido por um MAC diferente do cadastrado.

Nome	Em	Tipo	Observações
state	query	string	Só as entradas online, recent ou offline (o resumo continua contando tudo).

curl -H "X-API-Key: YOUR_API_KEY" "http://ROUTER-IP:8880/clients/active?state=online"

{
  "summary": {
    "registered": 120,
    "services": 340,
    "online": 401,
    "recent": 12,
    "offline": 47,
    "dynamic_active_leases": 3
  },
  "clients": [
    {
      "mac": "AA:BB:CC:DD:EE:FF",
      "ip": "10.110.0.2",
      "hostname": "client-aabbccddeeff",
      "iface": "vlan100",
      "status": "online",
      "neigh_state": "REACHABLE",
      "seen_mac": "AA:BB:CC:DD:EE:FF",
      "mac_mismatch": false,
      "ipv6_actual": null,
      "ipv6_all": [],
      "prefix6_delegated": []
    },
    {
      "mac": "AA:BB:CC:00:11:22",
      "ip": "100.64.16.9",
      "hostname": "Customer name",
      "iface": "vlan116",
      "status": "online",
      "neigh_state": "REACHABLE",
      "service": "svc_1a2b3c4d",
      "service_state": "active",
      "seen_mac": "AA:BB:CC:00:11:22",
      "mac_mismatch": false
    }
  ],
  "dynamic_leases": [
    {
      "ip": "10.120.0.50",
      "state": "active",
      "mac": "AA:BB:CC:33:44:55",
      "hostname": "cpe",
      "ends": "2026/09/28 12:00:00",
      "neigh_state": "STALE",
      "online": false
    }
  ]
}

GET /clients6

Todo MAC visto na rede via IPv6 — cadastrado ou não — com o endereço IPv6 que ele usa, a sua concessão DHCPv6, o seu prefixo fixado e o prefixo delegado a ele. Os MACs do próprio roteador ficam de fora; outros roteadores (anúncios de roteador IPv6) ficam de fora, a menos que se passe routers=1 ou que estejam cadastrados ou tenham uma concessão.

Nome	Em	Tipo	Observações
iface	query	string	Só esta interface, por exemplo vlan100.
routers	query	1	Inclui os roteadores vizinhos.

curl -H "X-API-Key: YOUR_API_KEY" "http://ROUTER-IP:8880/clients6?iface=vlan100"

{
  "summary": { "total": 1, "online": 1, "registered": 1, "with_prefix": 1 },
  "clients": [
    {
      "mac": "AA:BB:CC:DD:EE:FF",
      "registered": true,
      "hostname": "client-aabbccddeeff",
      "ipv4": "10.110.0.2",
      "iface": "vlan100",
      "ipv6": "XXXX:XXXX:100::25",
      "ipv6_all": ["XXXX:XXXX:100::25"],
      "ipv6_reserved": null,
      "link_local": "fe80::aabb:ccff:fedd:eeff",
      "state": "REACHABLE",
      "online": true,
      "router": false,
      "lease6": ["XXXX:XXXX:100::25"],
      "prefix6_pinned": null,
      "prefix6_delegated": ["XXXX:XXXX:b:500::/64"]
    }
  ],
  "orphan_delegated_prefixes": []
}

GET /ips

Uso de endereços por rede no roteador: os endereços cadastrados, os endereços não cadastrados vistos ao vivo na rede e os dez primeiros endereços livres.

Nome	Em	Tipo	Observações
network	query	CIDR	Uma rede, por exemplo 10.110.0.0/21. Omita para todas.

curl -H "X-API-Key: YOUR_API_KEY" "http://ROUTER-IP:8880/ips?network=10.110.0.0/21"

{
  "ok": true,
  "code": 200,
  "count": 1,
  "networks": [
    {
      "network": "10.110.0.0/21",
      "iface": "vlan100",
      "gateway": "10.110.0.1",
      "total_assignable": 2045,
      "used_count": 1,
      "free_count": 2044,
      "next_free": ["10.110.0.3", "10.110.0.4"],
      "used": [ { "ip": "10.110.0.2", "mac": "AA:BB:CC:DD:EE:FF", "hostname": "client-aabbccddeeff" } ],
      "unregistered_seen": [ { "ip": "10.110.0.77", "mac": "AA:BB:CC:66:77:88", "neigh_state": "STALE" } ]
    }
  ]
}

404 quando a rede indicada não está neste roteador.

Alteração

POST /clients

Altera o roteador

Adiciona uma reserva DHCP, a regra de filtro de MAC e (com um plano) o controle de banda do cliente; recarrega o DHCP.

Cadastra um cliente. O endereço IPv4 precisa estar em uma rede configurada em uma das interfaces do roteador (e não ser o endereço de rede, de gateway ou de broadcast); a rede, a interface e o gateway são obtidos dali. Um endereço IPv6, quando informado, precisa estar na mesma interface.

Nome	Em	Tipo	Observações
mac	body	string	Obrigatório.
ip	body	IPv4	Obrigatório.
ipv6	body	IPv6	Endereço IPv6 fixo opcional.
hostname	body	string	Letras, dígitos, pontos, hífens, máximo 63. Padrão client-<mac without colons>.
comment	body	string	Texto livre.
plan	body	string	O nome de um plano existente, ou none.
expires	body	date	Data de término (YYYY-MM-DD ou YYYY-MM-DD HH:MM), ou never.

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"mac":"AA:BB:CC:DD:EE:FF","ip":"10.110.0.2","hostname":"cpe-1","plan":"plan_100_50"}' \
  http://ROUTER-IP:8880/clients

{
  "ok": true,
  "code": 201,
  "message": "Client added successfully",
  "client": {
    "mac": "AA:BB:CC:DD:EE:FF",
    "ip": "10.110.0.2",
    "ipv6": null,
    "plan": "plan_100_50",
    "suspended": false,
    "auto_suspended": false,
    "expires": null,
    "hostname": "cpe-1",
    "network": "10.110.0.0/21",
    "network6": null,
    "iface": "vlan100",
    "gateway": "10.110.0.1",
    "comment": "",
    "created": "2026-09-28 10:00:00"
  }
}

Erros: 400 MAC/IP/IPv6/hostname inválido ou um endereço fora das redes do roteador; 404 plano desconhecido; 409 MAC, IP, IPv6 ou hostname já em uso (para um MAC duplicado a resposta traz existing); 500 quando o DHCP não recarrega — nesse caso o cadastro do cliente é desfeito.

DELETE /clients/{mac}

Altera o roteador

Remove a reserva, as regras de filtro de MAC, qualquer suspensão e o controle de banda do cliente; recarrega o DHCP.

Nome	Em	Tipo	Observações
mac	path	string	Obrigatório.

curl -X DELETE -H "X-API-Key: YOUR_API_KEY" http://ROUTER-IP:8880/clients/AA:BB:CC:DD:EE:FF

{
  "ok": true,
  "code": 200,
  "message": "Client deleted",
  "client": { "mac": "AA:BB:CC:DD:EE:FF", "ip": "10.110.0.2", "hostname": "cpe-1" },
  "dhcp": { "ok": true, "message": "DHCP reloaded" }
}

404 quando o cliente não existe; 400 {"error": "Specify MAC"} sem um MAC.

POST /plan

Altera o roteador

Define o plano de velocidade do cliente e reconstrói o controle de banda na sua interface.

Nome	Em	Tipo	Observações
mac	body	string	Obrigatório.
plan	body	string	Um nome de plano; vazio ou none remove o limite.

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"mac":"AA:BB:CC:DD:EE:FF","plan":"plan_200_100"}' \
  http://ROUTER-IP:8880/plan

{ "ok": true, "code": 200, "message": "Plan assigned", "mac": "AA:BB:CC:DD:EE:FF", "plan": "plan_200_100" }

404 para um cliente ou plano desconhecido.

POST /suspend

Altera o roteador

Bloqueia o tráfego do cliente (regras de suspensão) até que ele seja reativado.

O MAC pode ir no corpo ou no caminho (POST /suspend/{mac}). Suspender manualmente limpa o indicador de suspensão automática (por data de término).

Nome	Em	Tipo	Observações
mac	body ou path	string	Obrigatório.

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"mac":"AA:BB:CC:DD:EE:FF"}' http://ROUTER-IP:8880/suspend

{ "ok": true, "code": 200, "message": "Client suspended", "mac": "AA:BB:CC:DD:EE:FF", "suspended": true }

POST /resume

Altera o roteador

Remove a suspensão do cliente.

Mesmos parâmetros de POST /suspend (MAC no corpo ou no caminho).

curl -X POST -H "X-API-Key: YOUR_API_KEY" http://ROUTER-IP:8880/resume/AA:BB:CC:DD:EE:FF

{ "ok": true, "code": 200, "message": "Client resumed", "mac": "AA:BB:CC:DD:EE:FF", "suspended": false }

POST /expires

Altera o roteador

Define a data de término do cliente; uma data no passado o suspende na hora, uma data futura reativa um cliente que a data de término havia suspendido.

Depois que a data é gravada, as datas de término de todos os clientes são reconciliadas imediatamente (o roteador também faz isso a cada 5 minutos).

Nome	Em	Tipo	Observações
mac	body	string	Obrigatório.
expires	body	date	YYYY-MM-DD ou YYYY-MM-DD HH:MM; vazio ou never a remove.

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"mac":"AA:BB:CC:DD:EE:FF","expires":"2026-10-31"}' \
  http://ROUTER-IP:8880/expires

{
  "ok": true,
  "code": 200,
  "message": "End date set",
  "mac": "AA:BB:CC:DD:EE:FF",
  "expires": "2026-10-31 00:00:00",
  "suspended": false
}

400 para uma data que ele não consegue ler, 404 para um cliente desconhecido.

Equivalentes na API de ações

Todas são GET /api?action=… com os parâmetros na query string (veja a visão geral da API).

Ação	Parâmetros de consulta	Equivale a
action=list	[network]	GET /clients
action=search	q	GET /clients?q= (a resposta acrescenta query)
action=get	mac	GET /clients/{mac}
action=add	mac, ip, [hostname], [comment], [ipv6]	POST /clients (sem plano nem data de término)
action=delete	mac	DELETE /clients/{mac}
action=active / action=connected	[state]	GET /clients/active
action=clients6	[iface], [routers=1]	GET /clients6
action=ip-info	[network]	GET /ips
action=set-plan	mac, plan	POST /plan
action=suspend / action=resume	mac	POST /suspend / POST /resume
action=set-expires	mac, expires	POST /expires