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 Lấy & Xoay Proxy (Get Proxy với Key Xoay)
Sử dụng phương thức GET hoặc POST truyền key nhận được khi mua hàng để lấy proxy hoặc kích hoạt xoay IP theo nhà mạng và vị trí tỉnh thành.
YOUR_KEY bằng key của bạn để chạy thử trực tiếp trên trình duyệt hoặc tool.
Danh Sách Tham Số (Parameters):
| Tham số | Bắt buộc | Giá trị hợp lệ | Mô tả chi tiết |
|---|---|---|---|
key |
Bắt buộc | Chuỗi ký tự |
Key proxy nhận được khi bạn mua hàng trên website. |
nhamang |
Tùy chọn | Random, viettel, fpt, vnpt |
Nhà mạng muốn lấy proxy (mặc định: Random). |
tinhthanh |
Tùy chọn | Mã tỉnh (0, 1, 2, 3...) |
Mã tỉnh liệt kê bên dưới (mặc định: 0 - Random). |
whitelist |
Tùy chọn | 1.2.3.4,5.6.7.8 |
Khai thêm danh sách IPv4 được phép sử dụng proxy. |
Danh Sách Mã Tỉnh Thành (tinhthanh):
0 Random1 Phú Thọ2 Tuyên Quang3 Hà Nội4 Hải Dương5 Bắc Giang6 Hồ Chí Minh7 Tây Ninh8 Đồng Nai9 Vũng Tàu10 Bình Dương11 Nghệ An12 Hà Tĩnh13 Quảng Bình14 Quảng Trị15 Huế16 Đà Nẵng17 Vĩnh Phúc18 Yên Bái19 Lào Cai20 Lạng Sơn21 Thái Nguyên22 Hà Nam23 Nam Định24 Thái Bình25 Hải Phòng26 Quảng Ninh27 Cà Mau28 Kiên Giang29 Bạc Liêu30 Sóc Trăng31 Hậu Giang- Bắc Ninh- Hưng Yên- Ninh Bình- Thanh Hoá- Quảng Nam- Khánh Hoà- Lâm Đồng- Cần ThơVí Dụ Request:
# 1. Gọi phương thức GET curl "https://hubproxy.vn/apiv1/xoay/get.php?key=YOUR_KEY&nhamang=viettel&tinhthanh=3" # 2. Gọi phương thức POST curl -X POST "https://hubproxy.vn/apiv1/xoay/get.php" \ -d "key=YOUR_KEY" \ -d "nhamang=fpt" \ -d "tinhthanh=6"
Kết Quả Trả Về (JSON Response):
Kết quả thành công (status = 100):
{
"status": 100,
"message": "proxy nay se die sau 1777s",
"proxyhttp": "42.117.243.215:10836::",
"proxysocks5": "42.117.243.215:30836::",
"Nha Mang": "fpt",
"Vi Tri": "HaNoi1",
"Token expiration date": "22:52 19-02-2025"
}
Kết quả lỗi (status = 101, 102):
# Lỗi key không tồn tại / hết hạn (status = 102)
{
"status": 102,
"message": "key khong ton tai"
}
# Lỗi chưa truyền key (status = 101)
{
"status": 101,
"message": "Key khong ton tai hoac chua truyen tham so key"
}
2. API Mua Key Proxy Xoay (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 key.
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":21,"quantity":1,"duration":1}'| 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 key |
duration | Có | Số kỳ mua (1–365). Mỗi kỳ dài bằng gói của key: ngày, tuần hoặc tháng |
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": 21,
"product": "Key Xoay 1 Ngày",
"quantity": 1,
"delivered": 1,
"total": 31200,
"refunded_amount": 0,
"currency": "VND",
"created_at": "2026-11-05 22:01:10",
"keys": [
{
"id": "key_34",
"key": "YOUR_ROTATING_KEY",
"kind": 21,
"product": "Key Xoay 1 Ngày",
"expires_at": "2026-11-06 22:01:11",
"status": "active",
"features": [
"renew"
]
}
]
}
}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 |
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.
3. API Gia Hạn Key Proxy Xoay (Gia Hạn Tự Động)
duration là số kỳ gia hạn (1–12). Mỗi kỳ dài bằng gói của key: ngày, tuần hoặc tháng.
curl -X POST "https://hubproxy.vn/apiv1/v1/proxies/key_34/renew" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: gia-han-0001" \
-H "Content-Type: application/json" \
--max-time 100 \
-d '{"duration":1}'4. API Lấy Danh Sách Key Xoay (List Keys Đã Mua)
Xem các key xoay đã mua, hạn dùng và trạng thái. 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/keys?page=1&limit=50" -H "Authorization: Bearer YOUR_API_KEY"
5. 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.
6. Cách gọi API
Mua, gia hạn và xem danh sách key xoay. API key dùng để mua và quản lý. Key xoay nhận được sau khi mua dùng để lấy proxy ở mục 1. Đây là hai key khác nhau.
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=xoay" -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=xoay&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=21&quantity=1&duration=1&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/keys?key=YOUR_API_KEY |
Danh sách key xoay đã mua. Có ?page= và ?limit= | GET |
https://hubproxy.vn/apiv1/v1/proxies/key_34?key=YOUR_API_KEY |
Chi tiết một key xoay | GET |
https://hubproxy.vn/apiv1/v1/proxies/key_34/renew?key=YOUR_API_KEY&duration=1&request_id=gia-han-0001 |
Gia hạn key xoay Có trừ tiền. Bắt buộc request_id |
POSTduration |
7. 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 |
|---|---|---|---|---|
21 |
Key Xoay 1 Ngày | Key xoay | 5 | Gia hạn |
22 |
Key Xoay 1 Tuần | Key xoay | 5 | Gia hạn |
23 |
Key Xoay 1 Tháng | Key xoay | 5 | Gia hạn |
8. 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.