DWService API

Para usuários avançados

Este guia fornece instruções avançadas para desenvolvedores que desejam integrar as APIs do DWService em suas aplicações, com foco em autenticação, endpoints principais, integração com WebSockets, exemplos de uso, tratamento de erros e considerações de segurança. O DWService oferece uma API RESTful para gerenciar agentes, canais, sessões remotas e integrações personalizadas. Baseado na documentação oficial (versão de outubro de 2025), disponível em https://docs.dwservice.net/docs/api/getting-started/.

As APIs permitem:

• Gerenciar agentes remotamente (instalação, monitoramento, controle).

• Integrar controle remoto (tela, arquivos, processos) em apps web ou desktop.

• Suportar streaming de tela/áudio via WebSockets.

• Realizar operações CRUD em recursos.

• Integrar com SSO, chat, chamadas de vídeo e armazenamento em nuvem.

Pré-requisitos:

• Conta DWService com plano que suporte APIs (verifique em https://api.dwservice.net/).

• Chave de API gerada no painel de desenvolvedor.

• Conhecimento de HTTP/REST, JSON, WebSockets e autenticação OAuth2.

• Limites: Até 200 agentes e 5 canais por conta padrão; expanda via upgrade.

Autenticação

A API usa autenticação baseada em tokens OAuth2. Não use credenciais de login diretamente.

1

Passos para Obter Token

1. Gere uma chave de API no painel: Configurações > API Keys (formato: sk_xxxxxxxx).

2. Faça login OAuth2 para obter um token de acesso:

• Endpoint: POST https://www.apiremoteaccess.com/en/api/v1/auth/token

• Headers: Content-Type: application/x-www-form-urlencoded

• Body (form-data):

grant_type=client_credentials
client_id=SEU_CLIENT_ID
client_secret=SEU_CLIENT_SECRET

• Resposta de Sucesso (200 OK):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

1. Use o access_token em requisições: Authorization: Bearer <token>.

2

Renovação de Token

• Tokens expiram em 1 hora. Renove com o mesmo endpoint, usando refresh_token se disponível.

• Para SSO (ex: Microsoft Azure AD, Zimbra), mapeie credenciais via plugin customizado.

Exemplo em Python (usando requests):

obter_token.py

import requests

url = "https://www.apiremoteaccess.com/en/api/v1/auth/token"
data = {
    "grant_type": "client_credentials",
    "client_id": "SEU_CLIENT_ID",
    "client_secret": "SEU_CLIENT_SECRET"
}
response = requests.post(url, data=data)
token = response.json()["access_token"]
headers = {"Authorization": f"Bearer {token}"}

---

Endpoints Principais

A base URL é https://www.apiremoteaccess.com/en/api/v1/. Todos os endpoints usam JSON. Métodos suportados: GET, POST, PUT, DELETE.

Gerenciamento de Agentes (CRUD)

• URL: /json/agents

• Descrição: Lista, cria, atualiza ou deleta agentes.

Método	Endpoint	Descrição	Parâmetros/Body
GET	/json/agents	Lista todos os agentes.	Query: status=online, group_id=123
POST	/json/agents	Cria um novo agente (gera código de instalação).	Body: { "name": "Meu Agente", "os": "windows" }
PUT	/json/agents/{id}	Atualiza configurações (ex: idioma, apps).	Body: { "enabled_apps": ["screen", "files"] }
DELETE	/json/agents/{id}	Remove agente.	-

Resposta Exemplo (GET):

{
  "agents": [
    {
      "id": 12345,
      "name": "Meu Agente",
      "status": "online",
      "os": "windows",
      "ip": "192.168.1.100",
      "last_seen": "2025-10-08T10:00:00Z"
    }
  ],
  "total": 1
}

Gerenciamento de Canais/Sessões

• URL: /json/channels

• Descrição: Controla acessos simultâneos (ex: múltiplos admins).

Método	Endpoint	Descrição	Parâmetros/Body
POST	/json/channels	Cria canal para sessão remota.	Body: { "agent_id": 12345, "user_ids": [1,2] }
GET	/json/channels/{id}	Obtém status da sessão.	-
DELETE	/json/channels/{id}	Encerra canal.	-

Integração WebSocket: Após criar um canal, conecte-se via wss://www.apiremoteaccess.com/en/ws/session/{channel_id}.

Aplicações Remotas

• URL: /json/apps/{agent_id}/{app_name}

• Descrição: Executa apps específicas (ex: screen, files, processes).

Método	Endpoint	Descrição	Parâmetros/Body
POST	/json/apps/{agent_id}/screen	Inicia stream de tela.	Body: { "quality": "high", "resolution": "1920x1080" }
GET	/json/apps/{agent_id}/files	Lista arquivos remotos.	Query: path=/home/user
POST	/json/apps/{agent_id}/execute	Executa comando no agente.	Body: { "command": "ls -la" }

Eventos e Logs

• URL: /json/events

• Descrição: Analisa eventos (conexões, erros).

Método	Endpoint	Descrição	Parâmetros/Body
GET	/json/events	Lista eventos recentes.	Query: agent_id=12345&from=2025-10-01
POST	/json/events/analyze	Analisa padrões de uso.	Body: { "filter": "failed_connections" }

---

Integração com WebSockets

O DWService suporta streaming de tela, áudio e entrada de usuário via WebSockets para sessões remotas em tempo real. O endpoint WebSocket é: wss://www.apiremoteaccess.com/en/ws/session/{channel_id}

1

Passos para Integração WebSocket

1. Crie um canal via POST /json/channels para obter um channel_id.

2. Conecte ao WebSocket com o token de autenticação.

3. Processe mensagens recebidas (frames de tela, eventos de entrada).

4. Envie comandos de controle (ex: mouse, teclado) via WebSocket.

Exemplo 1: Streaming de Tela em JavaScript

Este exemplo cria um canal e exibe a tela remota em um <canvas>.

stream_tela.js

async function startScreenStream(agentId, token) {
  // Criar canal
  const response = await fetch(`https://www.apiremoteaccess.com/en/api/v1/json/channels`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ agent_id: agentId, app: 'screen', quality: 'high' })
  });
  const { channel_id } = await response.json();

  // Conectar WebSocket
  const ws = new WebSocket(`wss://www.apiremoteaccess.com/en/ws/session/${channel_id}?token=${token}`);
  const canvas = document.getElementById('remoteScreen');
  const ctx = canvas.getContext('2d');

  ws.onopen = () => console.log('Conexão WebSocket estabelecida');
  ws.onmessage = (event) => {
    // Supõe que frames são enviados como blobs (imagens)
    const img = new Image();
    img.src = URL.createObjectURL(event.data);
    img.onload = () => {
      ctx.drawImage(img, 0, 0, canvas.width, canvas.height);
      URL.revokeObjectURL(img.src);
    };
  };
  ws.onerror = (error) => console.error('Erro WebSocket:', error);
  ws.onclose = () => console.log('Conexão WebSocket fechada');

  // Enviar comandos de entrada (ex: clique do mouse)
  canvas.addEventListener('click', (e) => {
    const rect = canvas.getBoundingClientRect();
    const x = e.clientX - rect.left;
    const y = e.clientY - rect.top;
    ws.send(JSON.stringify({ type: 'mouse_click', x, y }));
  });
}

