مرجع 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: يعيد معرّف بيانات المستخدم المُنشأ والطابع الزمني

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. استخدم هذه الرموز لمعالجة الأخطاء وسجلات التدقيق.