Integração com o sistema de cobrança

Um sistema de cobrança (billing) pode comandar o roteador de duas formas:

• A API REST na porta 8880. As integrações novas a usam, com serviços.
• MK-api na porta 8728: um listener da API do MikroTik RouterOS, para um sistema de cobrança que já provisiona roteadores MikroTik e não pode ser alterado. Ele trabalha com clientes baseados em MAC.

Noções básicas da API REST

• Endereço: http://<router>:8880.

• Toda requisição leva a chave de API: o header X-API-Key: <key> (ou ?api_key= em GET). A chave foi exibida pelo instalador e está em /opt/dtvsol/etc/config.php.

• A rede do servidor de cobrança precisa estar na lista de permissões:

  dtvsol protect add XXX.XXX.XXX.25 "billing"

• JSON na entrada, JSON na saída.

• Timeouts: pelo menos 60 segundos por chamada (120 s é confortável). Criar um serviço ocupa uma sessão na OLT (10–40 s), e o roteador fala com uma OLT uma sessão de cada vez. Uma chamada que chega enquanto o roteador está sincronizando ou salvando essa OLT espera até cerca de 25 s a mais. Isso não é um erro: não repita a chamada antes da hora.

O fluxo de provisionamento

 billing (support)       billing (technician app)          router                    OLT
 1. create customer
    and contract
                         2. installs the ONU, taps
                            "register ONU"
                            GET /services/unregistered --> asks every OLT ------->  autofind
                            <-- list of ONTs {olt, pon, sn, vendor}
                         3. picks the serial
                            POST /services ------------->  registers the ONT --->  ONT, service-port,
                            {ref, sn, olt, pon, plan}      address, DHCP, CGNAT,   rate limit
                                                           anti-spoofing
                            <-- 201 {service: {id, ipv4}, technician: {user_vlan}}
                         4. shows "ONU WAN = VLAN <user_vlan>, DHCP"
 5. stores service.id
 6. later, by id: plan change, suspend/resume, end date, delete, status, graph

Endpoints

Chamada	Finalidade
GET /services/unregistered[?olt=<name>]	ONTs conectadas e não registradas (cerca de 3 s por OLT)
POST /services	criar um serviço (a chamada única)
GET /services/{id}	status: registro, plano e estado ao vivo
POST /services/{id}	trocar o plano, os nomes, a data de término ou tentar novamente
POST /services/{id}/suspend, /resume	cortar na fibra e no roteador, e restabelecer
DELETE /services/{id}[?keep_ont=1]	removê-lo; o id nunca é reutilizado
GET /services/{id}/graph?period=hour|day|week|month|year	um PNG do tráfego
GET /services?state=…&olt=…&q=…&fast=1	listagem; fast=1 pula a consulta ao vivo

{id} aceita o id do serviço, a sua ref, o número de série, o contrato ou o endereço IPv4.

Campos de POST /services

Campo	Obrigatório	Significado
ref	recomendado	o seu id para este serviço. Torna a chamada idempotente: repeti-la devolve o serviço existente (200, existing: true).
sn	sim	o número de série da ONT, 16 dígitos hexadecimais
olt	quando há mais de uma OLT	o nome da OLT
pon	recomendado	frame/slot/port; procurado no autofind se for omitido
plan, ou down_mbps + up_mbps	sim	um nome de plano, ou velocidades (plan_<down>_<up> é criado se não existir)
name	sim	o cliente, como você quer vê-lo no roteador
contract, comment	não	texto livre, armazenado e pesquisável
user_vlan	não	a VLAN que a ONU envia, quando não é a da porta
ipv6	não	padrão true quando o roteador tem um pool IPv6
iptv	não	a segunda porta Ethernet da ONT na VLAN de IPTV
expires	não	data de término: suspenso nessa data, reativado quando você enviar uma data posterior

Exemplo de requisição:

{ "ref": "C-0001", "sn": "485754430A1B2C3D", "olt": "olt-1", "pon": "0/1/0",
  "down_mbps": 200, "up_mbps": 200, "name": "Example Customer",
  "contract": "C-0001", "ipv6": true, "expires": "2026-12-31" }

Guarde o service.id da resposta e mostre o technician.user_vlan ao técnico. O endereço do assinante (service.ipv4.address) é fixo durante toda a vida do serviço. Veja Serviços para uma resposta completa.

Alterações

{ "plan": "plan_300_300" }
{ "down_mbps": 300, "up_mbps": 300 }
{ "name": "…", "contract": "…", "comment": "…", "ref": "…" }
{ "expires": "2026-11-30" }
{ "expires": "never" }
{ "retry": true }

Uma troca de plano move a ONT para o novo rate limit (alguns segundos de interrupção). O campo olt da resposta diz se o lado da OLT teve sucesso. Um 502 em suspend ou resume significa que o lado do roteador foi feito e a OLT não acompanhou: tente novamente.

Erros

Código	Significado	O que fazer
400	um campo está faltando ou é inválido (error diz qual)	corrija a requisição
404	o número de série não está na tabela de autofind da OLT	a ONU não está conectada, ainda não foi vista ou já está registrada
409	o número de série já pertence a um serviço (devolvido), ou a porta não pode ser usada agora	use o id devolvido; caso contrário, consulte o operador
502	a OLT recusou ou não pôde ser alcançada	tente mais tarde; nada foi criado
500	o lado da OLT funcionou, o lado do roteador falhou	o serviço fica no estado error: {"retry": true} depois de corrigida a causa
507	não sobrou endereço nessa porta	consulte o operador

Observações

• Sempre envie ref. Assim, uma nova tentativa após um timeout de rede nunca cria um segundo serviço.
• A numeração é derivada, nunca escolhida. Veja Conceitos.
• O endereço MAC não é um dado de entrada. Se o cliente trocar o roteador dele, o serviço continua funcionando com o mesmo endereço e o mesmo id.

MK-api (compatível com MikroTik)

O MK-api escuta na porta TCP 8728 e fala o suficiente da API do MikroTik RouterOS para que um sistema de cobrança pense que está falando com um MikroTik. Ele transforma os comandos do sistema de cobrança em chamadas à API do próprio roteador.

Escopo: somente DHCP/IPoE.

Comando do billing	O que o roteador faz
/ip/dhcp-server/lease/add	cria um cliente (MAC + endereço)
/ip/dhcp-server/lease/set (disabled)	suspende ou reativa o cliente
/ip/dhcp-server/lease/remove	apaga o cliente
/ip/dhcp-server/lease/print	lista os clientes
/queue/simple/… ou um rate-limit de lease	define a velocidade: um plano mk_<down>m_<up>m é criado para isso
/ppp/… (PPPoE)	recusado

Configure-o:

dtvsol mkapi                                          # status
dtvsol mkapi set user billing password '<password>'
dtvsol mkapi set identity router-1

identity, model <m> e version <v> definem o que o roteador responde quando o sistema de cobrança pergunta com qual MikroTik está falando. port <n> muda a porta.

Cuidado

O instalador dá ao MK-api uma senha aleatória própria e a mostra uma vez no final da instalação. Se preferir, defina a sua antes de conectar um sistema de cobrança.

O endereço do sistema de cobrança precisa estar na lista de permissões (dtvsol protect add). O listener roda como dtvsol-mkapi.service.