Integração com o Lumina ACS

Tudo o que um ERP, um app de técnicos ou um sistema do provedor precisa para falar com o Lumina ACS: a API REST, a NBI compatível com o GenieACS, o conector de ERP e os webhooks.

Os quatro caminhos

O Lumina conversa com o ERP do provedor por quatro caminhos independentes, que podem ser combinados. Em dois deles o ERP chama o Lumina; nos outros dois o Lumina vai até o ERP.

Combinação típica: o conector de ERP ligado (o atendimento vê o cliente na CPE e o vínculo grava PPPoE e Wi-Fi do contrato), a NBI apontada no módulo de ACS do próprio ERP (o atendente reinicia e consulta sem sair do ERP) e webhooks para quedas, resets de fábrica e tarefas. A API REST entra quando o provedor quer automações próprias ou um app de instalação.

Por onde começar

Cinco regras que evitam a maioria dos problemas

1. Ações em CPE são assíncronas. A resposta 202 quer dizer “aceito”, não “feito”. Veja Tarefas e o modelo assíncrono.
2. Provisione pela configuração do assinante (PUT …/config ou o vínculo com o ERP), não por set_values solto: só ela volta sozinha depois de um reset de fábrica.
3. Não faça polling de CPE. Assine webhooks; o Lumina já sabe quando algo muda.
4. Use a chave da CPE exatamente como a API devolve, codificada na URL. Nunca monte a chave no ERP a partir de pedaços.
5. Trate null. Nem toda CPE expõe RX óptico, CPU, memória ou clientes Wi-Fi. Ausência não é zero.

Primeiros passos

Da chave criada à primeira ação numa CPE, em cinco minutos.

1. Crie uma chave de API

No console, um administrador vai em Integrações → Chaves de API → Nova chave, dá um nome (por exemplo “ERP — testes”), marca os escopos devices:read, devices:safe-ops e tasks:read e salva. A chave (lmk_ seguido de 32 caracteres) aparece uma única vez: copie-a agora. Detalhes em Chaves de API e escopos.

2. Prepare as variáveis

Todos os exemplos de curl desta wiki assumem estas três variáveis de shell (e jq onde aparece):

ACS=https://acs.provedor.com.br
KEY="Authorization: Bearer lmk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
CPE=40ED00-XX230v-2249B1000123

ACS é o mesmo endereço do console. No ACS hospedado pela Lumina, é o subdomínio do provedor.

3. Três chamadas

# 1 — a chave funciona? (devices:read)
curl -s -H "$KEY" "$ACS/api/v1/dashboard/summary"

# 2 — achar a CPE do cliente pelo login PPPoE
curl -sG -H "$KEY" "$ACS/api/v1/devices" --data-urlencode "pppoe=cliente@isp" | jq -r '.items[0].key'

# 3 — reiniciar (devices:safe-ops)
curl -s -X POST -H "$KEY" "$ACS/api/v1/devices/$CPE/actions/reboot"
# 202 {"id":"b32fqgm2ejgjkahhetfa","status":"pending","connection_request":true}

4. Acompanhe a tarefa

curl -s -H "$KEY" "$ACS/api/v1/tasks/b32fqgm2ejgjkahhetfa" | jq -r .status
# pending → running → rebooting → done

Em produção, troque a consulta pelo webhook task.completed/task.failed. Se a CPE estiver inalcançável, a tarefa fica pending e executa no próximo Inform: não é erro.

Próximos passos

• Entender o ciclo de uma ação: Tarefas e o modelo assíncrono.
• Gravar PPPoE e Wi-Fi do cliente: Configuração do assinante.
• Receber eventos em vez de consultar: Webhooks.

Chaves de API e escopos

Toda integração usa uma chave de API do tenant, com escopos, lista de IPs, limite por minuto e validade.

Criar uma chave

No console, em Integrações → Chaves de API → Nova chave, por um usuário administrador. Também por POST /api/v1/api-keys com a sessão desse usuário (nunca com outra chave). O formato é lmk_ seguido de 32 caracteres. O Lumina guarda só o hash e depois mostra apenas o prefixo (os 12 primeiros caracteres).

{ "name": "ERP — módulo de ACS",
  "scopes": ["devices:read","devices:safe-ops","devices:write","tasks:read","firmware:write"],
  "ip_allowlist": ["200.150.10.0/24"],
  "rate_per_minute": 600,
  "expires_at": null }

