Tài Liệu Kết Nối API Proxy
Tích hợp và quản lý Proxy tự động dành cho lập trình viên và nhà phát triển.
1. API Key của bạn
Mỗi tài khoản có một key riêng, dùng chung cho cả 3 nhóm API. Tiền mua qua API được trừ vào số dư của tài khoản này, nên hãy giữ key cẩn thận và không chia sẻ cho người khác.
2. Cách gọi API
Proxy IPv4 Việt Nam, Datacenter, Datacenter US, 4G và gói proxy. Có gia hạn và đổi user/pass.
Cách đơn giản nhất là gọi bằng link, thay YOUR_API_KEY bằng API key của bạn. Khi viết phần mềm, nên gửi key trong header Authorization: Bearer YOUR_API_KEY hoặc X-API-Key: YOUR_API_KEY, vì link có thể bị lưu trong lịch sử trình duyệt và nhật ký máy chủ.
request_id (8–64 ký tự). Mở lại cùng một link sẽ trả về đơn cũ, không mua lần nữa. Không gửi link có key thật cho người khác.curl "https://hubproxy.vn/apiv1/v1/account" -H "Authorization: Bearer YOUR_API_KEY"
curl "https://hubproxy.vn/apiv1/v1/products?group=tinh" -H "Authorization: Bearer YOUR_API_KEY"
| Link mẫu gọi API | Chức năng | Gọi bằng header |
|---|---|---|
https://hubproxy.vn/apiv1/v1/account?key=YOUR_API_KEY |
Xem số dư, thông tin tài khoản | GET |
https://hubproxy.vn/apiv1/v1/products?group=tinh&key=YOUR_API_KEY |
Xem sản phẩm, giá, số lượng tối đa, tính năng của nhóm này | GET |
https://hubproxy.vn/apiv1/v1/orders?key=YOUR_API_KEY&kind=1&quantity=2&duration=30&protocol=HTTP&proxy_user=random&proxy_password=random&request_id=don-hang-0001 |
Mua. Chờ xử lý xong mới trả kết quả Có trừ tiền. Bắt buộc request_id |
POSTkind, quantity, duration |
https://hubproxy.vn/apiv1/v1/orders/ord_123?key=YOUR_API_KEY |
Xem đơn và dữ liệu đã giao | GET |
https://hubproxy.vn/apiv1/v1/proxies?key=YOUR_API_KEY |
Danh sách proxy đã mua. Có ?page= và ?limit= | GET |
https://hubproxy.vn/apiv1/v1/packages?key=YOUR_API_KEY |
Danh sách gói đã mua | GET |
https://hubproxy.vn/apiv1/v1/proxies/123?key=YOUR_API_KEY |
Chi tiết một proxy. Với gói, thay 123 bằng goi_12 | GET |
https://hubproxy.vn/apiv1/v1/proxies/123/renew?key=YOUR_API_KEY&duration=30&request_id=gia-han-0001 |
Gia hạn proxy. Với gói, thay 123 bằng goi_12 Có trừ tiền. Bắt buộc request_id |
POSTduration |
https://hubproxy.vn/apiv1/v1/proxies/123/reset-credentials?key=YOUR_API_KEY&username=user0001&password=pass0001&protocol=http |
Đổi user/pass | POSTusername, password, protocol |
3. API Mua Proxy (Mua Mới Tự Động)
API giữ kết nối đến khi hệ thống xử lý xong rồi trả luôn dữ liệu, tối đa 85 giây. Hãy đặt thời gian chờ phía bạn từ 100 giây trở lên. Mỗi lần mua tối đa 5 proxy hoặc 1 gói.
| Lựa chọn | Link mẫu | |
|---|---|---|
| HTTP, user/pass ngẫu nhiên | https://hubproxy.vn/apiv1/v1/orders?key=YOUR_API_KEY&kind=1&quantity=2&duration=30&protocol=HTTP&proxy_user=random&proxy_password=random&request_id=don-hang-0001 |
|
| SOCKS5, user/pass ngẫu nhiên | https://hubproxy.vn/apiv1/v1/orders?key=YOUR_API_KEY&kind=1&quantity=2&duration=30&protocol=SOCKS5&proxy_user=random&proxy_password=random&request_id=don-hang-0002 |
|
| HTTP, tự đặt user/pass | https://hubproxy.vn/apiv1/v1/orders?key=YOUR_API_KEY&kind=1&quantity=2&duration=30&protocol=HTTP&proxy_user=user0001&proxy_password=pass0001&request_id=don-hang-0003 |
|
| SOCKS5, tự đặt user/pass | https://hubproxy.vn/apiv1/v1/orders?key=YOUR_API_KEY&kind=1&quantity=2&duration=30&protocol=SOCKS5&proxy_user=user0001&proxy_password=pass0001&request_id=don-hang-0004 |
curl -X POST "https://hubproxy.vn/apiv1/v1/orders" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: don-hang-0001" \
-H "Content-Type: application/json" \
--max-time 100 \
-d '{"kind":1,"quantity":2,"duration":30,"protocol":"HTTP","proxy_user":"random","proxy_password":"random"}'| Trường | Bắt buộc | Mô tả |
|---|---|---|
key | Có | API key của bạn, hoặc gửi bằng header |
request_id | Có | Mã riêng của mỗi đơn (8–64 ký tự: chữ, số, _ . : -) |
kind | Có | Số của sản phẩm, xem bảng mã sản phẩm bên dưới |
quantity | Có | Số lượng: 1–5 proxy, hoặc đúng 1 gói |
duration | Có | Thời hạn theo unit của sản phẩm trong GET /products: day là số ngày, month là số tháng |
protocol | Không | HTTP (mặc định) hoặc SOCKS5 |
proxy_user, proxy_password | Không | random (mặc định) để hệ thống tạo ngẫu nhiên, hoặc tự đặt 3–32 ký tự gồm chữ, số, _ . - |
expected_total | Không | Tổng tiền bạn dự kiến. Nếu giá khác, đơn bị từ chối và không trừ tiền |
Idempotency-Key) là mã do bạn tự đặt, 8–64 ký tự, mỗi đơn một mã. Nếu mất kết nối giữa chừng, hãy gửi lại đúng mã đó: API trả kết quả của đơn cũ, không mua và không trừ tiền lần nữa. Đừng tạo mã mới vì sẽ thành đơn mới.{
"data": {
"id": "ord_3557",
"task": "buy",
"status": "completed",
"kind": 1,
"product": "IPv4 FPT",
"quantity": 1,
"delivered": 1,
"total": 31200,
"refunded_amount": 0,
"currency": "VND",
"created_at": "2026-11-05 22:01:10",
"proxies": [
{
"id": 31115,
"external_id": "69070",
"kind": 1,
"product": "IPv4 FPT",
"host": "203.0.113.20",
"port": 8080,
"username": "user01",
"password": "pass01",
"protocol": "HTTP",
"proxy": "203.0.113.20:8080:user01:pass01",
"allowed_ip": "",
"expires_at": "2026-12-05 22:01:11",
"status": "active",
"features": [
"renew",
"reset_credentials"
]
}
]
}
}status| Trạng thái | HTTP | Ý nghĩa | Bạn cần làm |
|---|---|---|---|
completed | 200 | Đã giao đủ, có dữ liệu | Sử dụng |
partial | 200 | Giao thiếu. delivered là số đã giao, phần thiếu đã hoàn vào refunded_amount | Dùng số đã giao |
processing | 202 | Hết 85 giây nhưng đơn vẫn đang chạy | Gọi GET /orders/{id} sau ít phút |
provisioning | 202 | Đã mua gói, đang lấy danh sách proxy | Gọi lại sau 1–2 phút |
pending_review | 202 | Chưa xác định được kết quả, đang chờ kiểm tra | Không mua lại. Liên hệ hỗ trợ nếu lâu chưa xong |
Mỗi lần mua và gia hạn đều có trong Lịch sử tiêu, cuối nội dung ghi qua API thành công khi đã giao hàng.
4. API Gia Hạn và Thao Tác Trên Proxy
Mỗi proxy có trường features cho biết tính năng dùng được. Gọi tính năng không có sẽ nhận lỗi FEATURE_NOT_SUPPORTED và không bị trừ tiền. Các thao tác này cũng chờ xử lý xong mới trả kết quả.
duration là số ngày gia hạn (1–730).
curl -X POST "https://hubproxy.vn/apiv1/v1/proxies/123/renew" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: gia-han-0001" \
-H "Content-Type: application/json" \
--max-time 100 \
-d '{"duration":30}'curl -X POST "https://hubproxy.vn/apiv1/v1/proxies/123/reset-credentials" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
--max-time 100 \
-d '{"username":"user0001","password":"pass0001","protocol":"http"}'5. API Lấy Danh Sách Proxy Đã Mua
Xem các proxy đã mua, thông tin kết nối, hạn dùng và tính năng của từng proxy. Mỗi lần trả tối đa 100 dòng, dùng page và limit để lấy tiếp.
curl "https://hubproxy.vn/apiv1/v1/proxies?page=1&limit=50" -H "Authorization: Bearer YOUR_API_KEY"
6. Mã sản phẩm và tính năng
Giá và trạng thái còn hàng xem ở GET /products, vì giá có thể thay đổi.
| kind | Sản phẩm | Loại | Tối đa mỗi lần | Tính năng |
|---|---|---|---|---|
1 |
IPv4 FPT | Proxy IPv4 | 5 | Gia hạn, Đổi user/pass |
2 |
IPv4 VNPT | Proxy IPv4 | 5 | Gia hạn, Đổi user/pass |
3 |
IPv4 Viettel | Proxy IPv4 | 5 | Gia hạn, Đổi user/pass |
6 |
Datacenter Share 1 | Proxy IPv4 | 5 | Gia hạn, Đổi user/pass |
7 |
Datacenter Share 3 | Proxy IPv4 | 5 | Gia hạn, Đổi user/pass |
8 |
Datacenter Private | Proxy IPv4 | 5 | Gia hạn, Đổi user/pass |
13 |
Datacenter US | Proxy IPv4 | 5 | Gia hạn, Đổi user/pass |
14 |
Proxy 4G Vinaphone | Proxy IPv4 | 5 | Gia hạn, Đổi user/pass |
17 |
Gói 90 Proxy Viettel | Gói proxy | 1 | Gia hạn, Đổi user/pass |
18 |
Gói 96 Proxy VNPT | Gói proxy | 1 | Gia hạn, Đổi user/pass |
19 |
Gói 96 Proxy FPT | Gói proxy | 1 | Gia hạn, Đổi user/pass |
20 |
Gói 100 Proxy Datacenter | Gói proxy | 1 | Gia hạn, Đổi user/pass |
7. Mã lỗi
Khi lỗi, API trả về dạng dưới đây. Hãy viết code theo code, vì nội dung message có thể thay đổi.
{
"error": {
"code": "QUANTITY_LIMIT",
"message": "Vượt số lượng mua proxy (tối đa 5)",
"max_quantity": 5
}
}| HTTP | Mã lỗi | Ý nghĩa | Có trừ tiền? |
|---|---|---|---|
| 401 | INVALID_API_KEY | Thiếu API key hoặc key không đúng | Không |
| 402 | INSUFFICIENT_BALANCE | Số dư không đủ | Không |
| 403 | FORBIDDEN | Tài khoản đang bị khóa | Không |
| 404 | NOT_FOUND | Không tìm thấy, hoặc không thuộc tài khoản của bạn | Không |
| 405 | METHOD_NOT_ALLOWED | Sai phương thức (GET, POST...) | Không |
| 409 | PRICE_CHANGED | Giá thực tế khác expected_total. Đọc lại giá rồi gửi lại | Không |
| 409 | IDEMPOTENCY_CONFLICT | Idempotency-Key đã dùng cho một yêu cầu khác | Không |
| 409 | FEATURE_NOT_SUPPORTED | Loại proxy này không có tính năng đó | Không |
| 409 | OUT_OF_STOCK | Hết hàng. Nếu đơn đã tạo thì tiền đã được hoàn | Không, hoặc đã hoàn |
| 409 | ORDER_FAILED | Đơn không thành công. Xem trường refunded | Xem trường refunded |
| 422 | VALIDATION_ERROR | Dữ liệu gửi lên sai hoặc thiếu | Không |
| 422 | QUANTITY_LIMIT | Vượt số lượng mua: tối đa 5 proxy hoặc 1 gói mỗi lần | Không |
| 429 | RATE_LIMITED | Gọi quá nhanh, hoặc đã có 2 yêu cầu đang chờ. Xem Retry-After | Không |
| 500 | INTERNAL_ERROR | Lỗi hệ thống. Gửi mã request_id cho hỗ trợ | Xem đơn nếu có mã đơn |
| 503 | TOOL_OFFLINE | Hệ thống xử lý đơn đang tạm dừng. Thử lại sau | Không |
| 503 | MAINTENANCE | Sản phẩm đang bảo trì hoặc chưa mở bán | Không |
| 503 | NOT_READY | API chưa được bật trên hệ thống | Không |
Giới hạn tốc độ: 120 lần đọc và 20 lần ghi mỗi phút cho mỗi key, tối đa 2 yêu cầu đang chờ cùng lúc.