HTML associado:

<canvas id="remoteScreen" width="1920" height="1080"></canvas>

Exemplo 2: Controle de Teclado em Python

Este exemplo envia comandos de teclado para um agente remoto.

teclado_ws.py

import websockets
import asyncio
import requests
import json

async def send_keyboard_commands(agent_id, token):
    # Criar canal
    response = requests.post(
        "https://www.apiremoteaccess.com/en/api/v1/json/channels",
        headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
        json={"agent_id": agent_id, "app": "screen"}
    )
    channel_id = response.json()["channel_id"]

    # Conectar WebSocket
    async with websockets.connect(f"wss://www.apiremoteaccess.com/en/ws/session/{channel_id}?token={token}") as ws:
        # Enviar comando de teclado (ex: pressionar 'Enter')
        await ws.send(json.dumps({"type": "key_press", "key": "Enter"}))
        print("Comando de teclado enviado")

        # Receber confirmação
        response = await ws.recv()
        print("Resposta:", response)

# Executar
asyncio.run(send_keyboard_commands(12345, "SEU_TOKEN"))

Exemplo 3: Transferência de Arquivos com WebSocket

Este exemplo faz upload de um arquivo pequeno para o agente.

upload_arquivo.js

async function uploadFile(agentId, token, file) {
  const response = await fetch(`https://www.apiremoteaccess.com/en/api/v1/json/channels`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ agent_id: agentId, app: 'files' })
  });
  const { channel_id } = await response.json();

  const ws = new WebSocket(`wss://www.apiremoteaccess.com/en/ws/session/${channel_id}?token=${token}`);
  ws.onopen = () => {
    const reader = new FileReader();
    reader.onload = () => {
      ws.send(JSON.stringify({
        type: 'file_upload',
        path: '/remote/path/file.txt',
        data: reader.result
      }));
    };
    reader.readAsDataURL(file);
  };
  ws.onmessage = (event) => console.log('Upload status:', event.data);
}