→ 201
{ "item": { "id":"…", "name":"ERP — módulo de ACS", "prefix":"lmk_2f9cq7ab", "scopes":[…],
            "ip_allowlist":[…], "rate_per_minute":600, "active":true, "expires_at":null, … },
  "key": "lmk_2f9c…"   // aparece só aqui }

name e ao menos um escopo são obrigatórios. Escopo fora da lista, IP/CIDR malformado ou rate_per_minute fora de 0–100 000 dão 400. GET /api/v1/api-keys devolve {"items":[…],"scopes":[…]} com last_used_at, last_used_ip e revoked_at de cada chave. DELETE /api/v1/api-keys/{id} revoga na hora.

Como autenticar

# API REST: Bearer
curl -s -H "Authorization: Bearer lmk_2f9c…" "$ACS/api/v1/devices?limit=1"

# NBI: Basic, usuário livre e a chave como senha (Bearer também vale)
curl -sG -u "erp:lmk_2f9c…" "$ACS/nbi/devices" \
  --data-urlencode 'query={"_deviceId._SerialNumber":"2249B1000123"}'

Requisições com chave não passam pela proteção de CSRF (que só vale para o cookie do console) e não precisam de Origin. A lista de IPs de gerência do tenant vale para as sessões do console; uma chave obedece só à própria lista de IPs. As ações feitas com uma chave entram na auditoria e nas tarefas como apikey:<nome da chave>.

GET /api/v1/auth/me confirma a chave (role = api, email = apikey:…, tenant). O campo permissions volta vazio para chaves: os escopos valem, só não aparecem ali.

Escopos concedíveis

Uma chave recebe só os nove escopos abaixo, nunca os de usuários, integrações ou configurações (users:write, integrations:write, settings:write). Escopo ausente devolve 403 com error começando por sem permissão.

Escopos por tipo de integração

Restrições por chave

IPs permitidos

Lista de IPs ou CIDRs. Fora da lista: 403 IP não autorizado para esta chave. Vazia = qualquer IP.

Limite por minuto

Janela deslizante de 60 s por chave (compartilhada entre réplicas quando há cache Valkey). Excedido: 429 limite de requisições da chave excedido com Retry-After em segundos. Aceita de 1 a 100 000; 0 ou ausente vira 600.

Validade

expires_at opcional (RFC 3339). Vencida, a chave responde 401 chave de API inválida.

Teto de tarefas de escrita

Além do limite da chave, cada principal (usuário ou chave) cria no máximo 120 tarefas que gravam ou reiniciam por minuto fora dos lotes (LUMINA_WRITE_TASKS_PER_MINUTE). Excedido: 429 com Retry-After.

Convenções da API

Identificação da CPE, formato, erros, datas, paginação e segredos: o que vale para todas as rotas.

A chave da CPE

Toda CPE é identificada por {OUI}-{ProductClass}-{SerialNumber}, o mesmo formato de id do GenieACS. Por isso o id que o ERP já guardava de um GenieACS continua valendo. Exemplo: 40ED00-XX230v-2249B1000123. Onde esta wiki escreve {key}, é esse valor.

Regras gerais

Paginação na prática

URL="$ACS/api/v1/devices?limit=500"; CUR=""
while :; do
  PAGE=$(curl -s -H "$KEY" "$URL${CUR:+&cursor=$CUR}")
  echo "$PAGE" | jq -c '.items[] | {key, serial_number, pppoe_username, status}'
  CUR=$(echo "$PAGE" | jq -r '.next_cursor // empty')
  [ -n "$CUR" ] || break
done

O cursor é opaco: não o interprete nem o monte. Ele só vale com os mesmos filtros da chamada que o devolveu.

Tarefas e o modelo assíncrono

Por que uma ação responde 202, o que acontece até a CPE executar e como acompanhar.

Por que é assíncrono

O TR-069 é iniciado pela CPE: o ACS só fala com ela quando ela abre uma sessão (o Inform). Quando você pede uma ação, o Lumina:

1. cria uma tarefa;
2. dispara um Connection Request, por HTTP na porta da CPE ou, com o servidor STUN do Lumina ligado, por UDP para a CPE atrás de NAT;
3. responde na hora, sem esperar a CPE.

HTTP/1.1 202 Accepted
{ "id": "b32fqgm2ejgjkahhetfa", "status": "pending", "connection_request": true }

Se a CPE estiver inalcançável (CGNAT, porta bloqueada, desligada), a tarefa fica pendente e executa no próximo Inform periódico. Isso não é erro.

Estados de uma tarefa

Como acompanhar

# GET $ACS/api/v1/tasks/b32fqgm2ejgjkahhetfa
{ "id": "b32fqgm2ejgjkahhetfa", "kind": "set_values", "status": "done", "attempts": 1,
  "payload": { "values": [ { "name":"Device.WiFi.AccessPoint.3.Security.KeyPassphrase", "value":"••••••••", … } ] },
  "result": { "status": "done", "set_status": 0 },
  "created_by": "apikey:erp", "created_at": "2026-09-17T10:31:07-03:00",
  "started_at": "2026-09-17T10:31:09-03:00", "finished_at": "2026-09-17T10:31:09-03:00",
  "device_key": "40ED00-XX230v-2249B1000123", "serial_number": "2249B1000123" }

Toda tarefa serializada, em qualquer listagem, traz serial_number ao lado de device_key: é o número que o suporte e a etiqueta da ONU usam. set_status: 1 quer dizer que a CPE aplica depois da sessão; o Lumina relê os valores em alguns segundos.

Connection Request sem tarefa

POST …/actions/connection-request só acorda a CPE e responde na hora, sem criar tarefa. Ver Ações.

Listar e buscar CPEs

A lista com filtros, o item da lista, o detalhe de uma CPE, a exportação CSV e os menus de filtro.

curl -sG -H "$KEY" "$ACS/api/v1/devices" --data-urlencode "pppoe=cliente@isp"

{ "items": [ {
    "key": "40ED00-XX230v-2249B1000123",
    "manufacturer": "TP-Link", "product_class": "XX230v", "model_name": "XX230v",
    "serial_number": "2249B1000123", "software_version": "0.9.0 0.9.1 v6034.0 Build 240522 Rel.61823n",
    "status": "online", "pppoe_username": "cliente@isp", "wan_ip": "100.64.10.20",
    "wan_mac": "40:ED:00:11:22:33", "lan_mac": "40:ED:00:11:22:34",
    "wifi_ssid_24": "Casa", "optical_rx_dbm": -19.4,
    "uptime_seconds": 412233, "hosts_count": 7,
    "last_inform_at": "2026-09-17T10:31:07-03:00", "first_seen_at": "2026-08-11T09:02:44-03:00",
    "tags": ["pop-centro"],
    "hosts_active": 5, "hosts_read_at": "2026-09-17T10:29:41-03:00", "default_login": false } ],
  "next_cursor": "eyJrIjoi…", "total": 8342 }

• lan_mac é o MAC base da CPE (o MAC que costuma ir para o cadastro do ERP); wan_mac é o da interface voltada para a operadora.
• Hosts conectados são hosts_active: os ativos da última leitura da tabela de hosts, com a hora dessa leitura em hosts_read_at. Os dois vêm null enquanto a tabela nunca foi lida, e ela só é lida sob demanda (ver Hosts e leituras sob demanda).
• hosts_count é o HostNumberOfEntries que a CPE informa a cada sessão. Ele conta toda entrada da tabela, inclusive a concessão DHCP de quem já foi embora, e por isso não serve como “conectados”.

Detalhe de uma CPE

Acrescenta ao item da lista:

homolog_seal é {status, approved_at?}, omitido quando o par fabricante/modelo/hardware/firmware não tem selo no catálogo publicado pela Lumina; status é homologated ou community. A homologação de firmware é feita pela Lumina, fora deste ACS: não há rota para disparar ou consultar a bateria. 404 CPE não encontrada para chave desconhecida.

Exportação CSV

Os mesmos filtros de GET /devices, todas as páginas, em CSV com separador ; e BOM (abre direto no Excel). Arquivo cpes-AAAA-MM-DD.csv com as colunas:

chave;serial;fabricante;modelo;firmware;status;pppoe;ip_wan;mac;mac_wan;ssid_2g;rx_optico_dbm;uptime_s;hosts_na_tabela_da_cpe;ultimo_inform;primeiro_contato;tags;hosts_ativos;hosts_lidos_em

curl -s -H "$KEY" -o cpes.csv "$ACS/api/v1/devices/export.csv?status=online,unstable"
tail -n 1 cpes.csv | grep -q '^# EXPORTAÇÃO INCOMPLETA' && echo "arquivo parcial"

Fabricantes, modelos e firmwares do parque

Os fabricantes, modelos e firmwares das CPEs do tenant, cada um com o número de CPEs e sem corte: {"manufacturers":[…],"models":[…],"firmwares":[…]}. Serve para montar os menus de filtro de uma tela do ERP com valores que existem de fato.

Perfis de modelo

Os perfis de modelo carregados e as chaves virtuais que cada um suporta. O perfil é o que traduz “SSID do 5 GHz” nos caminhos TR-069 de cada fabricante; é ele que faz as ações funcionarem sem o ERP conhecer caminhos.

Visões da CPE

Wi-Fi, LAN, NAT, mesh e relógio em formato pronto: cada campo diz o valor, se é gravável, as opções aceitas e o caminho TR-069 de origem. O ERP não precisa conhecer os caminhos do fabricante.

Wi-Fi

{ "bands": [ {
    "band": "5g", "ssid": "Casa 5G",
    "fields": {
      "enabled":   { "value":true, "writable":true, "path":"Device.WiFi.SSID.3.Enable" },
      "channel":   { "value":36, "writable":true, "options":["36","40","44","48"], "path":"Device.WiFi.Radio.2.Channel" },
      "bandwidth": { "value":"80MHz", "writable":true, "options":[…], "labels":{…}, "path":"…" },
      "clients":   { "value":4, "writable":false, "path":"…" } },
    "missing": ["twt","bss_color"],
    "guest": { "ssid":"Casa_Convidados_5G", "enabled":true, "index":4 } } ],
  "shared": { "wps": { "value":false, "writable":true, "path":"…" } },
  "mixed": [], "optimization": { "auto": {…}, "threshold": {…} },
  "scan_supported": true, "updated_at": "…", "profile": "tplink-tr181" }

• Campos por banda: enabled (rede e rádio da banda juntos), standards, channel, auto_channel, bandwidth, bandwidth_current (só leitura), tx_power, hidden, security_mode, encryption, ofdma, twt, bss_color, mu_mimo, beamforming, wmm, wps, isolation, clients (só leitura).
• O que o fabricante ajusta de uma vez para as duas bandas sai em shared; mixed lista os que estão divergentes na CPE.
• O que estiver em missing não existe naquele modelo: esconda na sua tela.
• guest é a rede de convidados da banda, quando o fabricante a marca e o nome já foi lido: ssid, enabled (null se ainda não lido) e index (a instância de Device.WiFi.SSID.{i}). Só leitura; ausente quando não há rede de convidados conhecida (e nunca numa TR-098).
• optimization só aparece quando a CPE expõe a otimização de canais.
• 404 CPE sem perfil de modelo compatível quando não há perfil para o modelo.

Análise de canais

Lê a última varredura concluída (diagnóstico wifi_scan) e devolve, por banda, current, suggested, congested, networks (vizinhas que interferem no canal atual), score_current, score_suggested e candidates, além de task_id, scan_at e networks_total. Sem varredura, bands vem vazio: dispare actions/diagnostic com {"kind":"wifi_scan"} antes.

LAN e DHCP

Mesmo formato do Wi-Fi (fields + missing) com ip, mask, dhcp_enabled, dhcp_min, dhcp_max, dhcp_mask, dhcp_gateway, dhcp_dns, dhcp_lease, os campos IPv6 (ipv6_enabled, ipv6_address, ipv6_prefix, ipv6_prefix_origin, ipv6_addr_type, ipv6_prefix_len, ipv6_prefix_type, ipv6_parent_prefix, dhcp6_enabled, dhcp6_iana, dhcp6_dns, ra_enabled, ra_managed, ra_other, ra_rdnss, ra_rdnss_servers) e os derivados mac, ipv6_addr_mode (radvd/dhcpv6) e ipv6_wan. Mais a tabela de reservas:

{ "fields": { "ip":{"value":"192.168.0.1","writable":true,"path":"…"}, "dhcp_lease":{"value":86400,…} },
  "missing": [],
  "static_leases": [ { "index":1, "path":"…", "mac":"AA:BB:CC:44:55:66", "ip":"192.168.0.31",
                       "enabled":true, "name":"TV-Sala" } ],
  "static_supported": true, "static_max": 16, "updated_at": "…", "profile": "tplink-tr181" }

NAT

supported, virtual_servers[] (index, enabled, status, name, interface, external_port, external_end, internal_ip, internal_port, internal_end, protocol), vs_writable, dmz e upnp (com as entradas ativas; null quando a CPE não expõe esses objetos da TP-Link), interfaces e updated_at.

Mesh (EasyMesh)

supported, role (controller, agent ou none), node_count, nodes[] (MAC, modelo, backhaul, rádios, APs, clientes e, quando o nó também é uma CPE registrada, peer), para um agente controller, e o estado da leitura: read_at, pending, read_failed e updated_at (espelha read_at).

• A tabela EasyMesh é lida sob demanda (actions/refresh-mesh) e, na releitura periódica, só quando o contador de nós que a CPE reporta deixa de bater com a tabela guardada.
• role e node_count vêm só dos nós lidos: uma CPE é controller quando a tabela dela tem mais de um nó. Um controlador nunca lido aparece com supported: true, role: "none" e read_at: null.
• Numa CPE agente, Wi-Fi, LAN e NAT são do controlador: as escritas respondem 409 com mesh_agent: true.

Relógio e NTP

supported, synced, status, current_time, enabled, servers[], timezone, timezone_name, writable, updated_at, tenant (o NTP do provedor) e tenant_applied (a CPE já usa exatamente os servidores do provedor). O NTP do provedor é lido em GET /api/v1/settings/ntp (devices:read).

Próximo degrau de firmware

{"next": {"id","source","version","trust"}} ou {"next": null}. É sempre o próximo degrau de um caminho confirmado a partir da versão atual da CPE, nunca um salto nem um downgrade. source é local ou cloud; trust é lumina, community ou confirmed (sucesso confirmado por gente nesta instalação).

Hosts conectados e leituras sob demanda

Hosts, clientes Wi-Fi e a tabela EasyMesh não são relidos na sessão periódica: são lidos quando alguém pede. Como pedir, esperar e ler.

Lista fresca em três passos

ID=$(curl -s -X POST -H "$KEY" "$ACS/api/v1/devices/$CPE/actions/refresh-hosts" | jq -r .id)
# espere o task.completed desse id (webhook) ou sonde GET …/list-reads até lists.hosts.pending == false
curl -s -H "$KEY" "$ACS/api/v1/devices/$CPE/hosts" | jq '{read_at, read_failed, n: (.items | length)}'

refresh-hosts e refresh-mesh

refresh-hosts lê hosts, portas, clientes Wi-Fi (e a tabela EasyMesh, onde há); refresh-mesh lê só a tabela EasyMesh. As duas respondem sempre 202 com o id de uma tarefa, para o ERP acompanhar do mesmo jeito em todos os casos. O campo read diz qual foi:

# leitura enfileirada agora (tarefa nova, Connection Request disparado)
{ "id": "c41kq9d0…", "status": "pending", "read": "queued", "connection_request": true, "lists": ["hosts","wifi_clients"] }

# já havia uma leitura em andamento (outro operador, o console): é a tarefa dela
{ "id": "c41kq9d0…", "status": "pending", "read": "pending" }

# tudo lido há menos de 60 s: nada a pedir; a tarefa devolvida é a dessa leitura, já concluída
{ "id": "c41kq9d0…", "status": "done", "read": "fresh", "read_at": "2026-09-18T10:30:55-03:00" }

# numa CPE agente de mesh, mais a leitura pedida ao controlador, à parte
{ "id": "…", "status": "pending", "read": "queued", "connection_request": true, "lists": ["hosts","wifi_clients"],
  "controller": { "key": "40ED00-XX530v-2249B1000789", "id": "…", "status": "pending", "read": "queued" } }

Uma leitura por vez

Lista lida há menos de 60 s não é pedida de novo (fresh), e lista com tarefa em aberto não ganha outra (pending). Duas telas, dois operadores ou o console e o ERP abrindo a mesma CPE geram uma leitura só. Em queued, lists diz quais listas entraram na tarefa.

A tarefa vence em 20 minutos

Uma CPE sem Connection Request alcançável recebe a leitura no próximo Inform; se ele não vier até lá, a tarefa passa a expired e as visões deixam de mostrar pending.

Caminho morto não trava a lista

Se a CPE recusa o pedido conjunto (9005 num caminho que a build removeu), os caminhos são lidos um a um, a tarefa conclui done com result.note listando os recusados e a lista recusada fica com read_failed: true. Só quando nenhum caminho responde a tarefa é failed.

404

esta CPE não tem lista a ler por TR-069; refresh-mesh numa TR-098 responde esta CPE não expõe EasyMesh por TR-069 (o ramo não existe nesse modelo de dados).

Qualquer get_values concluído cujo pedido inclua a raiz de uma lista (Device.Hosts.Host., Device.WiFi.AccessPoint.{i}.AssociatedDevice., Device.WiFi.MultiAP. e os equivalentes TR-098) também grava a leitura, venha da ação, de uma tarefa crua ou da NBI (refreshObject). A leitura de um item só (Device.Hosts.Host.3.) não conta.

Ler os hosts

Junta a tabela de hosts com os clientes associados do Wi-Fi (sinal, taxa negociada) e as portas Ethernet (velocidade, duplex). É a visão que o atendimento usa para explicar lentidão.

{ "items": [
    { "name":"iPhone", "ip":"192.168.0.14", "mac":"AA:BB:CC:11:22:33", "active":true,
      "type":"wifi", "band":"5", "signal_dbm":-52, "tx_rate_mbps":780, "client_type":"Phone" },
    { "name":"TV-Sala", "ip":"192.168.0.31", "mac":"AA:BB:CC:44:55:66", "active":true,
      "type":"ethernet", "band":"", "port":"LAN2", "speed_mbps":100, "duplex":"Full" } ],
  "ports": [ { "name":"LAN1", "status":"Up", "speed_mbps":1000, "duplex":"Full", "mac":"…", "hosts":1, "wan":false } ],
  "conn_known": true,
  "read_at": "2026-09-18T10:30:55-03:00", "pending": false, "read_failed": false,
  "updated_at": "2026-09-18T10:30:55-03:00" }

• type é wifi, ethernet ou unknown; band é 2.4, 5 ou vazio. Opcionais: lease_s, address_source, client_type, ipv6 e, no controlador EasyMesh, mesh_node/mesh_node_key.
• tx_rate_mbps é a taxa de link negociada, a mesma que a página web da própria CPE mostra.
• conn_known: false: a CPE não publica a tabela de clientes Wi-Fi e não dá para separar cabo de Wi-Fi.
• read_at é a hora real em que a CPE respondeu à leitura das listas (a mais antiga entre hosts, clientes Wi-Fi e, onde há, MultiAP); null quando nunca foram lidas. pending: há leitura em aberto. read_failed: a última tentativa não leu alguma das listas; a lista anterior continua sendo devolvida. updated_at espelha read_at.
• Numa CPE agente de mesh, os clientes deste nó vêm da tabela do controlador, e a leitura dela aparece separada em controller: {"key","read_at","pending","read_failed"}.

Sondar sem carregar a lista

O estado das três listas, sem carregar parâmetro nenhum: é a rota para sondar enquanto se espera uma leitura, no lugar de /hosts e /mesh, que montam a visão inteira a cada chamada.

{ "lists": {
    "hosts":        { "read_at": "2026-09-18T10:30:55-03:00", "pending": false, "read_failed": false },
    "wifi_clients": { "read_at": "2026-09-18T10:30:55-03:00", "pending": false, "read_failed": false },
    "mesh":         { "read_at": null, "pending": true,  "read_failed": false } },
  "controller": { "key": "40ED00-XX530v-2249B1000789", "read_at": "…", "pending": false, "read_failed": false } }

As três chaves de lists vêm sempre. controller só aparece numa CPE agente de mesh. Uma leitura pedida há mais de 20 minutos que a CPE não atendeu deixa de contar como pendente. Sonde a cada poucos segundos, não em laço fechado. A conclusão chega também por SSE (device.lists) e pelos webhooks task.completed/task.failed.

O que continua periódico

hosts_count, wifi_clients_24 e wifi_clients_5 de /devices seguem sendo relidos a cada sessão. Já hosts_active e hosts_read_at são os ativos da última lista lida e a hora dela.

Histórico, eventos e parâmetros

A série histórica da CPE, a linha do tempo de eventos e o modelo de dados cru.

Histórico

6h e 24h (padrão) em amostras brutas; 7d e 30d em agregados por hora; 12m por dia.

{ "range": "24h", "resolution": "raw", "from": "2026-09-16T13:31:07Z",
  "points": [ { "ts":"…", "n":1, "rx":-19.4, "tx":2.1, "temp":48, "uptime":412233,
                "wifi24":3, "wifi5":4, "cpu":12, "mem_used_pct":61.5 } ] }

Nos agregados aparecem também rx_min, rx_max e cpu_max. wired traz os hosts ativos por cabo, lidos da tabela de hosts quando alguém a abre, e só existe para CPE que informa o tipo de conexão de cada host. Campo ausente num ponto = grandeza não medida. Retenção padrão: 30 dias de amostra bruta e 12 meses de agregado. A série do tenant inteiro está em GET /api/v1/dashboard/history?range=24h|7d|30d.

Eventos da CPE

Mais recentes primeiro, com ?limit= (padrão 100, máximo 500) e ?cursor=.

{ "items": [ { "id": 918273, "at": "2026-09-17T10:31:07-03:00", "kind": "erp_config_rejected",
                "detail": { "erp":"…", "contrato":"1856",
                            "campos":["wifi_password_24: deve ter entre 8 e 63 caracteres imprimíveis"] } } ],
  "total": 1204, "next_cursor": "eyJhdCI6…" }

auth_tolerated não é recusa nem falha de segurança: a senha foi exigida e conferida do mesmo jeito. Serve para o provedor saber quais modelos e versões precisam de correção do fabricante. Não há webhook nem alerta para ele.

Parâmetros crus

Escape para o modelo de dados cru quando a visão pronta não basta. Devolve {"items":[{"path","value","type","writable","updated_at"}]}, até 20 000 parâmetros. Use sempre prefix: a árvore de uma ONU passa de 5 mil parâmetros.

• Um caminho que a CPE passou a recusar sai da releitura automática por 24 h e vem com read_fault_count e read_skip_until. A linha continua no inventário e a escrita continua usando o caminho.
• Três ramos do TR-181 não entram no inventário, em nenhum modelo: Device.WiFi.DataElements., Device.WiFi.AccessPoint.{i}.AC. e Device.WiFi.SSID.{i}.Stats.. Uma tarefa get_values neles funciona e o valor sai no result da tarefa, só não é guardado.

Ações de alto nível

Ações falam o vocabulário do provedor e resolvem sozinhas os caminhos TR-069 de cada fabricante. É o jeito certo de gravar Wi-Fi, PPPoE, LAN e NAT.

Salvo indicação, a ação responde 202 com a tarefa criada e dispara o Connection Request (ver modelo assíncrono).

# trocar o SSID e a senha do 5 GHz
curl -s -X POST -H "$KEY" -H "Content-Type: application/json" \
  -d '{"band":"5g","ssid":"Casa 5G","password":"senha-forte-8"}' \
  "$ACS/api/v1/devices/$CPE/actions/wifi"
# 202 {"id":"b32fqgm2ejgjkahhetfa","status":"pending","connection_request":true}

Todas as ações

Na coluna Escopo, safe-ops é devices:safe-ops e write é devices:write. Ação desconhecida: 404 ação desconhecida.

Validações e garantias

• SSID de 1 a 32 caracteres imprimíveis; senha Wi-Fi de 8 a 63. Alguns modelos têm réguas próprias declaradas no perfil (SSID sem acento, senha com dígito ou símbolo); a mensagem do 400 diz qual.
• Antes de escrever, o Lumina descarta caminhos que aquela CPE não expõe (o SetParameterValues é atômico: um caminho inexistente derrubaria a escrita inteira).
• Depois de escrever, relê os valores para que a próxima leitura já traga o novo.
• Numa CPE agente EasyMesh, wifi, wifi-opt, lan, lan-static, nat e nat-vs respondem 409 com mesh_agent: true: a configuração é do controlador.

Diagnósticos

Ping, traceroute, teste de velocidade e varredura de Wi-Fi executados pela própria CPE.

Diagnóstico é assíncrono em dois tempos: a tarefa passa por diagnosing, a CPE executa e o resultado chega na sessão seguinte.

curl -s -X POST -H "$KEY" -H "Content-Type: application/json" \
  -d '{"kind":"ping","host":"8.8.8.8","size":4}' "$ACS/api/v1/devices/$CPE/actions/diagnostic"

# depois, em GET /api/v1/tasks/{id}: result.summary
{ "state":"Complete", "success":4, "failure":0, "min_ms":11, "avg_ms":13, "max_ms":18 }

Resultado por tipo

Todos trazem state. Um diagnóstico que o modelo de dados da CPE não tem dá 400 na hora. Ausência do objeto na enumeração da CPE não recusa (há firmware que esconde ramos): o pedido segue e, se a CPE não tem mesmo o objeto, responde 9005 e a tarefa fica failed.

Tarefas: criar, consultar, cancelar, repetir

A tarefa crua (RPC CWMP direto), a lista de tarefas do tenant com filtros e contadores, e as operações de cancelar, repetir e encerrar.

Tarefa crua

Para quando você sabe exatamente o que quer ler ou escrever. Prefira as ações sempre que houver uma.

curl -s -X POST -H "$KEY" -H "Content-Type: application/json" -d '{
  "kind": "set_values",
  "values": [ { "name": "Device.DHCPv4.Server.Pool.1.DNSServers", "value": "1.1.1.1,8.8.8.8", "type": "xsd:string" } ],
  "connection_request": true,
  "read_back": ["Device.DHCPv4.Server.Pool.1."]
}' "$ACS/api/v1/devices/$CPE/tasks"

