Справка по 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();

Аутентификация

Все конечные точки API требуют аутентификации 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

Проверьте оставшуюся квоту перед запуском заданий

Response: Возвращает общую квоту, использованную, оставшуюся и процент используемой

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

GET /api/usage

Получите статистику использования для отчетов и анализа затрат

Response: Возвращает общее количество сессий, общее количество минут и количество активных сессий

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

GET /api/history

Получите историю сессии для журналов аудита

Parameters: Необязательные параметры запроса начала и конца (временные метки ISO 8601)

Response: Возвращает массив объектов сессии с длительностью и причинами отключения

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

POST /api/user-data

Создайте новый контейнер пользовательских данных для постоянного состояния браузера (cookies, localStorage и т. д.)

Response: Возвращает созданный ID пользовательских данных и временную метку

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

GET /api/user-data

Список всех контейнеров пользовательских данных для аутентифицированного пользователя

Response: Возвращает массив объектов пользовательских данных с информацией о квоте

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

DELETE /api/user-data/:id

Удалить контейнер пользовательских данных и освободить квоту

Response: Возвращает статус успеха

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();

Модель оплаты

Планы подписки включают ежемесячные часы браузера. После их исчерпания дополнительное использование списывается с вашего предоплаченного баланса по ставке overage плана.

Ошибки подключения

Эти ошибки возникают при установке соединения — сессия не создаётся, поэтому она не появится в /api/history. Для обработки проверьте HTTP-статус и сообщение в теле ответа.

Причины отключения

После открытия сессии она в конечном счёте завершится с одной из причин ниже — зафиксированных в /api/history. Используйте эти коды для обработки ошибок и ведения журналов аудита.