API de serviços

Um serviço é um assinante na rede de fibra: uma ONT em uma porta PON de uma OLT registrada, um endereço IPv4 fixo (e opcionalmente IPv6 com um prefixo delegado) na rede dessa porta, um plano de velocidade e uma data de término opcional. Esta é a API que um sistema de cobrança usa. Não é necessário o endereço MAC do CPE: o roteador reconhece a ONT pela porta e pelo id de ONT que a OLT insere nas suas requisições DHCP (Option 82).

A numeração é derivada, nunca escolhida: os assinantes de uma porta PON compartilham a C-VLAN dessa porta, 100 + card × 16 + pon (porta 0/1/0 → C-VLAN 116) dentro da S-VLAN do roteador, e o seu bloco de endereços. Os registros legados baseados em MAC são a API de clientes.

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.

Tempos limite

Chamadas que acessam uma OLT (POST /services, alterações de plano, suspensão/reativação, exclusão, migração, GET /services/unregistered) mantêm uma sessão com a OLT: reserve pelo menos 60 s por chamada. Um roteador fala com uma OLT uma sessão por vez, então uma chamada pode ter de esperar primeiro o trabalho do próprio roteador com a OLT.

O fluxo da cobrança

1. O técnico instala a ONU; o sistema de cobrança consulta GET /services/unregistered e mostra os seriais encontrados.
2. O técnico escolhe um; o sistema de cobrança chama POST /services com seu próprio ref, o sn, olt, pon, plano e nome.
3. A resposta (201) traz service.id — guarde-o — e technician.user_vlan: configure a WAN da ONU nessa VLAN com DHCP.
4. Depois, pelo id: alterar o plano ou a data de término (POST /services/{id}), suspender/reativar, excluir, status, gráfico de tráfego.

Estados do serviço

provisioning (em criação), active, suspended, error (a parte da OLT foi feita, mas a parte do roteador falhou — corrija a causa e envie {"retry": true}).

Leitura

GET /services

Lista os serviços (os excluídos nunca são listados), cada um com um bloco live, a menos que fast=1. states conta todos os serviços por estado.

Nome	Em	Tipo	Observações
state	query	string	active, suspended, error, provisioning.
olt	query	string	Apenas os serviços desta OLT.
q	query	string	Busca de texto sem diferenciar maiúsculas em todo o registro.
fast	query	1	Pula a verificação ao vivo (link, vizinho, concessão).

curl -H "X-API-Key: YOUR_API_KEY" "http://ROUTER-IP:8880/services?state=active&olt=olt-1&fast=1"

{
  "ok": true,
  "code": 200,
  "count": 1,
  "states": { "active": 340, "suspended": 12 },
  "services": [
    {
      "id": "svc_1a2b3c4d",
      "ref": "billing-000812",
      "name": "Customer name",
      "olt": "olt-1",
      "pon": "0/1/0",
      "ont_id": 7,
      "state": "active"
    }
  ]
}

GET /services/{id}

Um serviço com seu estado ao vivo e seu plano. {id} aceita o id do serviço, o ref do sistema de cobrança, o serial da ONT, o contrato, o endereço IPv4 ou o nome da interface.

Nome	Em	Tipo	Observações
id	path	string	Id, ref, serial, contrato, endereço ou interface.

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

{
  "ok": true,
  "code": 200,
  "service": {
    "id": "svc_1a2b3c4d",
    "ref": "billing-000812",
    "name": "Customer name",
    "contract": "C-00812",
    "comment": null,
    "olt": "olt-1",
    "pon": "0/1/0",
    "ont_id": 7,
    "sn": "0123456789ABCDEF",
    "svlan": 500,
    "cvlan": 116,
    "user_vlan": 116,
    "iface": "v500.116",
    "ipv4": { "network": "100.64.16.0/24", "gateway": "100.64.16.1", "address": "100.64.16.9" },
    "ipv6": { "link": "XXXX:XXXX:a:183::/64", "pd": "XXXX:XXXX:b:8300::/56" },
    "plan": "plan_200_200",
    "iptv": false,
    "expires": "2026-10-31 00:00:00",
    "state": "active",
    "created": "2026-09-25 10:30:00",
    "updated": "2026-09-25 10:30:00",
    "olt_service_ports": { "internet": 1234, "iptv": null },
    "live": {
      "iface_exists": true,
      "link": "up",
      "online": true,
      "mac": "AA:BB:CC:DD:EE:FF",
      "neigh_state": "REACHABLE",
      "lease": { "state": "active", "mac": "AA:BB:CC:DD:EE:FF", "ends": "2026/09/28 12:00:00", "hostname": null }
    }
  },
  "plan": { "name": "plan_200_200", "down_mbps": 200, "up_mbps": 200 }
}

404 quando nenhum serviço corresponde. O gráfico de tráfego de um serviço é GET /services/{id}/graph — veja a API do sistema.

GET /services/unregistered