• factory_reset é recusado com 400; outros kinds dão 400 kind inválido.
• download.URL só é aceita quando é uma URL assinada deste ACS (firmware cadastrado, /fs/…) ou de um host liberado na instalação (LUMINA_DOWNLOAD_HOSTS). Para atualizar firmware, prefira actions/firmware, que aplica as regras de segurança por modelo e hardware.
• connection_request vale true quando omitido; false deixa a tarefa esperando o próximo Inform, o modo educado para escrita fora de horário de pico.
• read_back relê subárvores na mesma sessão, depois da escrita.
• Tudo que grava ou reinicia conta no teto de 120 tarefas por minuto do principal: 429 com Retry-After. Para muitas CPEs, use um lote.
• Um preset com set em Device.WiFi.DataElements., AccessPoint.{i}.AC. ou SSID.{i}.Stats. é recusado (400), porque esses ramos não são guardados no inventário. Para gravar ali, use uma tarefa set_values.

Listar as tarefas do tenant

A resposta é {"items":[…],"next_cursor","total"}, com total contando as tarefas que casam com o filtro. GET /api/v1/tasks/{id} devolve uma tarefa.

Os mesmos filtros (menos status, limit e cursor), devolvendo quantas tarefas há em cada status: {"pending":3,"running":0,…,"failed":12,"expired":4}.

Cancelar e repetir

