Integrador ACS — API para os roteadores

Onde fica: Integrador ACS › Loja de Plugins (chaves) · API em /api/webservice/

O ACS é o servidor que gerencia os roteadores dos clientes (TR-069). A sua API permite que o OMNI e o Integrador ISP consultem um equipamento e mandem comandos — trocar a senha do Wi-Fi, reiniciar, aplicar o padrão da empresa, gravar o PPPoE — sempre dentro da empresa dona da chave.

Antes de começar

Na Loja de Plugins do ACS, gere uma chave por sistema: uma para o ISP (prefixo isp_) e outra para o OMNI (prefixo omni_). O administrador revela e copia a chave quando precisar. Gerar uma nova chave invalida a anterior na hora.
O endereço que o outro sistema guarda deve ser só a origem (por exemplo, https://acs.exemplo.com.br). O caminho /api/webservice/... é acrescentado por quem chama. Endereço com caminho colado dá erro 404.

Autenticação

Authorization: Bearer <chave> em toda chamada. O ACS reconhece, pela ordem: o token de um usuário do painel, o token da empresa (legado) e a chave dedicada de integração. A empresa vem da chave: um sistema nunca enxerga equipamentos de outra empresa.

Escopos — o que a chave pode fazer

Escopo	Libera
`leitura`	Consultar equipamento, senha e espectro do Wi-Fi, status, hosts e histórico.
`wifi`	Trocar senha e nome do Wi-Fi, aplicar o padrão da empresa, canal automático, separar bandas.
`reboot`	Reiniciar o roteador.
`pppoe`	Gravar usuário e senha PPPoE no aparelho.
`cadastro`	Vincular ou desvincular cliente (espelho de conexões, adoção de aparelho).
`reset`	Reset de fábrica.

Chaves criadas na Loja de Plugins hoje nascem sem restrição de escopo (valem todos). Chaves antigas, sem escopo gravado, também valem todos. Chamada sem o escopo: 403 com escopo_insuficiente.

Como identificar o aparelho

Todas as rotas aceitam um destes quatro identificadores, nesta ordem de preferência:

dispositivo_id — o id do aparelho no ACS;
serial_number — o serial da ONU/roteador;
cliente_ref — o cliente no ERP. Para o Integrador ISP use o prefixo: isp:<id>. Sem prefixo, é o id do cliente no IXC. 1234 e isp:1234 são clientes diferentes;
pppoe_user — o login PPPoE do cliente (o que o ERP realmente tem na conexão).

Recursos

As rotas ficam em /api/webservice/ (e, por compatibilidade, em /api/omni/).

Consultar (escopo `leitura`)

Método e rota	Para quê
`GET /equipamento`	Consulta consolidada de um aparelho: `online`, fabricante, modelo, serial, SSID, IP da WAN, login PPPoE, sinal óptico (RX/TX), clientes conectados, tempo ligado, se está no padrão da empresa e o último contato. Sempre responde 200: sem equipamento, vem `{"encontrado": false, "mensagem": ...}`.
`GET /equipamentos`	Como o anterior, mas devolve todos os aparelhos do cliente (principal e satélites de mesh).
`GET /status`	Resumo curto do aparelho.
`GET /senha-wifi`	Senha atual do Wi-Fi, quando o firmware a expõe.
`GET /espectro-wifi`	Análise dos canais de 2,4 e 5 GHz: canal atual, largura, ocupação pelos vizinhos (quando o aparelho informa), veredito e recomendação.
`GET /hosts`	Aparelhos conectados ao roteador (nome, MAC, banda e sinal).
`GET /interfaces-wifi`	Uma linha por rede Wi-Fi anunciada (2,4 GHz, 5 GHz, convidados), com SSID, tecnologia, clientes conectados e se está ativa.
`GET /manutencao-status`	Confere se o padrão da empresa já foi aplicado, o roteador reiniciou e voltou.
`GET /eventos`	Histórico de operações de um aparelho (`dispositivo_id` obrigatório, `limite`).
`GET /equipamentos-novos`	Aparelhos recém-vistos, sem dono e com login de fábrica, para o técnico "adotar" (`minutos` até 1.440; `limite` até 100).

Comandos

Todo comando enfileira uma tarefa e tenta acordar o roteador na hora (Connection Request); se não conseguir, a tarefa é entregue no próximo contato do aparelho. A resposta traz tarefa_id, que pode ser acompanhado em GET /api/tasks.

Método e rota	Escopo	Para quê e campos
`POST /trocar-senha-wifi`	`wifi`	Troca a senha do Wi-Fi nas duas bandas. `nova_senha` (mínimo 8 caracteres); se omitida, o ACS gera uma forte e devolve em `nova_senha`.
`POST /trocar-nome-wifi`	`wifi`	Troca o nome da rede. `ssid_24` e `ssid_5` (por banda) ou `novo_nome` (um só). Máximo de 32 caracteres.
`POST /aplicar-padrao-wifi`	`wifi`	Aplica o padrão da empresa (potência, canal automático, largura, DNS) e depois reinicia. `partes` (opcional: `wifi`, `senha_admin`, `dns`, `acesso_remoto`) recorta o que é enviado — e, nesse caso, não reinicia.
`POST /reiniciar-roteador`	`reboot`	Reinicia o roteador.
`POST /canal-automatico`, `POST /otimizar-canal-suave`, `POST /separar-bandas`	`wifi`	Ajustes de canal e separação das redes de 2,4 e 5 GHz.
`POST /aplicar-pppoe`	`pppoe`	Grava `login` e `senha` PPPoE na interface do aparelho (`reiniciar` opcional). Responde `ja_aplicado` se já está certo e `sem_interface_ppp` se não achar a interface.
`POST /adotar`	`cadastro`	O técnico adota um aparelho sem dono: vínculo com o cliente + padrão da empresa + PPPoE. Corpo: `dispositivo_id`, `cliente`, `contrato`, `login`, `senha`. `409` se o aparelho já é de outro cliente.
`PUT /conexoes/{login}`	`cadastro`	O ISP empurra o espelho de uma conexão (cliente, contrato, login, equipamento) quando cria, altera ou cancela um contrato. Idempotente; nunca apaga aparelho (cancelamento é "suave").

Em todo comando que altera o aparelho, mande o bloco opcional autor (tipo: cliente, tecnico, sistema ou atendimento; mais id, nome e origem). Ele registra quem pediu no histórico; sem ele, fica "desconhecido".

Repetir o mesmo comando em menos de 60 segundos reaproveita a tarefa recém-criada (proteção contra repetição).

Webhook de volta (ACS → ISP)

O ACS avisa o ISP do que fez em cada aparelho, em lotes assinados por HMAC (X-Acs-Signature: sha256=<hex>) para POST /api/webhooks/acs. A configuração (endereço do ISP e segredo) fica nas Configurações do ACS, em "Integração Integrador ISP". Detalhes em Integrador ISP.

Exemplos

Consultar o equipamento de um cliente do ISP

bash

curl -s "https://acs.exemplo.com.br/api/webservice/equipamento?cliente_ref=isp:3749" \
  -H "Authorization: Bearer omni_chave-de-exemplo"

json

{"encontrado": true, "dispositivo_id": 4242, "online": true, "fabricante": "Fabricante Exemplo",
 "modelo": "EX520", "serial": "SERIALEXEMPLO01", "ssid": "Rede-Exemplo", "pppoe": "cliente.um",
 "sinal_fibra_rx_dbm": -21.4, "no_padrao_da_empresa": true,
 "ultimo_contato": "2026-10-20T14:05:00+00:00"}

Trocar a senha do Wi-Fi

bash

curl -s -X POST https://acs.exemplo.com.br/api/webservice/trocar-senha-wifi \
  -H "Authorization: Bearer omni_chave-de-exemplo" \
  -H "Content-Type: application/json" \
  -d '{"pppoe_user": "cliente.um",
       "autor": {"tipo": "atendimento", "nome": "Atendente Exemplo", "origem": "omni"}}'

