Đến nội dung
Tài liệuTổng quan

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.

REST APIJSONAPI v1

Bắt đầu nhanh

POST /api/v1/bypass

Gửi URL cùng API key để nhận kết quả vượt link.

cURL
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.

Bảo mật: Không đặt API key trong frontend hoặc repository công khai.

02 · Request

Request body

application/json
{
  "url": "https://linkvertise.com/...",
  "auto_solve_captcha": false,
  "max_hops": 10
}
Các field của request body
FieldTypeBắt buộcMô tả
urlstringCóURL HTTP/HTTPS public cần vượt.
auto_solve_captchabooleanKhôngSolver captcha tự động, mặc định false.
max_hopsintegerKhôngTối đa workflow liên tiếp, mặc định 10.

03 · Response

Response thành công

200 OK · application/json
{
  "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ý

401

API key không hợp lệ

Key thiếu, sai hoặc đã bị thu hồi.

402

Không đủ số dư

Nạp thêm xu trước khi gọi workflow.

403

Tài khoản bị khóa

API key chưa liên kết tài khoản active.

502

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/jobs

Dù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
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
  }'
Idempotency-Key (bắt buộc): 8–128 ký tự 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.
Các field khi tạo job
FieldTypeBắt buộcMô tả
urlstringCóURL HTTP/HTTPS public cần vượt, tối đa 8192 ký tự.
maxHopsintegerKhôngSố link vượt liên tiếp tối đa, 1–10, mặc định 10.
autoSolveCaptchabooleanKhôngChỉ nhận true; job luôn tự giải captcha.
202 Accepted · application/json
{
  "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
curl https://browser-agent.hommi.io.vn/api/v1/bypass/jobs/3f1b6a0e-8c2d-4f5a-9b7e-1d2c3b4a5f60 \
  -H "x-api-key: vl_live_xxx.secret"
200 OK · succeeded
{
  "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"
}
200 OK · failed
{
  "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"
}
Các field của job
FieldTypeMô tả
jobIdstringUUID v4 của job.
statusstringqueued → running → succeeded hoặc failed.
resultobject | nullCó khi succeeded: url đích (hoặc code), hopsUsed, solvedWorkflows, totalCost.
errorobject | nullCó khi failed: code và message an toàn để hiển thị.
billingStatusstringTrạ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).
pollAfterMsintegerThời gian nên chờ trước lần gọi GET tiếp theo.
createdAtstringThời điểm tạo job (ISO 8601).
sourcestringKê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/jobs

Trả 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
curl "https://browser-agent.hommi.io.vn/api/v1/bypass/jobs?limit=20" \
  -H "x-api-key: vl_live_xxx.secret"
200 OK · application/json
{
  "jobs": [ { "jobId": "3f1b6a0e-...", "status": "succeeded", ... } ],
  "nextCursor": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"
}

Mã lỗi của API job

422

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.

401

Chưa xác thực

API key thiếu, sai, đã bị thu hồi hoặc không có scope bypass.

403

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.

404

Không tìm thấy job

jobId sai hoặc job thuộc tài khoản khác.

409

Trùng Idempotency-Key

Cùng key nhưng nội dung request khác lần trước.

502 / 503 / 504

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.

Đơn giá API theo workflow
Mã workflowNền tảngGiá / lượt
gtrafficgtraffic400 ₫
gtraffic-drgtraffic-dr400 ₫
hnmodhnmod400 ₫
ktoolsktools400 ₫
laymalayma500 ₫
link3slink3s200 ₫
link4mlink4m400 ₫
link4sublink4sub200 ₫
link4sub-noteslink4sub-notes200 ₫
linkxlinkx200 ₫
ontopsontops400 ₫
rongyuirongyui200 ₫
toplinkstoplinks400 ₫
trafficso1trafficso1400 ₫
tumadam-unlocktumadam-unlock500 ₫
vuotlinkvuotlink200 ₫
vuotnhanhvuotnhanh200 ₫

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í.