Só a tarefa que ainda não terminou (pending, running, rebooting, diagnosing, transferring). Responde 200 {"id","status":"expired"}; a que já terminou responde 409 com o estado. Tarefa de lote é cancelada sozinha, sem mexer no lote. Só muda o registro no ACS: a CPE que já recebeu o pedido pode ainda executá-lo.

Só a tarefa failed ou expired volta à fila (pending), com resultado zerado; se ela pede Connection Request, ele sai na hora. Responde 200 {"id","status":"pending","connection_request"}. Outro estado: 409. A de escrita passa pelo teto por minuto (429), e a que grava configuração num agente EasyMesh é recusada (409, mesh_agent).

O “escopo de criar aquele tipo” é devices:safe-ops para reboot, refresh, get_values, get_names e diagnostic, e devices:write para os demais. Sem ele: 403 sem permissão para <kind>.

Encerrar um download preso

Encerra o download desta CPE que ficou em transferring porque a CPE não confirmou: a tarefa vira failed com "encerrada por <quem>". Outro tipo ou outro estado: 409; tarefa de outra CPE: 404. Só muda o registro: se a CPE voltar noutra versão, o registro da atualização passa a aplicado.

Configuração do assinante e instalação

O login e a senha PPPoE e o Wi-Fi do cliente, guardados no Lumina para cada CPE. O ACS grava esses valores a pedido e regrava sozinho quando a CPE volta de um reset de fábrica.

Três fontes escrevem no mesmo lugar: o vínculo com o contrato do ERP, o PUT …/config e as ações wan e wifi (SSID e senha). As senhas ficam cifradas no banco.

O fluxo de instalação

1. A CPE sai do preset do fabricante com o login PPPoE padrão do provedor e aparece no ACS. Os logins padrão são cadastrados no console (Configurações → Instalação) e lidos por GET /api/v1/settings/installation (devices:read): {"default_logins":["provedor@provedor"]}.
2. O app ou o ERP acha a CPE: GET /api/v1/devices?default_login=1&status=online, ou ?q= com o MAC ou o serial da etiqueta.
3. Grava o cliente: com conector de ERP, POST …/subscriber (o contrato vira a configuração); sem conector, PUT …/config com os valores do seu ERP.
4. Acompanha a tarefa apply_config pelo task_id da resposta ou pelos webhooks.

Gravar a configuração

curl -s -X PUT -H "$KEY" -H "Content-Type: application/json" -d '{
  "pppoe_username": "cliente@isp", "pppoe_password": "s3nh4",
  "wifi_ssid_24": "Casa", "wifi_password_24": "senha2g24",
  "wifi_ssid_5": "Casa 5G", "wifi_password_5": "senha5g24",
  "apply": true, "link_login": "cliente@isp"
}' "$ACS/api/v1/devices/$CPE/config"

→ 200
{ "saved": true, "default_login": true, "erp": "…", "linked": true, "task_id": "b32fqgm2ejgjkahhetfa",
  "config": { "pppoe_username":"cliente@isp", "pppoe_password":"••••••••",
              "wifi_ssid_24":"Casa", "wifi_password_24":"••••••••",
              "wifi_ssid_5":"Casa 5G", "wifi_password_5":"••••••••",
              "source":"manual", "updated_by":"apikey:app-tecnicos", "updated_at":"…",
              "applied_at":null, "reapply_count":0, "last_reapply_at":null } }

Semântica: campo ausente mantém o que estava salvo; senha igual a •••••••• também mantém; string vazia apaga. Pelo menos um campo precisa ficar preenchido.

Erros: 400 com a mensagem do campo; 409 em CPE agente EasyMesh; 429 quando a configuração foi salva mas o teto de tarefas de escrita estourou (repita com {"apply":true} depois do Retry-After); 500 configuração salva, mas a tarefa de gravação falhou.

Na CPE: a tarefa grava o Wi-Fi primeiro e o PPPoE depois, em dois SetParameterValues, porque a troca do PPPoE derruba a conexão. result.summary traz {"params","reapply"}; depois de done, config.applied_at fica preenchido.

Ler e apagar

{"saved":false,"default_login":…} ou {"saved":true,"config":{…},"default_login":…,"erp":"…"}, com as senhas mascaradas. erp só aparece quando há conector de ERP ativo e traz o identificador dele (o mesmo kind de GET /api/v1/integrations/erp/providers). O mesmo campo aparece nas respostas de PUT …/config e de …/subscriber. Em config.source vem manual (gravada pela API ou pelo console) ou o identificador do conector (veio do contrato).

Apaga a configuração salva sem tocar na CPE: 200 {"ok":true} ou 404 sem configuração salva.

Senhas guardadas

{ "pppoe_password": "s3nh4", "wifi_password_24": "senha2g24", "wifi_password_5": "",
  "sources": { "pppoe_password": "lumina", "wifi_password_24": "erp" } }

Devolve em claro as senhas que o Lumina conhece. sources diz de onde veio cada uma: lumina (gravada pelo ACS) ou erp (Wi-Fi cadastrado no contrato quando o Lumina ainda não gravou um: é o cadastro, não necessariamente o que está na CPE). Cada leitura entra na auditoria com os campos devolvidos.

Vincular ao contrato do ERP

Com o conector de ERP ativo, uma chamada faz a instalação inteira: o Lumina consulta o contrato, grava o vínculo e guarda como configuração do assinante o login PPPoE, a senha (quando o ERP a expõe) e, com a política “ERP é a fonte”, o SSID e a senha do contrato. Depois decide o que gravar na CPE:

curl -s -X POST -H "$KEY" -H "Content-Type: application/json" \
  -d '{"login":"cliente@isp"}' "$ACS/api/v1/devices/$CPE/subscriber"

{ "linked": true, "saved": true, "default_login": true, "erp": "…",
  "task_id": "b32fqgm2ejgjkahhetfa", "needs_pppoe_password": false,
  "subscriber": { "erp":"…", "contract_id":"1856", "customer_name":"…", "plan":"100MEGA",
                  "status":"Ativo", "login":"cliente@isp", "linked_by":"pppoe", … },
  "config": { "pppoe_username":"cliente@isp", "pppoe_password":"••••••••", "source":"…", … } }

• Corpo: {"login":"…"} busca por PPPoE; {"serial":"…"} pelo serial do serviço; {} usa o login e o serial da própria CPE, conforme o “buscar por” do conector.
• Vincular a um login ou serial diferente do que a CPE apresenta grava a credencial de outro contrato nela e por isso exige devices:write (senão 403).
• 400 com o conector desativado; 404 com a mensagem do ERP quando não há contrato. Se a tarefa não pôde ser criada, a resposta traz apply_error.

O vínculo e a configuração salva. Formato completo em Conector de ERP. Sem vínculo, linked é false e subscriber não vem.

Desfaz o vínculo e apaga a configuração salva: {"ok":true,"config_deleted":true}. A CPE não muda.

Consultar contratos sem gravar

Para um app montar o próprio formulário. Corpo {"login":"…"} ou {"document":"CPF ou CNPJ"}. Resposta {"items":[{"contract_id","customer_name","document","plan","status","login","has_password","wifi":{"ssid_24","channel_24","ssid_5","channel_5"},"address"}]}. Não devolve senha: has_password só diz se o ERP a expõe.

Toda consulta que chega ao ERP vai para a auditoria (subscriber.lookup) com o campo, o valor parcialmente mascarado e o resultado. Limite por principal: 20 consultas por minuto e 300 por hora; acima disso, 429 com Retry-After.

Reset de fábrica, reaplicação e quarentena

O que o Lumina faz sozinho quando uma CPE volta de fábrica, e por que às vezes ele segura a CPE até alguém confirmar.

Reaplicação automática

Quando uma CPE conhecida volta de fábrica, o Lumina registra o evento factory_reset e, se há configuração do assinante salva, regrava PPPoE e Wi-Fi, só o que difere do salvo (evento config_applied com reapply: true; reapply_count e last_reapply_at sobem). Nada a fazer no ERP, que pode acompanhar pelos webhooks device.factory_reset e device.config_applied ou por uma regra de alerta factory_reset.

detail.signal diz o que afirmou o reset:

Quarentena de bootstrap

Quando uma CPE que já tinha recebido credencial de Inform própria volta ao ACS com a senha genérica do provedor e o evento 0 BOOTSTRAP, o Lumina não sabe se foi um reset real ou alguém se passando por ela. A CPE fica em quarentena: segue informando, mas fica sem PPPoE e Wi-Fi do assinante, sem presets e sem tarefas até um operador confirmar.

A quarentena também termina sozinha se a CPE voltar a usar a credencial própria ou concluir um download de firmware enviado pelo ACS.

Etiquetas da CPE

Marcas livres do provedor (POP, bairro, cliente empresarial) que servem de filtro na lista, nos lotes e nas regras de alerta.

curl -s -X PUT -H "$KEY" -H "Content-Type: application/json" \
  -d '{"tags":["pop-centro","empresarial"]}' "$ACS/api/v1/devices/$CPE/tags"
# 200 {"ok":true,"tags":["pop-centro","empresarial"]}

• Substitui o conjunto inteiro. Para acrescentar uma, leia tags de GET /devices/{key}, acrescente e mande tudo. {"tags":[]} limpa.
• Cada etiqueta: 1 a 32 caracteres, só letras minúsculas a-z, dígitos, hífen e sublinhado. No máximo 20 por CPE; repetidas contam uma vez. Fora disso, 400 com o motivo.
• A troca entra na auditoria (device.tags) com o conjunto anterior.
• Filtrar: GET /devices?tag=pop-centro; no lote, "Tag"; na regra de alerta, filter.tag.

Pela NBI

POST/DELETE /nbi/devices/{id}/tags/{tag} acrescentam ou removem uma etiqueta (escopo devices:write ou devices:safe-ops).

Remoção de CPE e licença

A licença conta CPEs que informaram nos últimos 30 dias. Por isso remover tem três modos, e a escolha muda o que acontece com a vaga de licença.

curl -s -X POST -H "$KEY" -H "Content-Type: application/json" \
  -d '{"keys":["40ED00-XX230v-2249B1000123","40ED00-XX530v-2249B1000456"],"mode":"release"}' \
  "$ACS/api/v1/devices/remove"
# 200 {"removed":2,"keys":[…],"mode":"released"}   (404 se nenhuma existir)

Ver e desfazer recusas

Aceita ?mode=release|block, ?q= (serial, chave, PPPoE, modelo) e ?limit= (até 500). Devolve {"items":[…],"counts":{…},"total":N}, cada item com removed_by, removed_at, last_seen_at e ignored_count (Informs ignorados desde a remoção).

