Bắt đầu

Bắt đầu nhanh

Tạo khoá API, mở một hồ sơ trên máy của bạn, điều khiển bằng Playwright rồi dừng lại.

Cập nhật 27 tháng 10, 2026

Hướng dẫn này gọi thẳng HTTP API để thấy rõ từng bước. Các bước tương tự có trong SDK, CLI và dưới dạng tool MCP.

Bạn cần một workspace Browlix có ít nhất một máy đã ghép nối và đang trực tuyến (Workspace → Máy chạy → Ghép nối máy). Bước 6 phải chạy trên chính máy đó — xem Code chạy ở đâu.

Trước khi bắt đầu

Cài thư viện cho ngôn ngữ bạn dùng (Node 20 trở lên hoặc Python 3.9 trở lên). Gói Playwright chỉ là phần điều khiển, không cần tải trình duyệt riêng vì Browlix mở trình duyệt:

npm i https://browlix.com/api/public/sdk/v1/download/latest playwright

Các đoạn TypeScript ghép thành một ES module có await ở cấp ngoài cùng: lưu thành quickstart.mts rồi chạy node quickstart.mts (Node 22.18 trở lên chạy thẳng TypeScript; Node cũ hơn dùng npx tsx quickstart.mts). Các đoạn curl là bash. Trên Ubuntu và Debian, Python hệ thống từ chối pip install toàn máy: tạo môi trường ảo trước bằng python3 -m venv .venv && . .venv/bin/activate (gói python3-venv).

1. Tạo khoá API

Trên web mở Cài đặt → Khoá API, tạo khoá với phạm vi quyền cần dùng và sao chép — phần bí mật chỉ hiện một lần. Giữ khoá trong biến môi trường, không viết vào code:

bash

export BROWLIX_API_KEY="bxk_…"

2. Kiểm tra khoá

curl https://browlix.com/api/public/v1/workspace \
  -H "Authorization: Bearer $BROWLIX_API_KEY"

Mọi phản hồi có correlation_id; hãy gửi kèm mã này khi báo lỗi.

3. Chọn máy

curl https://browlix.com/api/public/v1/devices \
  -H "Authorization: Bearer $BROWLIX_API_KEY"
# export DEVICE_ID=<data[0].id>

Chọn máy đang trực tuyến; danh sách cũng cho biết hệ điều hành và số phiên còn mở được.

4. Tạo hồ sơ

Mọi thao tác ghi là lệnh: bạn tự gửi command_id (một UUID) để thử lại không bao giờ tạo hồ sơ thứ hai. Xem Lệnh và biên nhận.

curl -X POST https://browlix.com/api/public/v1/profiles \
  -H "Authorization: Bearer $BROWLIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"command_id\":\"$(uuidgen)\",\"profile\":{\"name\":\"Quickstart\",\"config\":{\"os\":\"linux\"}}}"
# export PROFILE_ID=<data.profile_id>

Đặt os đúng hệ điều hành của máy đã chọn (windows hoặc linux): hồ sơ được giữ nhất quán với máy chạy nó.

5. Mở hồ sơ

curl -X POST https://browlix.com/api/public/v1/sessions \
  -H "Authorization: Bearer $BROWLIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"command_id\":\"$(uuidgen)\",\"profile_id\":\"$PROFILE_ID\",\"device_id\":\"$DEVICE_ID\"}"

# export SESSION_ID=<data.id>, rồi hỏi lại tới khi data.lifecycle là "ready"
curl https://browlix.com/api/public/v1/sessions/$SESSION_ID \
  -H "Authorization: Bearer $BROWLIX_API_KEY"

Mỗi hồ sơ chỉ có tối đa một phiên đang chạy. Mở lại sẽ nhận BUSY kèm mã phiên đang mở.

6. Gắn Playwright (trên máy đó)

sessions.attach trả về vé ngắn hạn và địa chỉ broker cục bộ của máy, ws://127.0.0.1:<port>/cdp. Chạy đoạn này trên máy đang giữ phiên:

import { chromium } from "playwright";

const a = await bx.attach(sessionId, { ttlSeconds: 300 });
const browser = await chromium.connectOverCDP(a.endpoint, { headers: a.headers });
const page = browser.contexts()[0]!.pages()[0] ?? (await browser.contexts()[0]!.newPage());
await page.goto("https://example.com");
console.log(await page.title());
await browser.close(); // ngắt Playwright; phiên vẫn chạy

Vé chỉ dùng cho một phiên, trong ttl_seconds (30–900, mặc định 300). Hết hạn thì xin vé mới.

7. Dừng phiên

curl -X POST https://browlix.com/api/public/v1/sessions/$SESSION_ID/stop \
  -H "Authorization: Bearer $BROWLIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"command_id\":\"$(uuidgen)\"}"

Phiên chỉ được báo đã đóng khi máy chứng minh không còn tiến trình trình duyệt nào.

Phiên trình duyệt — mọi trạng thái và nên làm gì ở từng trạng thái.
Webhook — nhận session.ready thay vì hỏi lại liên tục.
Lỗi — các mã lỗi và mã nào an toàn để thử lại.