Referência de API

A API REST do RC ACS permite que integradores — ERPs, sistemas internos, scripts de automação — gerenciem CPEs programaticamente. Esta página documenta os principais endpoints, métodos de autenticação e exemplos de uso.

Atenção: As URLs e parâmetros abaixo são exemplos ilustrativos. A documentação completa e interativa via Swagger estará disponível em sua instância do RC ACS em /api-docs. Os endpoints reais podem variar conforme a versão instalada. Esta página é um guia conceitual — sempre consulte o Swagger da sua instância para detalhes exatos.

Visão geral

• Protocolo: REST sobre HTTPS
• Formato de dados: JSON (Content-Type: application/json)
• Versão atual: v3
• URL base: https://seu-acs.dominio.com/api/v1/
• Documentação Swagger: https://seu-acs.dominio.com/api-docs

Autenticação

A autenticação na API é feita via API Key enviada no cabeçalho HTTP. O formato esperado:

Authorization: Bearer <sua-api-key>

O mecanismo exato de autenticação (Bearer token, X-API-Key ou custom header) será confirmado pelo time de desenvolvimento e documentado no Swagger da sua instância.

Para gerar uma chave de API:

1. Acesse o painel do RC ACS como Administrador.
2. Navegue até Administração → Usuários → Chaves de API.
3. Clique em Nova chave e defina nome, permissões e validade.
4. Copie a chave gerada — ela será exibida apenas uma vez.

Dica: Armazene a chave de API com segurança. Nunca a inclua em código-fonte versionado. Use variáveis de ambiente (ACS_API_KEY) ou cofre de segredos.

Endpoints

CPEs

Gerencie CPEs individualmente ou em lote. Principais endpoints:

Diagnósticos

Execute testes e diagnósticos a partir do CPE. Principais endpoints:

Usuários

Gerencie o acesso de operadores ao RC ACS. Principais endpoints:

Exemplos de uso

cURL

# Listar todos os CPEs
curl -X GET "https://acs.seuisp.com.br/api/v1/cpes" \
  -H "Authorization: Bearer sua-api-key" \
  -H "Content-Type: application/json"

# Consultar um CPE específico
curl -X GET "https://acs.seuisp.com.br/api/v1/cpes/ABC123456" \
  -H "Authorization: Bearer sua-api-key"

# Provisionar novo CPE
curl -X POST "https://acs.seuisp.com.br/api/v1/cpes" \
  -H "Authorization: Bearer sua-api-key" \
  -H "Content-Type: application/json" \
  -d '{"serial": "ABC123456", "preset_id": "residencial-100mbps", "cliente": "João Silva"}'

# Alterar SSID e senha Wi-Fi
curl -X PATCH "https://acs.seuisp.com.br/api/v1/cpes/ABC123456" \
  -H "Authorization: Bearer sua-api-key" \
  -H "Content-Type: application/json" \
  -d '{"ssid": "CasaDoJoao", "wifi_password": "novaSenhaSegura123"}'

# Reiniciar CPE
curl -X POST "https://acs.seuisp.com.br/api/v1/cpes/ABC123456/reboot" \
  -H "Authorization: Bearer sua-api-key"

Python

import requests
import os

API_BASE = "https://acs.seuisp.com.br/api/v1"
API_KEY = os.environ.get("ACS_API_KEY")

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Listar CPEs online
response = requests.get(f"{API_BASE}/cpes?status=online", headers=headers)
cpes = response.json()
for cpe in cpes["data"]:
    print(f"{cpe['serial']} - {cpe['fabricante']} - {cpe['modelo']}")

# Provisionar novo CPE
novo_cpe = {
    "serial": "XYZ987654",
    "preset_id": "residencial-300mbps",
    "cliente": "Maria Souza"
}
response = requests.post(f"{API_BASE}/cpes", headers=headers, json=novo_cpe)
if response.status_code == 201:
    print("CPE provisionado com sucesso!")

# Executar speed test
response = requests.post(
    f"{API_BASE}/cpes/XYZ987654/diagnostics/speedtest",
    headers=headers
)
task = response.json()
print(f"Speed test agendado. ID: {task['task_id']}")

PHP

 $http_code, 'body' => json_decode($response, true)];
}

// Listar CPEs
$result = acs_request('GET', '/cpes?status=online');
foreach ($result['body']['data'] as $cpe) {
    echo $cpe['serial'] . " - " . $cpe['fabricante'] . "\n";
}

// Reiniciar CPE
$result = acs_request('POST', '/cpes/ABC123456/reboot');
if ($result['status'] === 202) {
    echo "Reboot agendado com sucesso.\n";
}

Códigos de erro

Rate limits

Os limites de taxa (rate limits) serão definidos pelo time de desenvolvimento e estarão documentados no Swagger da sua instância. Expectativa preliminar: limites por chave de API com janela deslizante, cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e Retry-After em caso de estouro.

Recomendações gerais:

• Use paginação em listagens (parâmetros ?page= e ?limit=).
• Evite polling agressivo — para monitoramento contínuo, prefira webhooks (consulte a documentação de disparo de eventos).
• Implemente backoff exponencial com jitter em caso de 429.
• Cacheie respostas que mudam pouco (ex: lista de presets, lista de CPEs compatíveis).

Perguntas frequentes

A API retorna dados em tempo real ou cache?

Status de CPE (online/offline) e métricas imediatas são em tempo real. Listagens e consultas de configuração refletem o estado mais recente conhecido pelo ACS — que é atualizado a cada Inform do CPE (tipicamente a cada 30 minutos, configurável). Para forçar uma atualização imediata, você pode enviar um comando de refresh via API.

Posso usar a API para migrar CPEs de outro ACS para o RC ACS?

Sim. A migração de CPEs de outro ACS é um caso de uso suportado. O procedimento envolve: (1) alterar a URL do ACS no CPE (via preset ou configuração manual), (2) cadastrar o CPE no RC ACS via API, (3) o CPE se conecta ao novo ACS no próximo Inform. Consulte o guia de presets e entre em contato com nossa equipe de implantação para planejar a migração.

Leia também

• Integração com ERPs
• Disparo de eventos
• Auditoria e rastreabilidade