Na resposta e nos registros o modo aparece como removed, released ou blocked. Toda remoção pela API REST ou pelo console emite o webhook device.removed com mode, serial, modelo, PPPoE e quem removeu: bom gancho para o ERP registrar a devolução do equipamento. A remoção pela NBI só apaga o registro e não emite esse webhook.

Ações em massa (lotes)

Um lote aplica a mesma tarefa a todas as CPEs que casam com um filtro, com taxa controlada e salvaguardas obrigatórias no servidor.

As salvaguardas

Quantidade reconferida

O corpo precisa trazer confirm_count igual ao número de CPEs que o filtro alcança agora. Sem ele, ou com número diferente: 409 com {"error":"confirme digitando a quantidade de CPEs do filtro: N","count":N}. Mostre N a quem pediu e só então reenvie.

Janela de arrependimento

O lote nasce pending e só começa depois de start_at: 5 minutos para o que grava ou reinicia, 1 minuto para leituras. Dá para cancelar nesse intervalo.

Primeira onda

Lotes que gravam ou reiniciam com mais de 10 CPEs rodam primeiro em 10 e param em canary até alguém chamar POST /api/v1/batches/{id}/continue (204).

Tetos

Lotes que gravam ou reiniciam aceitam no máximo 500 CPEs (422 acima disso: restrinja o filtro) e 300 tarefas por minuto (valor maior é reduzido).

5 min, 10 CPEs e 500 CPEs são os padrões (LUMINA_BULK_GRACE, LUMINA_BULK_CANARY, LUMINA_BULK_MAX_WRITE) e podem ter sido ajustados na instalação. Os valores desta instalação estão em limits de GET /api/v1/firmwares/options e em bulk de GET /api/v1/guides/context.

Criar um lote

# 1ª chamada: sem confirm_count, só para saber quantas CPEs o filtro alcança
curl -s -X POST -H "$KEY" -H "Content-Type: application/json" -d '{
  "name": "DNS novo — POP Centro",
  "filter": { "Tag": "pop-centro", "Status": ["online"] },
  "task": { "kind": "set_values",
            "values": [ { "name": "Device.DHCPv4.Server.Pool.1.DNSServers", "value": "1.1.1.1,8.8.8.8", "type": "xsd:string" } ] },
  "rate_per_minute": 120,
  "connection_request": false
}' "$ACS/api/v1/batches"
# 409 {"error":"confirme digitando a quantidade de CPEs do filtro: 214","count":214}

# 2ª chamada: o mesmo corpo com "confirm_count": 214
# 202 {"id":"…","status":"pending","start_at":"…","canary":10,"confirm_count":214,"rate_per_minute":120,…}

Chaves do filtro

Tarefas aceitas no lote: get_values, get_names, refresh, set_values, add_object, delete_object, reboot e download (mesma restrição de URL da tarefa crua). rate_per_minute padrão 60. 400 nenhuma CPE no filtro quando a contagem é zero.

Acompanhar e controlar

Firmware e campanhas

O repositório de firmware, a atualização de uma CPE com o portão de segurança e as campanhas para o parque.

Repositório

curl -s -X POST -H "$KEY" \
  -F file=@XX530v_v2_0.9.1.bin -F manufacturer=TP-Link -F model=XX530v -F hardware_version="XX530v v2.0" \
  -F version="0.9.1" -F from_versions="0.8.0,0.9.0" -F changelog="Correções de Wi-Fi" \
  "$ACS/api/v1/firmwares"

Campos: file (até 512 MB), manufacturer e model (obrigatórios), hardware_version, version (destino), from_versions (obrigatório: as versões que as CPEs têm hoje, separadas por vírgula, ponto e vírgula ou linha), changelog, notes e blocks_downgrade (true = depois desta versão não se volta atrás). 201 com o firmware; 200 quando o mesmo arquivo (mesmo SHA-256) já existia, com as versões de origem novas acrescentadas. O arquivo é servido às CPEs por URL assinada com prazo de 7 dias (/fs/…), com retomada.

Atualizar uma CPE

Corpo {"firmware_id":"…"} (repositório local) ou {"cloud_id":"…"} (catálogo da Lumina, baixado na hora se preciso). Antes de criar a tarefa o Lumina confere fabricante, modelo, hardware, versão atual, caminho confirmado e travas de downgrade:

Para saber o que aplicar, use GET …/firmware-next. O resultado fica em GET /api/v1/firmwares/updates?device={key}. Download preso em transferring pode ser encerrado (ver Tarefas).

Campanhas

{ "firmware_id": "…", "from_version": "0.9.0", "name": "XX530v → 0.9.1",
  "rate_per_minute": 30, "window_start": "01:00", "window_end": "05:00", "max_failure_pct": 20,
  "confirm_count": 37 }

• A campanha cria um lote de Download cujo filtro é sempre fabricante + modelo + hardware do firmware + from_version: ela nunca alcança uma CPE que a regra de segurança recusaria uma a uma. Por isso o firmware precisa declarar fabricante, modelo e hardware (400 senão).
• Aceita também cloud_id, confirm (mesma regra da atualização unitária) e allow_downgrade (exigido quando a origem é mais nova que o arquivo; sem ele, 409).
• Padrões: 30 por minuto, até 20 % de falhas. Com pelo menos 5 atualizações concluídas e falhas acima do limite, a campanha pausa sozinha. Encerrada ou pausada, emite o webhook campaign.done.
• Salvaguardas de lote em toda campanha: confirm_count obrigatório (400 sem ele; 409 com count se não bate; 422 acima do teto), janela de arrependimento, primeira onda com /batches/{id}/continue e taxa até 300/min. A janela de horário conta a partir do fim da janela de arrependimento.
• Ordem das recusas: firmware, portão (409 de confirm ou de allow_downgrade, 422), campos, e só então a contagem.
• Pela lista de CPEs: com filter (o mesmo de POST /batches), a contagem é a do filtro restrito ao par da campanha. O filtro só restringe (status, busca…): fabricante, modelo, hardware e versão são sempre os do par. Com filter, exige também bulk:write.

GET /api/v1/campaigns (devices:read) lista; POST /api/v1/campaigns/{id}/cancel (204) cancela a campanha e o lote dela.

Prévia da atualização em massa

{ "filter": { "Model": "EG8145V5", "Hardware": "1.0", "Software": "V5R020C10S100", "Status": ["online"] } }

Responde total, groups e combinations (até 50 combinações modelo · hardware · versão, as maiores primeiro) e limits. Só quando há exatamente uma combinação vêm targets: cada firmware cadastrado cuja campanha teria esse par como origem, com o veredito do portão (verdict, reason, downgrade, trust), o selo do destino e o par de origem a mandar de volta em POST /campaigns; e upgrade_unsupported_devices, as CPEs do par cujo perfil não aceita atualização por TR-069.

Alertas, regras e canais

Regras que observam o parque e abrem alertas; para o ERP, o caminho natural é receber alert.opened por webhook e abrir a OS.

Tipos de regra

Criar uma regra

curl -s -X POST -H "$KEY" -H "Content-Type: application/json" -d '{
  "name": "Sinal óptico baixo", "kind": "optical_low", "params": {"dbm": -26},
  "filter": {"tag": "pop-centro"}, "severity": "warning", "channel_ids": [], "cooldown_minutes": 60
}' "$ACS/api/v1/alert-rules"

Campos: name, kind, params, filter (manufacturer, product_class, tag), severity (info, warning padrão, critical), channel_ids (só canais do próprio tenant; id inexistente dá 400), enabled, cooldown_minutes (padrão 60, até 10 080) e notify_resolve. PATCH /alert-rules/{id} altera só o que vier; DELETE apaga a regra e os alertas dela. GET /api/v1/alert-rules (devices:read) lista regras, tipos e severidades aceitos.

Listar e resolver

Resposta {"items","total","next_cursor"}, abertos primeiro, do mais recente ao mais antigo. Cada alerta traz id, rule_id, rule_name, kind, device_key, serial_number, product_class, manufacturer, severity, title, message, detail, opened_at, resolved_at e resolved_by.

A resolução é automática quando a condição cessa, ou manual. As duas emitem o webhook alert.resolved com o mesmo payload (um por alerta, também na resolução em grupo).

Canais de notificação

E-mail, Telegram e webhook simples, ligados às regras por channel_ids. GET /api/v1/channels (devices:read, segredos mascarados); POST, PATCH /{id}, DELETE /{id} (tira o canal das regras) e POST /{id}/test com alerts:write.

Webhooks

O Lumina avisa o ERP quando algo acontece: cada evento vira um POST JSON assinado, entregue por uma fila com retentativa.

Configurados em Integrações → Webhooks por um administrador (ou por POST /api/v1/webhooks com essa sessão; nenhuma chave de API cria webhook) com nome, URL, segredo e a lista de eventos.

Envelope

POST https://erp.provedor.com.br/hooks/lumina
Content-Type: application/json
User-Agent: LuminaACS-Webhook/1
X-Lumina-Event: device.offline
X-Lumina-Delivery: 84213
X-Lumina-Timestamp: 1789651267
X-Lumina-Signature: sha256=6b1f…

{ "id": 84213, "event": "device.offline", "tenant": "default",
  "timestamp": "2026-09-17T13:41:07.52Z",
  "data": { "key":"40ED00-XX230v-2249B1000123", "from":"online", "to":"offline" } }

timestamp é quando o evento aconteceu (UTC); X-Lumina-Timestamp é quando esta tentativa saiu (segundos desde a época). X-Lumina-Signature só vem quando o webhook tem segredo: configure sempre um.

Eventos

• Fechar a OS de device.offline: device.online sai uma vez por volta. Não emitem device.online a CPE nova (o primeiro Inform é device.discovered) e a unlicensed. Com retentativa, um device.online pode chegar antes do device.offline que veio antes dele: compare o timestamp dos dois antes de fechar a OS.
• CPE em quarentena que volta de offline emite device.online com "quarantined": true: quem mandou o Inform pode não ser a CPE. Não trate essa volta como serviço restabelecido sem conferir. Fora da quarentena o campo não vem.
• device.removed traz mode como removed, released ou blocked.
• device.config_applied só traz task quando houve tarefa (a reaplicação após reset não tem) e só traz error quando algo falhou.
• task.* cobre todos os tipos, inclusive apply_config (summary = {"params","reapply"}) e diagnósticos (summary = resultado resumido).

Verificar a assinatura

X-Lumina-Signature é sha256= + HMAC-SHA256 (hex) do segredo sobre X-Lumina-Timestamp + "." + corpo bruto. Compare em tempo constante e rejeite timestamps muito antigos.

# Python
import hmac, hashlib
ts = request.headers["X-Lumina-Timestamp"]
corpo = request.get_data()   # bytes exatamente como chegaram
mac = hmac.new(segredo.encode(), ts.encode() + b"." + corpo, hashlib.sha256)
valido = hmac.compare_digest("sha256=" + mac.hexdigest(), request.headers["X-Lumina-Signature"])