json

{"ok": true, "mensagem": "Troca de senha enfileirada e dispositivo acordado (Connection Request).",
 "tarefa_id": 9001, "dispositivo_id": 4242, "connection_request": true, "nova_senha": "Gerada123Exemplo"}

Outras rotas da API

O painel do ACS usa outras rotas (/api/devices, /api/tasks, /api/events, /api/firmware, /api/ixc, /api/rotinas), que seguem a sessão do usuário do painel e não são o contrato de integração. As de leitura /api/tasks e /api/events também aceitam a chave de integração.

Erros comuns

Código	Quando
`401`	Sem `Authorization: Bearer`.
`403`	Token inválido, empresa inativa ou chave sem o escopo (`escopo_insuficiente`).
`404`	Aparelho não encontrado nesta empresa.
`409`	Aparelho já vinculado a outro cliente (em `/adotar`).
`422`	Falta um identificador, senha com menos de 8 caracteres, nome de rede inválido ou login do caminho diferente do corpo.

Integrador ACS — API para os roteadores ​

Antes de começar ​

Autenticação ​

Escopos — o que a chave pode fazer ​

Como identificar o aparelho ​

Recursos ​

Consultar (escopo leitura) ​

Comandos ​

Webhook de volta (ACS → ISP) ​

Exemplos ​

Consultar o equipamento de um cliente do ISP ​

Trocar a senha do Wi-Fi ​

Outras rotas da API ​

Erros comuns ​

Leia também ​