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)
GET / POST

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.

https://hubproxy.vn/apiv1/xoay/get.php
Thay thế 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 Random
1 Phú Thọ
2 Tuyên Quang
3 Hà Nội
4 Hải Dương
5 Bắc Giang
6 Hồ Chí Minh
7 Tây Ninh
8 Đồng Nai
9 Vũng Tàu
10 Bình Dương
11 Nghệ An
12 Hà Tĩnh
13 Quảng Bình
14 Quảng Trị
15 Huế
16 Đà Nẵng
17 Vĩnh Phúc
18 Yên Bái
19 Lào Cai
20 Lạng Sơn
21 Thái Nguyên
22 Hà Nam
23 Nam Định
24 Thái Bình
25 Hải Phòng
26 Quảng Ninh
27 Cà Mau
28 Kiên Giang
29 Bạc Liêu
30 Sóc Trăng
31 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)
GET / POST

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.

https://hubproxy.vn/apiv1/v1/orders
Ví dụ gọi bằng header
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ườngBắt buộcMô tả
keyCóAPI key của bạn, hoặc gửi bằng header
request_idCóMã riêng của mỗi đơn (8–64 ký tự: chữ, số, _ . : -)
kindCóSố của sản phẩm, xem bảng mã sản phẩm bên dưới
quantityCóSố lượng: 1–5 key
durationCó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_totalKhôngTổng tiền bạn dự kiến. Nếu giá khác, đơn bị từ chối và không trừ tiền
request_id (hoặc header 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.
Kết quả khi mua xong
{
    "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"
                ]
            }
        ]
    }
}
Các trạng thái status
Trạng tháiHTTPÝ nghĩaBạn cần làm
completed200Đã giao đủ, có dữ liệuSử dụng
partial200Giao thiếu. delivered là số đã giao, phần thiếu đã hoàn vào refunded_amountDùng số đã giao
processing202Hết 85 giây nhưng đơn vẫn đang chạyGọi GET /orders/{id} sau ít phút
pending_review202Chưa xác định được kết quả, đang chờ kiểm traKhô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)
Gia hạn

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)
GET

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.

https://hubproxy.vn/apiv1/v1/keys
Ví dụ gọi bằng header
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.

Vui lòng đăng nhập để tạo API key.
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.

Địa chỉ API
https://hubproxy.vn/apiv1/v1
Xác thực

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

Link mua và gia hạn là giao dịch thật: mở link là trừ tiền. Mỗi đơn mới phải đổi 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.
Xem số dư
curl "https://hubproxy.vn/apiv1/v1/account" -H "Authorization: Bearer YOUR_API_KEY"
Xem sản phẩm và giá
curl "https://hubproxy.vn/apiv1/v1/products?group=xoay" -H "Authorization: Bearer YOUR_API_KEY"
Danh sách đường link
Link mẫu gọi APIChức năngGọ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
POST
kind, 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
POST
duration
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.

kindSản phẩmLoạiTối đa mỗi lầnTí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
  }
}
HTTPMã lỗiÝ nghĩaCó trừ tiền?
401INVALID_API_KEYThiếu API key hoặc key không đúngKhông
402INSUFFICIENT_BALANCESố dư không đủKhông
403FORBIDDENTài khoản đang bị khóaKhông
404NOT_FOUNDKhông tìm thấy, hoặc không thuộc tài khoản của bạnKhông
405METHOD_NOT_ALLOWEDSai phương thức (GET, POST...)Không
409PRICE_CHANGEDGiá thực tế khác expected_total. Đọc lại giá rồi gửi lạiKhông
409IDEMPOTENCY_CONFLICTIdempotency-Key đã dùng cho một yêu cầu khácKhông
409FEATURE_NOT_SUPPORTEDLoại proxy này không có tính năng đóKhông
409OUT_OF_STOCKHết hàng. Nếu đơn đã tạo thì tiền đã được hoànKhông, hoặc đã hoàn
409ORDER_FAILEDĐơn không thành công. Xem trường refundedXem trường refunded
422VALIDATION_ERRORDữ liệu gửi lên sai hoặc thiếuKhông
422QUANTITY_LIMITVượt số lượng mua: tối đa 5 proxy hoặc 1 gói mỗi lầnKhông
429RATE_LIMITEDGọi quá nhanh, hoặc đã có 2 yêu cầu đang chờ. Xem Retry-AfterKhông
500INTERNAL_ERRORLỗi hệ thống. Gửi mã request_id cho hỗ trợXem đơn nếu có mã đơn
503TOOL_OFFLINEHệ thống xử lý đơn đang tạm dừng. Thử lại sauKhông
503MAINTENANCESản phẩm đang bảo trì hoặc chưa mở bánKhông
503NOT_READYAPI chưa được bật trên hệ thốngKhô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.