// PHP
$ts    = $_SERVER['HTTP_X_LUMINA_TIMESTAMP'];
$corpo = file_get_contents('php://input');
$mac   = 'sha256=' . hash_hmac('sha256', $ts . '.' . $corpo, $segredo);
$valido = hash_equals($mac, $_SERVER['HTTP_X_LUMINA_SIGNATURE'] ?? '');

// Node.js
const crypto = require('crypto');
const ts = req.get('X-Lumina-Timestamp');
const mac = 'sha256=' + crypto.createHmac('sha256', segredo).update(ts + '.').update(corpoBruto).digest('hex');
const recebido = req.get('X-Lumina-Signature') || '';
const valido = mac.length === recebido.length && crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(recebido));

Entrega e retentativa

• A fila é varrida a cada 3 s. Responda 2xx rápido (o timeout é de 15 s) e processe de forma assíncrona no seu lado.
• Falhas são retentadas com backoff 30 s → 2 min → 10 min → 30 min → 1 h → 3 h → 6 h → 12 h → 24 h, até 10 tentativas.
• 4xx desiste na hora (exceto 408 e 429): um erro de validação seu vira evento perdido. Devolva 5xx se quiser retentativa.
• A URL passa pela política de saída do ACS (destinos de rede interna podem ser recusados ao salvar) e seguem-se no máximo 3 redirecionamentos.
• Entregas podem repetir: use id (o mesmo de X-Lumina-Delivery) como chave de idempotência.
• Um evento só é guardado quando, no momento em que acontece, existe webhook ligado e inscrito nele: webhook criado ou inscrito depois não recebe eventos anteriores. Eventos e entregas são apagados depois de 7 dias.

Configurar pela API

{ "name": "ERP — eventos de CPE", "url": "https://erp.provedor.com.br/hooks/lumina",
  "secret": "troque-por-um-segredo-longo", "enabled": true,
  "events": ["device.offline","device.online","device.factory_reset","task.completed","task.failed","alert.opened"] }

PATCH /api/v1/webhooks/{id} altera só o que vier; secret volta mascarado nas leituras e reenviar •••••••• mantém o atual. Evento fora da lista dá 400 evento desconhecido; GET /api/v1/webhooks devolve {"items":[…],"events":[…]} com a lista válida. GET /api/v1/webhooks/{id}/deliveries mostra o histórico (status pending/sent/failed, attempts, response_code, last_error, next_attempt_at). POST /api/v1/webhooks/{id}/test dispara na hora um webhook.test com id 0: não trate o 0 como chave de idempotência.

Tempo real (SSE)

Um fluxo Server-Sent Events com os acontecimentos do tenant, para telas de atendimento abertas. Para integração servidor a servidor, use webhooks.

# todos os eventos do tenant
curl -sN -H "$KEY" "$ACS/api/v1/events/stream"

# Informs e sessões só desta CPE (o resto continua vindo do tenant inteiro)
curl -sN -H "$KEY" "$ACS/api/v1/events/stream?keys=$CPE"

event: hello
data: {"tenant":"default"}

event: task.update
data: {"type":"task.update","at":"2026-09-17T10:31:09.2-03:00","data":{"id":"b32fqgm2ejgjkahhetfa","status":"done","error":""}}

event: ping
data: {"at":"2026-09-17T10:31:34-03:00","data":{}}

• ?keys=a,b (até 50 chaves) limita device.inform e device.session a essas CPEs; ?keys= vazio não recebe nenhum desses dois; sem o parâmetro, recebe tudo. Os demais eventos vêm sempre do tenant inteiro.
• O corpo de cada evento é {"type","at","data"}. ping chega a cada 25 s; depois de 30 minutos o servidor envia bye e fecha: reconecte (com backoff se cair antes).
• Cliente lento perde eventos (o servidor não enfileira sem limite): ao reconectar, recarregue o estado pela API.
• O fluxo entrega o que é publicado no processo que atende a conexão. Com CWMP, API e worker em processos separados, parte dos eventos não chega a esse processo: mais um motivo para integração servidor a servidor usar webhooks.

NBI compatível com o GenieACS

O Lumina publica em /nbi uma API que imita a NBI do GenieACS 1.2. Um ERP que já tem conector GenieACS funciona apontando para cá, sem desenvolvimento no ERP.

Mesma porta e mesmo domínio do console. Nenhuma linha de código do GenieACS é usada; é uma reimplementação da interface.

Autenticação e escopos

HTTP Basic com usuário livre e a chave lmk_… como senha (a chave no lugar do usuário também é aceita), ou Authorization: Bearer lmk_…. Na NBI, qualquer recusa de credencial (chave inválida, IP fora da lista da chave, limite por minuto excedido) responde 401 com WWW-Authenticate: Basic, e não 403/429 como na API REST. Para o Gerenciador de CPE completo, a chave precisa de devices:read, devices:safe-ops, devices:write e tasks:read, mais firmware:write se o ERP for atualizar firmware.

Rotas

Erros da NBI têm corpo em string JSON (ex.: "sem permissão devices:read"), como no GenieACS.

Consultas suportadas

Subconjunto do dialeto Mongo do GenieACS, com $and e $or em qualquer nível:

Outro campo começado por _ dá 400 campo … não suportado. Os caminhos de serial, versões, fabricante, ProductClass, usuário PPPoE (…WANPPPConnection.1.Username e Device.PPP.Interface.1.Username), IP WAN do TR-098 e SSID 2,4 GHz consultam as colunas do inventário (os mesmos valores de GET /api/v1/devices); os demais consultam os parâmetros lidos da CPE.

# pelo serial da ONU
curl -sG -u "erp:lmk_…" "$ACS/nbi/devices" --data-urlencode 'query={"_deviceId._SerialNumber":"2249B1000123"}'

# pelo login PPPoE (TR-098)
curl -sG -u "erp:lmk_…" "$ACS/nbi/devices" \
  --data-urlencode 'query={"InternetGatewayDevice.WANDevice.1.WANConnectionDevice.1.WANPPPConnection.1.Username":"cliente@isp"}'

# quem não informa desde um instante (ms desde a época), só identificação
curl -sG -u "erp:lmk_…" "$ACS/nbi/devices" \
  --data-urlencode 'query={"_lastInform":{"$lt":1789650000000}}' --data-urlencode 'projection=_id,_lastInform'

Documento devolvido

Cada CPE vira o documento do GenieACS, com a árvore de parâmetros conhecida e folhas {_object,_value,_type,_timestamp,_writable}; objetos têm _object:true. O Lumina acrescenta _status (online/unstable/offline/unlicensed) como extensão. Com projection só de campos _…, a árvore de parâmetros nem é lida.

{ "_id": "40ED00-XX230v-2249B1000123",
  "_deviceId": { "_Manufacturer":"TP-Link", "_OUI":"40ED00",
                 "_ProductClass":"XX230v", "_SerialNumber":"2249B1000123" },
  "_lastInform": "2026-09-17T13:31:07.412Z", "_registered": "2026-08-11T12:02:44Z", "_lastBoot": "…",
  "_tags": ["pop-centro"], "_status": "online",
  "Device": { "_object":true, "WiFi": { "_object":true, "SSID": { "_object":true, "1": { "_object":true,
      "SSID": { "_object":false, "_value":"Casa", "_type":"xsd:string",
                "_writable":true, "_timestamp":"2026-09-17T13:31:07Z" } } } } } }

Tarefas aceitas

Os tipos são inferidos do JSON quando o terceiro elemento não vem: booleano vira xsd:boolean com 1/0, número inteiro vira xsd:int, o resto vira xsd:string. Outro name dá 400 tarefa … não suportada. Toda tarefa criada pela NBI entra na auditoria com a chave usada.

download passa pelo mesmo portão de segurança da ação de firmware. A diferença é que a NBI não tem como assumir risco: o que a ação pediria confirmação (409) e o que ela recusaria (422) viram 400 com o motivo (firmware recusado pelo portão de segurança: …), e nenhuma tarefa é criada. Um caminho que ainda precisa de confirmação tem de sair pelo console ou pela ação REST com confirm.

Semântica do connection_request

Igual à do GenieACS, e é o ponto que o ERP precisa tratar direito. Basta a presença do parâmetro ?connection_request; sem ele, a tarefa entra na fila e a resposta é 202 na hora.

A resposta é {"_id","name","device","timestamp","status"} mais result ou fault.

Módulo de ACS do ERP

Muitos ERPs de provedor já trazem um módulo que fala com um ACS do tipo GenieACS (às vezes chamado de “Gerenciador de CPE” ou “Integração TR-069”). Apontá-lo para o Lumina é uma configuração, não um desenvolvimento.

Configurar no ERP

O nome do menu varia de um ERP para outro (os caminhos conhecidos estão em ERPs: APIs e conectores); os campos são sempre estes:

A URL pronta para colar aparece em nbi_url de GET /api/v1/integrations/erp e na tela Integrações → ERP do console. Se o ERP só aceita usuário e senha separados, informe qualquer usuário e a chave como senha; se aceita token, a chave vai como Bearer.

O que cada função costuma disparar

Caminhos de gravação

Conferir a integração

1. No ERP, use a função de sincronizar ou buscar CPE com um serial conhecido.
2. No Lumina, a chamada aparece na auditoria com o nome da chave (apikey:<nome>).
3. Um 400 campo … não suportado no log quer dizer que o ERP consulta por um campo fora da lista suportada: mande o trecho do log para a equipe do Lumina.

Conector de ERP

O caminho inverso: o Lumina consulta o ERP e guarda, para cada CPE, o contrato do assinante e a configuração do assinante que vem dele.

Serve para o atendimento ver cliente, plano, endereço e POP na tela da CPE, e para gravar na CPE o PPPoE e o Wi-Fi do contrato. O conector é somente leitura no ERP: o Lumina nunca escreve no ERP. Cancelamento, troca de plano e reserva de equipamento continuam sendo feitos no ERP.

Conectores disponíveis

O Lumina traz conectores prontos para os ERPs mais usados por provedores. A lista, e o que cada conector sabe fazer, vem da própria instalação:

{ "default": "…", "items": [
  { "kind": "…", "name": "…", "validated": true, "wifi": true,
    "lookups": ["login","serial","mac","document"],
    "fields": [ { "key":"base_url", "label":"URL do ERP", "type":"url", "required":true, "placeholder":"https://erp.provedor.com.br" },
                { "key":"token", "label":"Token", "type":"password", "required":true }, … ],
    "notes": "Onde criar a credencial no ERP…" },
  … ] }

O que cada ERP pede e o que o conector chama na API dele, sistema por sistema: ERPs: APIs e conectores.

No ERP, antes

