Hướng dẫn tích hợp
Tích hợp API vượt link
Gửi URL, xử lý workflow và nhận URL đích qua REST API của VuotLink. Bắt đầu với API key và một request.
Bắt đầu nhanh
POST /api/v1/bypassGửi URL cùng API key để nhận kết quả vượt link.
curl -X POST https://browser-agent.hommi.io.vn/api/v1/bypass \
-H "Content-Type: application/json" \
-H "x-api-key: vl_live_xxx.secret" \
-d '{
"url": "https://linkvertise.com/...",
"auto_solve_captcha": false,
"max_hops": 10
}'01 · Authentication
Xác thực bằng API key
Tạo key trong Cài đặt → API keys. Gửi toàn bộ key trong header x-api-key. Key chỉ hiển thị một lần khi tạo.
02 · Request
Request body
{
"url": "https://linkvertise.com/...",
"auto_solve_captcha": false,
"max_hops": 10
}| Field | Type | Bắt buộc | Mô tả |
|---|---|---|---|
| url | string | Có | URL HTTP/HTTPS public cần vượt. |
| auto_solve_captcha | boolean | Không | Solver captcha tự động, mặc định false. |
| max_hops | integer | Không | Tối đa workflow liên tiếp, mặc định 10. |
03 · Response
Response thành công
{
"requested_url": "https://linkvertise.com/...",
"final_url": "https://example.com/destination",
"status_code": 200,
"title": "Example destination",
"workflow": "linkvertise",
"hops_used": 1,
"hops_exceeded": false,
"solved_workflows": [
{
"workflow": "linkvertise",
"resolved_url": "https://example.com/destination"
}
],
"total_cost": 200,
"remaining_balance": 9800
}URL qua nhiều dịch vụ sẽ được xử lý theo từng hop.
04 · Errors
Mã lỗi cần xử lý
API key không hợp lệ
Key thiếu, sai hoặc đã bị thu hồi.
Không đủ số dư
Nạp thêm xu trước khi gọi workflow.
Tài khoản bị khóa
API key chưa liên kết tài khoản active.
Workflow thất bại
Yêu cầu được hoàn phí tự động.
05 · Async jobs
Tạo job vượt link
POST /api/v1/bypass/jobsDùng job khi link cần nhiều thời gian xử lý. Request trả về ngay 202 Accepted kèm jobId và header Location; sau đó gọi API lấy thông tin job để nhận kết quả. API key cần scope bypass.
curl -X POST https://browser-agent.hommi.io.vn/api/v1/bypass/jobs \
-H "Content-Type: application/json" \
-H "x-api-key: vl_live_xxx.secret" \
-H "Idempotency-Key: 7f3c9a1e-order-0001" \
-d '{
"url": "https://linkvertise.com/...",
"maxHops": 10
}'A-Z a-z 0-9 _ -, duy nhất cho mỗi lần gửi. Gửi lại cùng key và cùng body trả về job cũ thay vì tạo job mới — dùng lại key khi retry sau timeout.| Field | Type | Bắt buộc | Mô tả |
|---|---|---|---|
| url | string | Có | URL HTTP/HTTPS public cần vượt, tối đa 8192 ký tự. |
| maxHops | integer | Không | Số link vượt liên tiếp tối đa, 1–10, mặc định 10. |
| autoSolveCaptcha | boolean | Không | Chỉ nhận true; job luôn tự giải captcha. |
{
"jobId": "3f1b6a0e-8c2d-4f5a-9b7e-1d2c3b4a5f60",
"status": "queued",
"billingStatus": "none",
"pollAfterMs": 2000,
"createdAt": "2026-11-16T08:00:00.000Z",
"source": "api"
}06 · Async jobs
Lấy thông tin job
GET /api/v1/bypass/jobs/{jobId}Gọi lại sau pollAfterMs cho đến khi status là succeeded hoặc failed. Job thất bại vẫn trả 200 kèm error. Chỉ đọc được job của chính tài khoản sở hữu API key.
curl https://browser-agent.hommi.io.vn/api/v1/bypass/jobs/3f1b6a0e-8c2d-4f5a-9b7e-1d2c3b4a5f60 \
-H "x-api-key: vl_live_xxx.secret"{
"jobId": "3f1b6a0e-8c2d-4f5a-9b7e-1d2c3b4a5f60",
"status": "succeeded",
"result": {
"url": "https://example.com/destination",
"code": null,
"hopsUsed": 1,
"solvedWorkflows": [],
"totalCost": 200
},
"error": null,
"billingStatus": "settled",
"pollAfterMs": 2000,
"createdAt": "2026-11-16T08:00:00.000Z",
"source": "api"
}{
"jobId": "3f1b6a0e-8c2d-4f5a-9b7e-1d2c3b4a5f60",
"status": "failed",
"result": null,
"error": { "code": "unsupported_link", "message": "Link chưa được hỗ trợ" },
"billingStatus": "settled",
"pollAfterMs": 2000,
"createdAt": "2026-11-16T08:00:00.000Z",
"source": "api"
}| Field | Type | Mô tả |
|---|---|---|
| jobId | string | UUID v4 của job. |
| status | string | queued → running → succeeded hoặc failed. |
| result | object | null | Có khi succeeded: url đích (hoặc code), hopsUsed, solvedWorkflows, totalCost. |
| error | object | null | Có khi failed: code và message an toàn để hiển thị. |
| billingStatus | string | Trạng thái phí, tách biệt với status: none (chưa trừ hoặc miễn phí), debited (đã tạm trừ), settled (đã chốt, gồm cả khi đã hoàn phí), reconciliation_required (đang đối soát). |
| pollAfterMs | integer | Thời gian nên chờ trước lần gọi GET tiếp theo. |
| createdAt | string | Thời điểm tạo job (ISO 8601). |
| source | string | Kênh tạo job: web, telegram hoặc api. Job tạo qua API này luôn là api. |
07 · Async jobs
Danh sách job
GET /api/v1/bypass/jobsTrả các job mới nhất của tài khoản. limit từ 1 đến 100 (mặc định 20); truyền cursor=nextCursor để lấy trang tiếp theo, nextCursor: null là trang cuối.
curl "https://browser-agent.hommi.io.vn/api/v1/bypass/jobs?limit=20" \
-H "x-api-key: vl_live_xxx.secret"{
"jobs": [ { "jobId": "3f1b6a0e-...", "status": "succeeded", ... } ],
"nextCursor": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"
}Mã lỗi của API job
Dữ liệu không hợp lệ
Thiếu/sai Idempotency-Key, url, maxHops, có field lạ hoặc sai tham số phân trang.
Chưa xác thực
API key thiếu, sai, đã bị thu hồi hoặc không có scope bypass.
Không được phép
API key chưa liên kết tài khoản hoặc không được phép vượt link.
Không tìm thấy job
jobId sai hoặc job thuộc tài khoản khác.
Trùng Idempotency-Key
Cùng key nhưng nội dung request khác lần trước.
Dịch vụ tạm lỗi
Thử lại GET sau; không tạo job mới với key khác.
08 · Pricing
Bảng giá workflow
Đơn giá API cơ bản theo từng workflow, lấy từ cấu hình hiện tại. Giá tính bằng VNĐ mỗi lượt, chưa gồm phụ phí tự giải captcha hoặc xử lý nhiều bước.
| Mã workflow | Nền tảng | Giá / lượt |
|---|---|---|
| gtraffic | gtraffic | 400 ₫ |
| gtraffic-dr | gtraffic-dr | 400 ₫ |
| hnmod | hnmod | 400 ₫ |
| ktools | ktools | 400 ₫ |
| layma | layma | 500 ₫ |
| link3s | link3s | 200 ₫ |
| link4m | link4m | 400 ₫ |
| link4sub | link4sub | 200 ₫ |
| link4sub-notes | link4sub-notes | 200 ₫ |
| linkx | linkx | 200 ₫ |
| ontops | ontops | 400 ₫ |
| rongyui | rongyui | 200 ₫ |
| toplinks | toplinks | 400 ₫ |
| trafficso1 | trafficso1 | 400 ₫ |
| tumadam-unlock | tumadam-unlock | 500 ₫ |
| vuotlink | vuotlink | 200 ₫ |
| vuotnhanh | vuotnhanh | 200 ₫ |
17 / 17 workflow
Gói tháng có quota đi kèm; khi hết quota, lượt vượt thêm tính theo đơn giá API. Xem bảng giá gói tháng để ước tính tổng chi phí.