API de CPE Novo na 7.2

Visão geral

A API de CPE expõe o ambiente CPE inteiro para sistemas externos. Ela cobre dois grandes usos:

• Consultar: lista de CPEs com filtros e paginação (com export CSV/PDF), retrato completo de uma CPE (Wi-Fi, WAN, LAN, portas, hosts conectados, vínculos com OLT e concentradora, tarefas, alertas e auditoria), visão geral da frota, estado do ambiente de gerência, perfis, modelos homologados, rotinas, campanhas, diagnósticos e resumos de IA.
• Gerenciar: reiniciar e restaurar de fábrica, editar Wi-Fi (rede, senha, canal), WAN (DNS, MTU, IPv6), credenciais PPPoE, LAN/DHCP, portas físicas, redirecionamentos de porta e DMZ, bloquear aparelhos, gerência web da CPE, vincular ONU, criar e aplicar perfis de provisionamento, disparar campanhas em massa (inclusive firmware), configurar rotinas autônomas, rodar diagnósticos e conduzir a homologação de modelos.

Casos típicos: integrar o provisionamento da CPE ao fluxo de ativação do seu ERP, trocar a senha do Wi-Fi do assinante direto do seu sistema de atendimento, alimentar um painel próprio com a saúde da frota e automatizar campanhas de firmware fora do horário comercial.

Pré-requisitos

Formato das chamadas

Todas as operações usam o endpoint único da API pública, com action=cpe. GET e POST são aceitos em todas as operações; prefira POST nas operações de escrita e sempre que quiser evitar o token em logs de acesso. Os parâmetros de cada operação vão junto, na querystring ou no corpo do formulário.

https://SEU-RAVI/api/api.php?token=CHAVE&action=cpe&operation=NOME_DA_OPERACAO

Envelope das respostas:

• Sucesso: {"status":"success","data":{...}} com HTTP 200.
• Erro: {"status":"error","message":"..."}. Nas confirmações em duas etapas (abaixo) e em algumas validações, o erro vem acompanhado de um campo data com detalhes.
• Exceção: operation=cpes com export=csv ou export=pdf devolve o arquivo bruto (CSV ou PDF), fora do envelope JSON.

Operações que criam tarefa na CPE

As ações que tocam o equipamento (reiniciar, editar Wi-Fi, WAN etc.) não são instantâneas: elas criam uma tarefa que o sistema envia à CPE e depois relê para confirmar que o valor realmente mudou. A resposta traz o estado inicial:

Acompanhe o desfecho (confirmada ou não) com operation=tarefas, que mostra o status final de cada tarefa após a releitura.

Confirmação em duas etapas

Três fluxos de grande alcance pedem confirmação explícita. A primeira chamada responde status:"error" com os números do alcance em data; repita a chamada com o campo de confirmação para executar:

Erros comuns a todas as operações

Operações de consulta

cpes: listar o inventário

Lista paginada com os mesmos filtros da tela CPEs. Todos os parâmetros são opcionais:

Resposta: total, pagina, porPagina, itens[] (serial, fabricante, modelo, firmware, login PPPoE, MAC, IPs, status, última comunicação, descrição, etiquetas, favorito, vínculos) e contagens (online, offline, favoritas, mudas há 24h). Com um ERP conectado, cada item ganha erpNome e erpStatus.

cpe: retrato completo de uma CPE

Parâmetro: serial (obrigatório). Devolve tudo o que a página da CPE mostra: cadastro e assinante, informações do equipamento, sinal óptico, WANs (PPPoE e IP), LAN, redes Wi-Fi, redirecionamentos e DMZ, gerência web, aparelhos conectados (com bloqueio), séries históricas, vínculos de topologia (sessão, concentradora, ONU/OLT), tarefas recentes, auditoria e firmwares disponíveis.

Estado do ambiente e da frota

Listagens

Ações em uma CPE

Todas exigem serial (o serial exato do inventário). As que escrevem no equipamento criam tarefa com releitura de confirmação e respeitam o modo bancada.

Energia, dados e cadastro

wifi_editar: rede Wi-Fi

wan_editar e wan_pppoe_editar: interface de internet

Ambas recebem caminho (a conexão WAN, como vem no retrato da CPE, bloco wansPpp).

LAN, portas e gerência web

Redirecionamentos, DMZ e bloqueio de aparelhos

Vínculo com a ONU

Perfis, homologação e rotinas

Perfis de provisionamento

Catálogo de modelos e homologação guiada

Rotinas autônomas

As rotinas existem uma por tipo; use operation=rotinas para listar os ids. Depois:

Extras por tipo: dns4 (rotina de DNS padrão), ntp (servidores de hora), idPerfilRestrito (perfil do bloqueio via ERP), wifiNotaLimiar e largura20 (correção de canal Wi-Fi), uptimeMinDias (reinício terapêutico), etiqueta (recolhimento de cancelados).

Ações em massa (campanhas)

O fluxo é o mesmo da tela Em massa: filtre os alvos, confira o alcance e confirme.

Configuração do ambiente

Exemplos práticos

Listar as CPEs offline (POST, com o token fora da URL):

curl -s https://SEU-RAVI/api/api.php \
  -d "token=SUA_CHAVE" \
  -d "action=cpe" \
  -d "operation=cpes" \
  -d "status=0" \
  -d "porPagina=100"

Trocar a senha do Wi-Fi de um assinante (o caminho vem do retrato da CPE, bloco wifi):

curl -s https://SEU-RAVI/api/api.php \
  -d "token=SUA_CHAVE" \
  -d "action=cpe" \
  -d "operation=wifi_editar" \
  -d "serial=ZTEG12345678" \
  -d "caminho=InternetGatewayDevice.LANDevice.1.WLANConfiguration.1" \
  -d "ssid=CasaDoJoao" \
  -d "senha=NovaSenha2026"

Reiniciar e depois acompanhar o desfecho da tarefa:

curl -s https://SEU-RAVI/api/api.php \
  -d "token=SUA_CHAVE" -d "action=cpe" -d "operation=reiniciar" -d "serial=ZTEG12345678"

curl -s "https://SEU-RAVI/api/api.php?token=SUA_CHAVE&action=cpe&operation=tarefas&serial=ZTEG12345678&limite=5"

Campanha de reinício fora do horário comercial, em duas etapas (prévia e confirmação):

# 1ª chamada: devolve status "error" com data.confirmar=true e o alcance
curl -s https://SEU-RAVI/api/api.php \
  -d "token=SUA_CHAVE" -d "action=cpe" -d "operation=massa_criar" \
  -d "tipoAcao=reiniciar" -d "fabricante=ZTE" \
  -d "janelaInicio=02:00" -d "janelaFim=05:00"

# 2ª chamada: os mesmos campos + confirmado=1
curl -s https://SEU-RAVI/api/api.php \
  -d "token=SUA_CHAVE" -d "action=cpe" -d "operation=massa_criar" \
  -d "tipoAcao=reiniciar" -d "fabricante=ZTE" \
  -d "janelaInicio=02:00" -d "janelaFim=05:00" -d "confirmado=1"

Solução de problemas