1. Crie uma credencial só para o Lumina (token, aplicação ou usuário de API, conforme o ERP; notes diz onde). Só permissão de consulta de clientes, contratos e logins: o Lumina não escreve no ERP.
2. Para o Lumina gravar o PPPoE do contrato, a credencial precisa enxergar a senha do serviço. Sem ela, o vínculo grava o login e pede a senha (needs_pppoe_password).
3. Se a credencial restringe origem, libere o IP de saída do ACS (não o IP de quem acessa o console).

No console

Em Integrações → ERP, o grupo Sistema escolhe o ERP. Um tenant tem um ERP: trocar o sistema com configuração salva de outro pede confirmação e, ao salvar, substitui a configuração anterior (as CPEs já vinculadas continuam vinculadas e passam a ser reconciliadas pelo novo sistema). Abaixo vêm:

• Conexão (os fields do conector): URL e credenciais. Senhas e tokens voltam mascarados.
• Sincronização (igual para todos): Buscar por login PPPoE (padrão), serial ou ambos; Reconciliar a cada N horas; Wi-Fi: “CPE é a fonte” ou “ERP é a fonte”. O que o conector não oferece aparece anotado abaixo do campo.

Testar conexão confere as credenciais que estão na tela, sem salvar. Sincronizar agora faz uma passada na hora (só com a integração ligada e para o sistema salvo).

Pela API

As rotas exigem integrations:write, que nenhuma chave recebe: são para a sessão de um administrador (o próprio console as usa). O conector vai no campo provider (o kind de /providers); sem o campo vale o ERP do tenant; valor fora da lista responde 400 com os aceitos.

{ "provider": "<kind do conector>", "enabled": true,
  "config": { "base_url":"https://erp.provedor.com.br",
              "token":"8f3c…",
              "lookup_by":"both", "resync_hours":"12",
              "rate_per_second":"3", "wifi_policy":"report" } }

Todas as chaves vão como texto no JSON. As demais são as fields do conector escolhido. Gravar gera a auditoria erp.save com o conector no detalhe.

Mensagens de erro

Quando algo falha (Testar, Sincronizar agora, vincular ou consultar contrato), o console e a API mostram a categoria, a mesma frase que fica em “Último erro”, sempre com o nome do ERP configurado:

• contrato não encontrado no <ERP>
• <ERP> recusou as credenciais
• conector do ERP desativado…
• o <ERP> respondeu sem contrato e com uma mensagem de erro (caso típico: credencial sem permissão para a consulta; o texto do ERP fica no log)
• busca por serial não disponível neste ERP
• o motivo da conexão: nome não resolve, conexão recusada, tempo esgotado, TLS, resposta inesperada

O detalhe técnico (URL, status HTTP, corpo da resposta) vai só para o log do servidor: a base_url é escolhida por um administrador do tenant, e devolver ao navegador o que responde nesse endereço transformaria a tela num leitor de serviços internos. A base_url também passa pela política de saída do ACS: destinos que a instalação bloqueia são recusados.

Vínculo com o contrato

Como o Lumina acha o contrato de cada CPE no ERP, o que ele guarda e quando grava alguma coisa na CPE.

Por qual campo o Lumina procura

• pppoe (padrão): o login PPPoE que a própria CPE reportou.
• serial: o serial cadastrado no serviço do ERP, tentando primeiro a chave completa OUI-Modelo-Serial (o id que o ERP guarda quando o serviço foi cadastrado por um ACS do tipo GenieACS) e depois só o serial.
• both: PPPoE e, se não achar, o serial.

ONUs em modo bridge, sem PPPoE na própria CPE, precisam de serial e do serial cadastrado no serviço. Pela API, o vínculo manual busca por login ou serial, e a consulta sem gravar por login ou document (ver consultar contratos).

Escolha do contrato

Quando o ERP devolve vários contratos para a mesma busca, o Lumina escolhe, nesta ordem: (1) o contrato cujo login do serviço bate com o PPPoE (sem diferenciar maiúsculas), (2) o primeiro ativo, (3) o primeiro da lista. É o que evita colar a CPE no contrato cancelado de um cliente que trocou de plano.

Ciclo de sincronização

• Um sincronizador faz uma passada por minuto em cada tenant com o conector ativo, até 50 CPEs por passada, respeitando rate_per_second.
• São candidatas as CPEs sem vínculo e as com vínculo vencido (resync_hours). É o que detecta troca de plano, mudança de login e cancelamento.
• Contrato não encontrado fica registrado como “não encontrado” e só é consultado de novo depois de resync_hours, para não martelar o ERP com CPEs sem cadastro.
• Credencial recusada interrompe a passada inteira e grava o erro em last_error.

O que o vínculo grava

• O vínculo: cliente, contrato, plano, status, endereço, POP, telefones. Senhas do contrato nunca ficam junto: são guardadas cifradas, à parte.
• A configuração do assinante: sempre o login PPPoE do contrato e a senha quando o ERP a expõe; o Wi-Fi só com “ERP é a fonte”. Campo vazio no ERP não apaga o que já estava salvo.
• Mesma checagem do formulário. Cada campo passa pelas regras do PUT …/config (PPPoE até 128, SSID 1–32, senha Wi-Fi 8–63, só imprimíveis). O que não passa é ignorado e o resto segue. PPPoE e cada banda do Wi-Fi andam em par: se o login ou a senha é recusado, os dois ficam de fora.
• Recusas visíveis. Campos recusados geram o evento erp_config_rejected na CPE, com {"erp","contrato","campos":["campo: motivo"]}, nunca o valor.
• Em segundo plano, só o Wi-Fi que mudou é gravado na CPE (tarefa apply_config restrita ao Wi-Fi, sem Connection Request: aplica no próximo Inform). O PPPoE nunca é regravado sem alguém pedir.

Vincular uma CPE que ainda está no login padrão do provedor grava tudo nela (instalação), e a configuração é reaplicada sozinha após um reset de fábrica.

Política de Wi-Fi

Como o vínculo aparece na API

{ "linked": true, "saved": true, "default_login": false, "erp": "…",
  "subscriber": {
    "device_key": "40ED00-XX230v-2249B1000123",
    "erp": "…", "customer_id": "10422", "contract_id": "20981",
    "customer_name": "…", "document": "123.456.789-00",
    "plan": "Fibra 600 Mega", "status": "Ativo", "login": "cliente@isp",
    "address": "Rua das Palmeiras, 120, Centro · CEP 88000-000",
    "city": "Florianópolis/SC", "pop": "POP Centro", "latlng": "-27.59,-48.55",
    "phones": ["(48) 99999-0000"],
    "wifi_desired": { "ssid_24":"Casa", "channel_24":"6", "ssid_5":"Casa 5G" },
    "linked_by": "pppoe", "synced_at": "2026-09-17T09:00:11-03:00" },
  "config": { "pppoe_username": "cliente@isp", "pppoe_password": "••••••••", "source": "…", … } }

Campos que o ERP não fornece vêm vazios. Sem vínculo, linked é false e subscriber não vem, inclusive quando a última consulta não achou contrato: a tela pode mostrar “não encontrado no ERP” sem confundir com erro. As senhas do contrato só saem por GET …/secrets.

ERPs: APIs e conectores

O único artigo da wiki que trata cada ERP pelo nome: o que cadastrar em cada sistema, o que o conector do Lumina chama na API dele, por quais campos busca, o que traz e como apontar o módulo de ACS do ERP para o Lumina.

Resumo

Validado quer dizer que o conector roda contra uma instalação real do ERP com clientes de verdade. Não validado quer dizer que foi escrito a partir da documentação pública da API do ERP: rotas e nomes de campo ainda não confirmados ficam isolados num bloco “a confirmar” do conector, para ajuste rápido na primeira instalação real. Antes de ativar um deles, use Testar conexão e confira o cartão Assinante de uma CPE conhecida depois da primeira sincronização.

“—” na coluna do módulo de ACS quer dizer que esta wiki ainda não documenta o caminho naquele ERP; se ele tiver integração com ACS do tipo GenieACS, a receita genérica de Módulo de ACS do ERP vale.

O que é igual para todos (busca, escolha do contrato, política de Wi-Fi, ciclo de sincronização, mensagens de erro) está em Conector de ERP e Vínculo com o contrato.

SGP validado

No SGP, antes

1. Em Administração › Integrações › Tokens, crie um token para o Lumina.
2. Marque a rota /api/ura/consultacliente/ entre as permitidas. Para o Lumina gravar o PPPoE do contrato, o token precisa expor servico_senha.
3. Se o token usar “Hosts permitidos”, libere o IP de saída do ACS.

Alternativa ao token: usuário e senha (HTTP Basic). O SGP não aceita Bearer.

Configuração no Lumina

O que o Lumina chama

POST https://provedor.sgp.net.br/api/ura/consultacliente/
Content-Type: application/x-www-form-urlencoded
Accept: application/json
User-Agent: LuminaACS

login=cliente%40isp&app=lumina&token=8f3c…

• Só POST: um 405 vira a mensagem “a API do SGP só aceita POST”. Timeout de 20 s por chamada; resposta lida até 4 MB.
• Campos de busca: login (PPPoE), servico_serial (primeiro a chave completa OUI-Modelo-Serial, que o SGP guarda quando o serviço foi cadastrado por um GenieACS, e depois só o serial), MAC e cpfcnpj.
• Escolha entre vários contratos: o que tem servico_login igual ao PPPoE; senão o primeiro ativo (contratoStatus 1 ou “Ativo”); senão o primeiro.

Mapa de campos SGP → Lumina

servico_tipo_conexao, servico_mac e servico_vlan são lidos mas não aparecem na resposta do vínculo. O documento do SGP é guardado sem senhas.

Gerenciador de CPE do SGP (NBI)

Em Sistema › Gerenciador de CPE: tipo GenieACS, URL https://acs.provedor.com.br/nbi, usuário qualquer (por exemplo sgp) e a chave lmk_… como senha, com os escopos da NBI. Sincronizar, Importar Wi-Fi, Definir Wi-Fi, Configurar WAN, Reiniciar e Atualizar firmware viram as tarefas descritas em Módulo de ACS do ERP.

IXC Soft não validado

No IXC, antes

Em Configurações › Tokens de API, um token com permissão de listagem nas tabelas radusuarios, cliente e cliente_contrato. Libere o IP de saída do ACS, se o token restringir origem.

Configuração no Lumina

O que o Lumina chama

POST https://ixc.provedor.com.br/webservice/v1/radusuarios
Authorization: Basic base64(id:chave)
ixcsoft: listar
Content-Type: application/json

{ "qtype": "radusuarios.login", "query": "cliente@isp", "oper": "=",
  "page": "1", "rp": "20", "sortname": "radusuarios.id", "sortorder": "asc" }

