Referência de API

Quick Start

Connect your existing Puppeteer, Playwright, or CDP automation to BotCloud by swapping your WebSocket endpoint to wss://cloud.bots.win. No code rewrites — just one line change.

import puppeteer from "puppeteer-core";

const params = new URLSearchParams({
  token: process.env.BOTCLOUD_TOKEN,
  "--proxy-server": process.env.BOTCLOUD_PROXY,
  device_type: "mac",
});

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://cloud.bots.win?${params.toString()}`,
});

const page = await browser.newPage();
await page.goto("https://example.com");
await page.screenshot({ path: "screenshot.png" });
await browser.close();

Autenticação

Todos os endpoints de API requerem autenticação por token Bearer

# All API endpoints require Bearer token authentication
curl -H "Authorization: Bearer your-user-token-here" \
  https://cloud.bots.win/api/quota

GET /api/quota

Verifique a cota restante antes de iniciar trabalhos

Response: Retorna cota total, usada, restante e percentual usado

curl -H "Authorization: Bearer your-token" https://cloud.bots.win/api/quota

GET /api/usage

Obtenha estatísticas de uso para relatórios e análise de custo

Response: Retorna total de sessões, minutos totais e contagem de sessões ativas

curl -H "Authorization: Bearer your-token" https://cloud.bots.win/api/usage

GET /api/history

Recupere o histórico de sessão para trilhas de auditoria

Parameters: Parâmetros de consulta opcionais de início e fim (timestamps ISO 8601)

Response: Retorna array de objetos de sessão com duração e motivos de desconexão

curl -H "Authorization: Bearer your-token" https://cloud.bots.win/api/history

POST /api/user-data

Crie um novo contêiner de Dados do Usuário para estado persistente do navegador (cookies, localStorage, etc.)

Response: Retorna o ID de Dados do Usuário criado e timestamp

curl -X POST -H "Authorization: Bearer your-token" https://cloud.bots.win/api/user-data

GET /api/user-data

Liste todos os contêineres de Dados do Usuário para o usuário autenticado

Response: Retorna array de objetos de Dados do Usuário com informações de cota

curl -H "Authorization: Bearer your-token" https://cloud.bots.win/api/user-data

DELETE /api/user-data/:id

Exclua um contêiner de Dados do Usuário e libere cota

Response: Retorna status de sucesso

curl -X DELETE -H "Authorization: Bearer your-token" \
  https://cloud.bots.win/api/user-data/udd_abc123xyz789defg

Framework Integration

Puppeteer, PuppeteerSharp, Playwright (Node.js / Python / .NET), raw CDP, Go (chromedp / rod), Java (native WebSocket), and Ruby (Ferrum) all work without code rewrites. Swap wss://cloud.bots.win as your endpoint and pass your token, proxy, and device type as query parameters.

import puppeteer from "puppeteer-core";

const params = new URLSearchParams({
  token: process.env.BOTCLOUD_TOKEN,
  "--proxy-server": process.env.BOTCLOUD_PROXY,
  device_type: "mac",
});

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://cloud.bots.win?${params.toString()}`,
});

const page = await browser.newPage();
await page.goto("https://example.com");
await page.screenshot({ path: "screenshot.png" });
await browser.close();

Modelo de Faturamento

Os planos de assinatura incluem horas de navegador mensais. Após esgotá-las, o uso adicional é cobrado do seu saldo pré-pago à taxa overage do plano.

Erros de Conexão

Esses erros ocorrem durante a configuração da conexão — a sessão nunca é criada, portanto não aparecerá em /api/history. Verifique o status HTTP e a mensagem no corpo da resposta para tratá-los.

Motivos de Desconexão

Uma vez que uma sessão foi aberta, ela eventualmente terminará com um dos motivos abaixo — registrados em /api/history. Use esses códigos para tratamento de erros e trilhas de auditoria.