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

Autenticazione

Tutti gli endpoint API richiedono autenticazione Bearer token

# 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 quota rimanente prima di lanciare job

Response: Restituisce quota totale, utilizzata, rimanente e percentuale utilizzata

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

GET /api/usage

Ottieni statistiche utilizzo per reporting e analisi costo

Response: Restituisce sessioni totali, minuti totali e conteggio sessioni attive

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

GET /api/history

Recupera cronologia sessioni per piste audit

Parameters: Parametri query start e end opzionali (timestamp ISO 8601)

Response: Restituisce array di oggetti sessione con durata e motivi disconnessione

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

POST /api/user-data

Crea un nuovo container User Data per stato browser persistente (cookie, localStorage, ecc.)

Response: Restituisce ID User Data creato e timestamp

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

GET /api/user-data

Elenca tutti i container User Data per l'utente autenticato

Response: Restituisce array di oggetti User Data con informazioni quota

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

DELETE /api/user-data/:id

Cancella un container User Data e rilascia quota

Response: Restituisce stato di successo

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

Modello Fatturazione

I piani di abbonamento includono ore browser mensili. Una volta esaurite, l'utilizzo aggiuntivo viene addebitato dal tuo saldo prepagato alla tariffa overage del piano.

Errori di Connessione

Questi errori si verificano durante la configurazione della connessione — la sessione non viene mai creata, quindi non apparirà in /api/history. Controlla lo stato HTTP e il messaggio nel corpo della risposta per gestirli.

Motivi Disconnessione

Una volta aperta una sessione, si concluderà prima o poi con uno dei motivi seguenti — registrati in /api/history. Usa questi codici per la gestione degli errori e i trail di audit.