HTML associado:

<input type="file" id="fileInput" onchange="uploadFile(12345, 'SEU_TOKEN', this.files[0])">

---

Outros Exemplos de Uso Avançado

Deploy Automatizado (Python)

deploy_agents.py

import requests

def deploy_agents(num_agents, token):
    headers = {"Authorization": f"Bearer {token}"}
    for i in range(num_agents):
        resp = requests.post("https://www.apiremoteaccess.com/en/api/v1/json/agents",
                             headers=headers,
                             json={"name": f"Agente {i}", "os": "linux"})
        if resp.status_code == 201:
            print(f"Agente {i} criado: Código = {resp.json()['install_code']}")

Integração SSO (Zimbra)

• Crie um plugin que mapeia usuários Zimbra para DWService.

• Use /auth/token com credenciais mapeadas para login automático.

---

Tratamento de Erros e Limites

• Códigos de Erro Comuns:

Código	Descrição	Ação
401	Token inválido	Renove token.
403	Sem permissão	Verifique escopo da chave API.
429	Rate limit excedido	Aguarde (padrão: 100 req/min).
500	Erro interno	Consulte logs do agente.

• Rate Limits: 100 requisições/minuto por IP; expanda via suporte.

• Paginação: Use ?page=1&limit=50 em listas.

• Logs: Acesse via /json/logs/{agent_id}.

• WebSocket Erros: Trate onerror e reconecte com espera exponencial (ex: 1s, 2s, 4s).

---

Considerações de Segurança

• HTTPS e WSS Obrigatórios: Use TLS 1.3+ para todas as conexões.

• Tokens Seguros: Armazene em variáveis de ambiente; nunca em código.

• Escopos: Defina permissões mínimas (ex: read:agents, write:sessions).

• WebSocket Segurança: Valide channel_id e use tokens em query strings.

• Auditoria: Monitore /json/events para acessos suspeitos.

• Integração Privada: Hospede apps em domínio próprio para evitar redirecionamentos.

• Vulnerabilidades: Relate via mailto:[e-mail]; evite expor chaves em repositórios.

Para mais detalhes, consulte a documentação oficial: https://docs.dwservice.net/docs/api/getting-started/ ou o anúncio de lançamento: https://news.dwservice.net/introducing-the-dwservice-apis/. Este guia reflete a versão de outubro de 2025. Contate mailto:[e-mail] para suporte.