Serviços

Um serviço é um cliente em uma ONT, com uma velocidade, um endereço fixo e um id permanente. Uma única chamada registra a ONT na OLT dela (perfis, rate limit, service-port QinQ) e configura o lado do roteador: a interface VLAN da porta, DHCP com Option 82, IPv6 e um prefixo delegado, CGNAT, contabilização e anti-spoofing. Leia primeiro os Conceitos para entender a numeração.

Antes do primeiro serviço

• A OLT está cadastrada com a S-VLAN deste roteador: dtvsol olt add … --svlan <n>. Veja OLTs.
• A interface da S-VLAN vlan<svlan> existe na porta ou no bond voltado para a OLT.
• Os pools de endereços dos serviços estão definidos em /opt/dtvsol/etc/config.php: svc_ipv4_pool (por exemplo 100.64.0.0/10) e, para IPv6, svc_ipv6_pool e svc_pd_pool. Sem um pool IPv6, os serviços são somente IPv4.

O fluxo do técnico

1. O técnico conecta e liga a ONU.

2. Ele lista as ONTs que estão conectadas e ainda não registradas:

   dtvsol service unregistered

3. Ele escolhe o número de série e cria o serviço:

   dtvsol service add 485754430A1B2C3D --name "Example Customer" --plan plan_200_200 \
       --olt olt-1 --pon 0/1/0 --ref C-0001 --contract C-0001

4. O comando mostra a VLAN a configurar na WAN da ONU, com DHCP. A ONU então recebe o seu endereço fixo.

Referência da CLI

dtvsol service unregistered [--olt n]
dtvsol service add <sn> --name "..." (--plan p | --down d --up u) [--olt n] [--pon f/s/p]
                  [--user-vlan v] [--ref r] [--contract c] [--expires YYYY-MM-DD|never]
                  [--comment ...] [--iptv] [--no-ipv6]
dtvsol service list [--state active|suspended|error] [--olt n] [-q text] [--fast] [--json]
dtvsol service get <id>
dtvsol service set <id> [--plan p | --down d --up u] [--name] [--contract] [--expires] [--comment] [--retry]
dtvsol service suspend <id> | resume <id>
dtvsol service del <id> [--keep-ont]
dtvsol service graph <id> [hour|day|week|month|year] [out.png] [--olt|--errors]

Observações:

• <id> pode ser o id do serviço, a sua ref, o número de série da ONT, o contrato, o endereço ou a interface.
• --down/--up em vez de --plan cria plan_<down>_<up> se ele não existir.
• --pon pode ser omitido: o roteador encontra o número de série na tabela de autofind da OLT.
• --user-vlan é para uma ONU que já envia outra VLAN (por exemplo, ao assumir uma rede existente). A OLT a traduz; a ONU não é mexida.
• --ref torna a chamada idempotente: a mesma ref devolve o mesmo serviço.
• --iptv coloca a segunda porta Ethernet da ONT na VLAN de IPTV da OLT.
• Uma troca de plano move a ONT para o novo rate limit na OLT. O cliente percebe alguns segundos de interrupção.
• Suspender desativa a ONT na OLT e bloqueia o endereço no roteador. Com uma data de término (--expires), o roteador suspende sozinho nessa data e reativa quando você envia uma data posterior.
• service graph --olt mostra o tráfego da ONT como a OLT o contabiliza; --errors, os seus erros de fibra (BIP, FEC).

Um assinante cuja ONT foi provisionada à mão ainda pode ser registrado:

dtvsol service add none --svlan 1000 --pon 0/1/0 --ont-id 7 --name "Example Customer" --plan plan_100_50

A API

As mesmas operações estão disponíveis via HTTP na porta 8880. Toda requisição leva a chave de API no header X-API-Key. A rede de quem chama precisa estar na lista de permissões (dtvsol protect add).

Dê a cada chamada pelo menos 60 segundos. Criar um serviço ocupa uma sessão na OLT (10–40 s) e pode esperar pelo trabalho do próprio roteador na OLT.

ONTs não registradas:

curl -s -H "X-API-Key: $KEY" "http://XXX.XXX.XXX.10:8880/services/unregistered?olt=olt-1"

{ "ok": true, "count": 1,
  "onts": [ { "olt": "olt-1", "pon": "0/1/0", "sn": "485754430A1B2C3D",
              "vendor": "HWTC", "seen_at": "2026-09-25 10:12:03+00:00",
              "svlan": 1000, "cvlan": 116 } ],
  "errors": {} }

Criar um serviço:

curl -s -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  "http://XXX.XXX.XXX.10:8880/services" -d '{
    "ref": "C-0001", "sn": "485754430A1B2C3D", "olt": "olt-1", "pon": "0/1/0",
    "down_mbps": 200, "up_mbps": 200, "name": "Example Customer",
    "ipv6": true, "expires": "2026-12-31" }'

A resposta (201) traz o serviço. Guarde o service.id. Mostre o technician.user_vlan ao técnico:

{ "ok": true, "message": "Service created",
  "service": {
    "id": "svc_d320fcbd", "ref": "C-0001", "olt": "olt-1", "pon": "0/1/0", "ont_id": 7,
    "svlan": 1000, "cvlan": 116, "user_vlan": 116, "iface": "v1000.116",
    "ipv4": { "network": "100.64.16.0/24", "gateway": "100.64.16.1", "address": "100.64.16.9" },
    "ipv6": { "link": "XXXX:XXXX:0:116::/64", "pd": "XXXX:XXXX:1:1600::/56" },
    "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" } }

Outras chamadas:

Chamada	O que faz
GET /services/{id}	o registro, mais o estado ao vivo: link, online, MAC visto, lease DHCP
POST /services/{id}	altera plan (ou down_mbps/up_mbps), name, contract, comment, expires, ou {"retry": true}
POST /services/{id}/suspend, /resume	corta e restabelece
DELETE /services/{id}	remove-o de todos os lugares (?keep_ont=1 deixa a ONT registrada)
GET /services/{id}/graph?period=day	um PNG do tráfego
GET /services?state=active&olt=olt-1&q=text&fast=1	a listagem

Códigos de erro a tratar: 400 campo inválido, 404 número de série fora do autofind, 409 o número de série já pertence a um serviço (a resposta o traz), 502 a OLT recusou ou não pôde ser alcançada (nada foi criado), 500 o lado da OLT funcionou, mas o lado do roteador falhou (o serviço existe no estado error: corrija a causa e depois {"retry": true}), 507 não sobrou endereço nessa porta.

O guia completo de integração para as equipes de cobrança está em Integração com o sistema de cobrança.