• A resposta é {"page","total","registros":[…]} ou {"type":"error","message":"…"}.
• Por login PPPoE ou MAC: radusuarios (campos login ou mac). Por CPF/CNPJ: o cliente em cliente e depois os logins dele em radusuarios.
• Completa com o cadastro do cliente (cliente) e o contrato (cliente_contrato: status e plano).
• Traz login, senha, MAC, cliente, documento, endereço, telefones, status e plano. Não busca por serial nem traz Wi-Fi.

Hubsoft não validado

No Hubsoft, antes

Uma aplicação OAuth2 (client_id e client_secret) e um usuário de API com permissão de consulta de clientes.

Configuração no Lumina

O que o Lumina chama

POST https://api.provedor.hubsoft.com.br/oauth/token
{ "grant_type": "password", "client_id": "…", "client_secret": "…", "username": "…", "password": "…" }

GET https://api.provedor.hubsoft.com.br/api/v1/integracao/cliente?busca=login&termo_busca=cliente@isp&limit=…
Authorization: Bearer <token>

• Busca por login do serviço (busca=login) ou CPF/CNPJ (busca=cpf_cnpj), com o valor em termo_busca. O token vai como Bearer.
• Traz, por serviço do cliente, contrato, plano, status, login, senha, endereço de instalação e telefones. Não busca por serial nem MAC; não traz Wi-Fi.

Gerenciador de CPE do Hubsoft (NBI)

Em Configurações › Integrações › Gerenciador de CPE: escolha GenieACS, URL https://acs.provedor.com.br/nbi, um usuário qualquer e a chave lmk_… como senha.

MK-Auth não validado

No MK-Auth, antes

Em Sistema › API, cadastre uma API (id e segredo) com permissão de consulta de clientes.

Configuração no Lumina

O que o Lumina chama

GET https://mkauth.provedor.com.br/api/cliente/show/login/cliente@isp   # por login PPPoE
GET https://mkauth.provedor.com.br/api/cliente/show/mac/40:ED:00:11:22:33 # por MAC
GET https://mkauth.provedor.com.br/api/cliente/show/12345678900          # por CPF/CNPJ
Authorization: Basic base64(id:segredo)

• Busca por login PPPoE, MAC ou CPF/CNPJ.
• Traz login, senha, nome, documento, plano, situação (ativo, bloqueado, inativo), endereço, MAC e telefones. Não busca por serial; não traz Wi-Fi.

Voalle não validado

No Voalle, antes

Uma integração de terceiros com client_id, client_secret e syndata (pedida à Voalle ou cadastrada no ERP), com permissão de consulta de pessoas, contratos e autenticações de contrato.

Configuração no Lumina

O que o Lumina chama

POST https://erp.provedor.com.br:45700/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=syngw&client_id=…&client_secret=…&syndata=…

• Com o token (como Bearer), consulta a API externa de terceiros no gateway, sob /external/integrations/thirdparty/:

• Traz contrato, plano, status, cliente, documento, login, senha, MAC e endereço. Não busca por serial nem MAC; não traz Wi-Fi.

Nomes históricos na API

O conector nasceu só para o SGP, e alguns identificadores da API ficaram com esse nome. Todos valem para qualquer ERP:

Receitas de integração

Os fluxos que os ERPs mais pedem, prontos para adaptar.

Achar a CPE do cliente a partir do contrato

O caminho barato é o login PPPoE, que o ERP conhece. pppoe é igualdade exata; q busca por trecho também em MAC, serial e SSID.

curl -sG -H "$KEY" "$ACS/api/v1/devices" --data-urlencode "pppoe=cliente@isp" | jq -r '.items[0].key // empty'
curl -sG -H "$KEY" "$ACS/api/v1/devices" --data-urlencode "q=40:ED:00:11:22:34" --data-urlencode "limit=5"

Instalação pelo app do técnico

# CPEs online que subiram com o login padrão do provedor
curl -s -H "$KEY" "$ACS/api/v1/devices?default_login=1&status=online"

# grava o cliente (sem conector: valores do seu ERP) e cria a tarefa apply_config
curl -s -X PUT -H "$KEY" -H "Content-Type: application/json" \
  -d '{"pppoe_username":"cliente@isp","pppoe_password":"s3nh4","wifi_ssid_24":"Casa","wifi_password_24":"senha2g24"}' \
  "$ACS/api/v1/devices/$CPE/config" | jq -r .task_id

# acompanha (a cada 3 a 5 s por até um minuto; se seguir pending, a CPE grava no próximo Inform)
curl -s -H "$KEY" "$ACS/api/v1/tasks/b32fqgm2ejgjkahhetfa" | jq -r .status

Com o conector de ERP ativo, troque o PUT por POST …/subscriber {"login":"cliente@isp"} e trate needs_pppoe_password (ver vincular). GET /api/v1/tasks/{id} exige tasks:read; com só devices:read, procure o id em GET /api/v1/devices/{key}/tasks.

Tela de atendimento, uma chamada por aba

Ao abrir a tela, dispare actions/refresh-hosts. Mostre a última lista com o read_at dela enquanto o atendente lê o resumo e troque-a quando chegar o task.completed do id devolvido, ou quando GET …/list-reads mostrar pending: false e um read_at maior. Se a resposta vier com read: "fresh", a lista já é de menos de um minuto atrás. Mantenha um SSE com ?keys={key} para ver o Inform chegar.

Cancelamento com devolução de equipamento

curl -s -X DELETE -H "$KEY" "$ACS/api/v1/devices/$CPE/subscriber"     # desfaz vínculo e configuração salva
curl -s -X DELETE -H "$KEY" "$ACS/api/v1/devices/$CPE?mode=release"  # libera a vaga de licença

A ONU volta a ser aceita sozinha quando for resetada de fábrica na próxima instalação. Se o equipamento não voltar, use mode=block.

Inventário completo para o ERP

Pagine /devices com limit=500 (ver paginação) ou baixe GET /devices/export.csv com os mesmos filtros e confira a última linha. Depois da carga inicial, mantenha atualizado por webhooks (device.discovered, device.removed, device.online/offline) em vez de varreduras periódicas.

Abrir OS automática por sinal óptico ou reset de fábrica

Crie a regra optical_low (ou factory_reset) com o limiar do seu padrão de rede e assine alert.opened. O payload traz a CPE, o serial e o detalhe da medição; com o vínculo do ERP ativo, o ERP já sabe qual contrato e qual POP. Para reset, também dá para assinar direto device.factory_reset. Feche a OS no alert.resolved.

Contratos com cadastro inválido no ERP

Quando o ERP tem, por exemplo, uma senha Wi-Fi de 5 caracteres, o campo é ignorado e a CPE registra erp_config_rejected. Um relatório para o time de cadastro:

curl -s -H "$KEY" "$ACS/api/v1/devices/$CPE/events?limit=500" \
  | jq '.items[] | select(.kind=="erp_config_rejected") | {at, contrato: .detail.contrato, campos: .detail.campos}'

Erros, limites e boas práticas

Os códigos HTTP, os tetos do servidor e o que fazer em cada caso.

Códigos

Limites

Boas práticas

• Não faça polling de CPE. Assine webhooks.
• Peça a lista de hosts quando for mostrá-la, não em varredura do parque.
• Uma chave por integração, com o mínimo de escopos e lista de IPs.
• Provisione pela configuração do assinante, não por set_values solto: só ela volta sozinha depois de um reset.
• Escreva com connection_request: false em manutenção de massa.
• Trate null: ausência não é zero.
• Nunca gere a chave da CPE no ERP; leia-a de /devices.
• Idempotência nos webhooks pelo id da entrega.
• Exportação CSV: confira a última linha antes de importar.

Login de pessoas por SSO

Não afeta integrações por chave. Quando o login OIDC do console falha, o ACS redireciona para /login?sso_error=<código>. Os códigos são contrato (só se acrescentam): generic, disabled, issuer, state, expired, provider, exchange, id_token, email_missing, email_unverified, domain, role, no_user, user_disabled, mgmt_ip, internal.

Índice de rotas

Todas as rotas da API, uma por linha. autenticado é qualquer chave ou sessão válida; público dispensa credencial.

Fora do /api/v1 existem ainda as rotas que as próprias CPEs usam (/cwmp/…, /fs/… para firmware por URL assinada e /tr143/… para o teste de velocidade) e a NBI. Nenhuma delas é para o ERP chamar, exceto a NBI.

Vocabulário

Os termos que aparecem em toda a wiki.

Inform

Sessão que a CPE abre com o ACS, periodicamente ou por evento (boot, mudança de valor, Connection Request). É o único momento em que o ACS pode falar com ela.

Connection Request

Cutucão do ACS para a CPE abrir uma sessão agora. Por HTTP na porta da CPE ou, atrás de NAT e com o STUN do Lumina ligado, por UDP.

Chave da CPE

OUI-ProductClass-SerialNumber. Mesmo formato de id do GenieACS, o que preserva vínculos já cadastrados no ERP.

Perfil de modelo

Mapa que traduz “SSID do 5 GHz” nos caminhos TR-069 reais de cada fabricante e firmware, com as particularidades conhecidas. É o que faz as ações funcionarem sem o ERP saber de caminhos.

Status da CPE

online; unstable (Informs perdidos repetidos: padrão 3 em 24 h com um na última hora; volta a online depois de 1 h sem novos); offline (sem informar além de 1,5× o intervalo); unlicensed (CPE nova além do limite da licença).

CPE licenciada

CPE que informou nos últimos 30 dias. Acima do limite contratado há tolerância; só CPEs novas são barradas, as já licenciadas continuam gerenciadas. Um agente EasyMesh cujo controlador é CPE licenciada não consome licença.

Configuração do assinante

PPPoE e Wi-Fi do cliente guardados por CPE. O ACS grava a pedido e regrava sozinho depois de um reset de fábrica.

Login padrão

Login PPPoE com que a CPE sai do preset do fabricante para o provedor. CPE nesse login está aguardando instalação (default_login: true).

Quarentena de bootstrap

Estado de uma CPE que voltou com a senha genérica depois de já ter credencial própria. Fica sem configuração do assinante até um operador confirmar.

Agente e controlador EasyMesh

Na rede mesh, o controlador é a CPE principal; o agente é o nó satélite. Configuração de Wi-Fi, LAN e NAT é do controlador.

Tenant

O provedor dentro do ACS. Cada chave de API pertence a um tenant e só vê as CPEs dele.

Lote

A mesma tarefa aplicada a todas as CPEs de um filtro, com salvaguardas.

Campanha

Lote de atualização de firmware com janela de horário, taxa e limite de falhas.

O que mudou

Para quem integrou por uma versão anterior da documentação. quebra marca o que muda o que uma integração antiga recebe ou precisa enviar.

14/10/2026 — esta wiki

A documentação passou de uma página única para esta wiki. Conteúdo conferido com o código e acrescido de rotas que já existiam e não estavam documentadas:

Desde a revisão de 02/09/2026