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.

Vui lòng đăng nhập để tạo API key.
2. Cách gọi API

Proxy IPv4 Update, Datacenter Update, Dân Cư Private, Private Xoay và IPv6. Có thêm IP được phép, đổi giao thức, đổi port, xoay IP, đổi DNS, reset, tùy theo từng loại.

Đị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=update" -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=update&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=9&quantity=1&duration=1&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
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/proxies?key=YOUR_API_KEY Danh sách proxy đã mua. Có ?page= và ?limit= GET
https://hubproxy.vn/apiv1/v1/proxies/123?key=YOUR_API_KEY Chi tiết một proxy GET
https://hubproxy.vn/apiv1/v1/proxies/123/renew?key=YOUR_API_KEY&duration=30&request_id=gia-han-0001 Gia hạn proxy
Có trừ tiền. Bắt buộc request_id
POST
duration
https://hubproxy.vn/apiv1/v1/proxies/123/reset-credentials?key=YOUR_API_KEY&username=user0001&password=pass0001&protocol=http Đổi user/pass POST
username, password, protocol
https://hubproxy.vn/apiv1/v1/proxies/123/allowed-ips?key=YOUR_API_KEY&ip=203.0.113.10 Thêm IP được phép dùng proxy POST
ip
https://hubproxy.vn/apiv1/v1/proxies/123/allowed-ips?key=YOUR_API_KEY&ip=203.0.113.10&action=remove Xóa IP được phép dùng proxy DELETE
ip
https://hubproxy.vn/apiv1/v1/proxies/123/protocol?key=YOUR_API_KEY&protocol=SOCKS5 Đổi giao thức HTTP hoặc SOCKS5 POST
protocol
https://hubproxy.vn/apiv1/v1/proxies/123/port?key=YOUR_API_KEY&port=2000 Đổi port (1000–9999) POST
port
https://hubproxy.vn/apiv1/v1/proxies/123/rotate?key=YOUR_API_KEY Xoay IP POST
https://hubproxy.vn/apiv1/v1/proxies/123/dns?key=YOUR_API_KEY&dns1=1.1.1.1&dns2=8.8.8.8 Đổi DNS POST
dns1, dns2
https://hubproxy.vn/apiv1/v1/proxies/123/reset?key=YOUR_API_KEY Reset proxy POST
https://hubproxy.vn/apiv1/v1/proxies/123/rotate-time?key=YOUR_API_KEY&seconds=60 Đổi thời gian xoay (1–86400 giây) POST
seconds
3. API Mua Proxy (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 proxy.

https://hubproxy.vn/apiv1/v1/orders
Ví dụ theo lựa chọn giao thức và user/pass
Lựa chọnLink mẫu
HTTP, user/pass ngẫu nhiên https://hubproxy.vn/apiv1/v1/orders?key=YOUR_API_KEY&kind=9&quantity=1&duration=1&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=9&quantity=1&duration=1&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=9&quantity=1&duration=1&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=9&quantity=1&duration=1&protocol=SOCKS5&proxy_user=user0001&proxy_password=pass0001&request_id=don-hang-0004
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":9,"quantity":1,"duration":1,"protocol":"HTTP","proxy_user":"random","proxy_password":"random"}'
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 proxy
durationCó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
protocolKhôngHTTP (mặc định) hoặc SOCKS5
proxy_user, proxy_passwordKhôngrandom (mặc định) để hệ thống tạo ngẫu nhiên, hoặc tự đặt 3–32 ký tự gồm chữ, số, _ . -. Một số loại yêu cầu tài khoản 6–12 ký tự chỉ gồm chữ và số
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
prefix, carrierKhôngChọn đầu IP hoặc nhà mạng, với sản phẩm có trong options
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": 9,
        "product": "DC Private Update",
        "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": 9,
                "product": "DC Private Update",
                "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",
                    "allowed_ips",
                    "protocol",
                    "port"
                ]
            }
        ]
    }
}
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.

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

Gia hạn

duration là số ngày gia hạn (1–730). Sản phẩm tính theo tháng được làm tròn lên: 30 ngày là 1 tháng.

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}'
Đổi user/pass
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"}'
Thêm IP được phép
curl -X POST "https://hubproxy.vn/apiv1/v1/proxies/123/allowed-ips" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 100 \
  -d '{"ip":"203.0.113.10"}'
Xoay IP
curl -X POST "https://hubproxy.vn/apiv1/v1/proxies/123/rotate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 100 \
  -d '[]'
5. API Lấy Danh Sách Proxy Đã Mua
GET

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.

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

kindSản phẩmLoạiTối đa mỗi lầnTính năng
4 IPv4 VNPT Update Proxy IPv4 5 Gia hạn, Đổi user/pass, IP được phép, Đổi giao thức
5 IPv4 Mobifone Update Proxy IPv4 5 Gia hạn, Đổi user/pass, IP được phép, Đổi giao thức
9 DC Private Update Proxy IPv4 5 Gia hạn, Đổi user/pass, IP được phép, Đổi giao thức, Đổi port
10 DC Share Update Proxy IPv4 5 Gia hạn, Đổi user/pass, IP được phép, Đổi giao thức
11 Private Xoay Proxy IPv4 5 Gia hạn, Đổi user/pass, IP được phép, Đổi giao thức, Xoay IP, Đổi DNS, Reset
12 Dân Cư Private Proxy IPv4 5 Gia hạn, Đổi user/pass, IP được phép, Đổi giao thức, Đổi port
15 IPv6 Datacenter VN Proxy IPv6 5 Gia hạn, Đổi user/pass, IP được phép, Đổi giao thức
16 IPv6 Xoay VN Proxy IPv6 5 Gia hạn, Đổi user/pass, IP được phép, Đổi giao thức, Thời gian xoay
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
  }
}
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.