Pergunta a todas as OLTs registradas (ou a uma) quais ONTs elas veem conectadas e ainda não registradas — a lista de escolha do técnico. Cada OLT é consultada por vez. errors indica as OLTs que não puderam ser consultadas; cvlan é a C-VLAN que a porta da ONT usa.

Nome	Em	Tipo	Observações
olt	query	string	Consulta apenas esta OLT.

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

{
  "ok": true,
  "code": 200,
  "count": 1,
  "onts": [
    {
      "olt": "olt-1",
      "pon": "0/1/0",
      "sn": "0123456789ABCDEF",
      "vendor": "ABCD",
      "model": "ONT-MODEL",
      "software": null,
      "seen_at": "2026-09-25 10:12:03+00:00",
      "svlan": 500,
      "cvlan": 116
    }
  ],
  "errors": {},
  "next": "POST /services {ref, sn, olt, pon, plan|down_mbps+up_mbps, name, ...}"
}

Alteração

POST /services

Altera o roteador e a OLT

Registra a ONT na OLT (perfis, limite de velocidade, service-port) e depois cria o endereço, DHCP, CGNAT, contabilização e anti-spoofing no roteador.

Cria um serviço em uma única chamada síncrona; quando responde 201, o serviço já está ativo. Com ref, a chamada é idempotente: repeti-la retorna o serviço existente (200, "existing": true) em vez de criar um segundo.

Nome	Em	Tipo	Observações
ref	body	string	Recomendado: o id próprio do sistema de cobrança para este serviço.
sn	body	string	Serial da ONT, 16 dígitos hexadecimais. Obrigatório com uma OLT.
olt	body	string	Nome de uma OLT registrada; obrigatório quando há mais de uma OLT registrada.
pon	body	string	Porta PON frame/slot/port. Se omitida, o serial é procurado na tabela autofind da OLT.
plan	body	string	Nome de um plano existente…
down_mbps, up_mbps	body	integer	…ou as velocidades: o plano plan_<down>_<up> é criado se não existir.
name	body	string	Obrigatório: o cliente.
contract, comment	body	string	Texto livre.
user_vlan	body	integer	1–4094: a VLAN que a ONU envia, quando não é a C-VLAN da porta (a OLT a traduz).
ipv6	body	boolean	Padrão true quando o roteador tem um pool IPv6 de serviço configurado.
iptv	body	boolean	Coloca a porta IPTV da ONT na VLAN de IPTV da OLT (quando a OLT tem uma).
expires	body	date	Data de término; nessa data o roteador suspende o serviço, e o reativa quando uma data posterior é definida. never a remove.
svlan, ont_id	body	integer	Apenas com "olt": "none" (uma ONT provisionada manualmente): obrigatórios junto com pon.

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"ref":"billing-000812","sn":"0123456789ABCDEF","olt":"olt-1","pon":"0/1/0",
       "down_mbps":200,"up_mbps":200,"name":"Customer name","contract":"C-00812",
       "expires":"2026-10-31"}' \
  http://ROUTER-IP:8880/services

{
  "ok": true,
  "code": 201,
  "message": "Service created",
  "service": {
    "id": "svc_1a2b3c4d",
    "ref": "billing-000812",
    "pon": "0/1/0",
    "ont_id": 7,
    "svlan": 500,
    "cvlan": 116,
    "user_vlan": 116,
    "iface": "v500.116",
    "ipv4": { "network": "100.64.16.0/24", "gateway": "100.64.16.1", "address": "100.64.16.9" },
    "plan": "plan_200_200",
    "state": "active"
  },
  "technician": {
    "user_vlan": 116,
    "note": "set the ONU's WAN to VLAN 116, DHCP; it receives 100.64.16.9"
  }
}

Código	Significado
200	Já existe um serviço com este ref; ele é retornado com "existing": true.
400	Um campo está ausente ou é inválido (error diz qual).
404	OLT ou plano desconhecido, ou o serial não está na tabela autofind da OLT.
409	O serial (ou o id de ONT dessa porta) já pertence a um serviço — retornado em service — ou a porta não pode ser usada (error diz por quê).
502	A OLT recusou; olt_raw traz as últimas linhas da resposta dela. Nada foi criado no roteador.
500	A parte da OLT deu certo, a parte do roteador falhou: o serviço existe no estado error; tente novamente com POST /services/{id} {"retry": true}.
507	Não sobrou endereço para esta ONT na sua porta.

POST /services/{id}

Altera o roteador e a OLT

Atualiza o registro; uma mudança de plano move a ONT para a nova velocidade na OLT (alguns segundos de interrupção).

Altera um ou mais campos. PUT é aceito da mesma forma. O olt da resposta diz se a parte da OLT de uma mudança de plano deu certo.

