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

Autenticación

Todos los endpoints de API requieren autenticación con 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

Verifica cuota restante antes de lanzar trabajos

Response: Retorna cuota total, usada, restante y porcentaje usado

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

GET /api/usage

Obtén estadísticas de uso para informes y análisis de costos

Response: Retorna total de sesiones, minutos totales y conteo de sesiones activas

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

GET /api/history

Recupera historial de sesiones para auditoría

Parameters: Parámetros de consulta opcionales inicio y fin (timestamps ISO 8601)

Response: Retorna array de objetos de sesión con duración y razones de desconexión

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

POST /api/user-data

Crea un nuevo contenedor de Datos de Usuario para estado persistente del navegador (cookies, localStorage, etc.)

Response: Retorna ID de Datos de Usuario creado y timestamp

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

GET /api/user-data

Lista todos los contenedores de Datos de Usuario para el usuario autenticado

Response: Retorna array de objetos de Datos de Usuario con información de cuota

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

DELETE /api/user-data/:id

Elimina un contenedor de Datos de Usuario y libera cuota

Response: Retorna estado de éxito

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 Facturación

Los planes de suscripción incluyen horas de navegador mensuales. Una vez agotadas, el uso adicional se descuenta de tu saldo prepago a la tarifa overage del plan.

Errores de Conexión

Estos errores ocurren durante la configuración de la conexión — la sesión nunca se crea, por lo que no aparecerá en /api/history. Comprueba el estado HTTP y el mensaje en el cuerpo de la respuesta para gestionarlos.

Razones de Desconexión

Una vez que se ha abierto una sesión, eventualmente terminará con una de las razones a continuación — registradas en /api/history. Usa estos códigos para el manejo de errores y registros de auditoría.