Nome	Em	Tipo	Observações
id	path	string	Id, ref, serial, contrato, endereço ou interface.
plan or down_mbps + up_mbps	body	string / integer	Novo plano (criado a partir das velocidades se não existir).
name, contract, comment, ref	body	string	Novos valores.
expires	body	date	Nova data de término, ou never.
retry	body	boolean	Executa de novo a parte do roteador (após um 500 na criação).

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"plan":"plan_300_300"}' http://ROUTER-IP:8880/services/svc_1a2b3c4d

{
  "ok": true,
  "code": 200,
  "message": "Service updated",
  "changed": ["plan"],
  "olt": "ONT moved to the new plan on the OLT",
  "service": { "id": "svc_1a2b3c4d", "plan": "plan_300_300", "state": "active" }
}

400 quando nada é informado para alterar; 404 para um serviço desconhecido.

POST /services/{id}/suspend

Altera o roteador e a OLT

Desativa a ONT na OLT e bloqueia o endereço do assinante no roteador.

A etapa na OLT pode ser desligada na configuração do roteador, deixando apenas o bloqueio no roteador.

Nome	Em	Tipo	Observações
id	path	string	Id, ref, serial, contrato, endereço ou interface.

curl -X POST -H "X-API-Key: YOUR_API_KEY" http://ROUTER-IP:8880/services/svc_1a2b3c4d/suspend

{
  "ok": true,
  "code": 200,
  "message": "Service suspended",
  "olt": "ONT deactivated on the OLT",
  "service": { "id": "svc_1a2b3c4d", "state": "suspended" }
}

502 quando a parte do roteador foi feita, mas a OLT não acompanhou (a resposta informa isso): tente novamente.

POST /services/{id}/resume

Altera o roteador e a OLT

Ativa a ONT na OLT e remove o bloqueio no roteador.

Mesmos parâmetros e respostas que a suspensão ("message": "Service resumed", "olt": "ONT activated on the OLT").

curl -X POST -H "X-API-Key: YOUR_API_KEY" http://ROUTER-IP:8880/services/svc_1a2b3c4d/resume

DELETE /services/{id}

Altera o roteador e a OLT

Remove o serviço do roteador e, a menos que keep_ont, a ONT e seus service-ports da OLT.

O registro é removido no roteador mesmo quando a etapa na OLT falha (o olt da resposta informa isso). A interface da porta permanece para os outros assinantes nela.

Nome	Em	Tipo	Observações
id	path	string	Id, ref, serial, contrato, endereço ou interface.
keep_ont	query or body	boolean	Mantém a ONT registrada na OLT.

curl -X DELETE -H "X-API-Key: YOUR_API_KEY" "http://ROUTER-IP:8880/services/svc_1a2b3c4d?keep_ont=1"

{
  "ok": true,
  "code": 200,
  "message": "Service deleted",
  "olt": null,
  "service": { "id": "svc_1a2b3c4d", "name": "Customer name", "state": "active" }
}

POST /services/{id}/migrate

Altera o roteador e a OLT

Move o serviço para a VLAN e o bloco de endereços da sua porta PON: o endereço do assinante muda.

Uso do operador ao renumerar (não faz parte do fluxo da cobrança): move um serviço criado com uma numeração antiga para a C-VLAN e o endereço da sua porta, recriando o service-port na OLT sem mexer na ONU. O id permanece; a ONU recebe o novo endereço no próximo DHCP. A antiga interface por assinante é removida quando nada mais a usa.

Nome	Em	Tipo	Observações
id	path	string	Id, ref, serial, contrato, endereço ou interface.

curl -X POST -H "X-API-Key: YOUR_API_KEY" http://ROUTER-IP:8880/services/svc_1a2b3c4d/migrate

{
  "ok": true,
  "code": 200,
  "message": "Service moved to its PON port",
  "olt": "service-port recreated: user-vlan 116 -> S-VLAN 500 / C-VLAN 116",
  "service": { "id": "svc_1a2b3c4d", "iface": "v500.116", "state": "active" },
  "note": "the ONU keeps its settings; it takes the new address at its next DHCP (reboot the ONT to make that now)"
}

Responde "message": "Already on its port" quando não há nada a mover; 409 quando a porta, o endereço ou a C-VLAN está ocupado por outra coisa; 502 quando a OLT recusa (parte do roteador inalterada).

Equivalentes na API de ações

Todos 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=service-list	[state], [olt], [q], [fast=1]	GET /services
action=service-get	id	GET /services/{id}
action=service-unregistered	[olt]	GET /services/unregistered
action=service-add	sn, olt, pon, plan ou down_mbps+up_mbps, name, [ref], [contract], [ipv6], [iptv], [expires]	POST /services
action=service-set	id, [plan], [name], [expires], [retry=1] …	POST /services/{id}
action=service-suspend / action=service-resume	id	POST /services/{id}/suspend / resume
action=service-del	id, [keep_ont=1]	DELETE /services/{id}
action=service-expiry	—	Executa agora a verificação de datas de término (suspende o que expirou, reativa o que foi prorrogado); responde {"changed": [...]}.