Chuyển đến nội dung
hiproxy
Bắt đầu

Hướng dẫn API HiProxy

Những gì bạn làm trong bảng điều khiển, bạn cũng có thể làm từ code của mình. Xem số dư và thông tin kết nối, kiểm tra giá, đặt hàng từ số dư và tạo tên người dùng proxy với các tùy chọn, tất cả qua REST API.

Lấy khóa APIXem các endpoint

Bắt đầu như thế nào?

  1. 1Đăng ký bằng tên đăng nhập và đăng nhập vào bảng điều khiển.
  2. 2Tạo khóa API ở tab Kết nối. Khóa đầy đủ chỉ hiện một lần, nên hãy lưu ngay ở nơi an toàn.
  3. 3Đặt khóa vào header Authorization của mọi yêu cầu cần đến khóa.
  4. 4Gọi /account trước để xác nhận khóa hoạt động, sau đó đặt hàng bằng /orders.

Xác thực hoạt động thế nào?

Các yêu cầu về tài khoản của bạn (account, orders, proxy-user) cần khóa API. Gửi trong header dạng Authorization: Bearer hpk_... Giá, quốc gia và báo giá mở cho mọi người, không cần khóa.

HiProxy chỉ lưu mã băm của khóa, không bao giờ lưu bản thân khóa. Nếu bạn làm mất khóa, hãy tạo khóa mới trong bảng điều khiển, khóa cũ bị chặn ngay lúc đó. Chỉ để khóa trong code phía máy chủ, không bao giờ để trong code chạy trên trình duyệt hay trong repository công khai.

HTTP header
Authorization: Bearer hpk_your_api_key

Base URL và định dạng dữ liệu

Base URL
https://hiproxy.shop/api/v1
Nội dung yêu cầu và phản hồi
application/json
Số tiền
USD dạng số, ví dụ 1036.60
Thời gian
ISO 8601 (UTC)

Có giới hạn tần suất gọi không?

Mỗi khóa API được gọi tối đa 60 lần mỗi phút. Endpoint công khai gọi không có khóa được 60 lần mỗi phút cho mỗi IP. Vượt giới hạn, bạn nhận HTTP 429. Hãy đợi một phút rồi gửi lại.

Phản hồi lỗi trông như thế nào?

Bạn nhận mã trạng thái HTTP cùng phần thân JSON gồm mã lỗi ngắn và thông báo.

Ví dụ
{
  "error": {
    "code": "insufficient_balance",
    "message": "Your balance is too low for this order. Top up in the dashboard."
  }
}
code
bad_requestHTTP 400Thiếu một giá trị bắt buộc, hoặc sản phẩm này không chấp nhận giá trị đó.
unauthorizedHTTP 401Không gửi khóa API, hoặc khóa không đúng.
insufficient_balanceHTTP 402Số dư thấp hơn tổng tiền đơn hàng. Số dư không bị trừ.
not_foundHTTP 404Tài khoản của bạn không có đơn hàng với id này.
rate_limitedHTTP 429Bạn đã vượt giới hạn số yêu cầu mỗi phút.
server_errorHTTP 500Máy chủ không hoàn tất được yêu cầu. Số dư không bị trừ.

Endpoint

Xem tài khoản

GET/api/v1/accountCần khóa API

Hiển thị số dư, host và cổng proxy, tên người dùng và mật khẩu proxy, và danh sách IP được cho phép.

Yêu cầu
curl https://hiproxy.shop/api/v1/account \
  -H "Authorization: Bearer hpk_your_api_key"
Phản hồi
{
  "username": "hi_user01",
  "balance_usd": 1300,
  "proxy": {
    "host": "gate.hiproxy.shop",
    "http_port": 6100,
    "socks5_port": 6200,
    "username": "hpexample1",
    "password": "your_password"
  },
  "allowed_ips": [
    "203.0.113.10"
  ]
}

Xem sản phẩm và giá

GET/api/v1/productsKhông cần khóa

Hiển thị giới hạn đặt hàng, giá theo từng mức và mức giảm theo thời hạn của mỗi sản phẩm. Dùng cùng bảng giá với trang bảng giá.

Yêu cầu
curl https://hiproxy.shop/api/v1/products
Phản hồi
{
  "currency": "USD",
  "prices_as_of": "2026-10-31",
  "products": [
    {
      "id": "unlimited",
      "unit": "day",
      "quantity": {
        "meaning": "days",
        "min": 1,
        "max": 365
      },
      "...": "..."
    },
    {
      "id": "residential",
      "unit": "gb",
      "...": "..."
    }
  ]
}

Danh sách quốc gia và thành phố

GET/api/v1/countriesKhông cần khóa

Hiển thị các quốc gia mỗi sản phẩm hỗ trợ và giá trị thành phố dùng cho tùy chọn -city- trong tên người dùng.

TrườngÝ nghĩa
productKhông bắt buộcMột trong unlimited, residential, isp, datacenter. Bỏ trống nghĩa là residential.
Yêu cầu
curl "https://hiproxy.shop/api/v1/countries?product=datacenter"
Phản hồi
{
  "product": "datacenter",
  "countries": [
    {
      "code": "us",
      "name": "United States",
      "region": "americas",
      "datacenter": true,
      "cities": [
        {
          "name": "New York",
          "value": "new_york"
        },
        {
          "name": "Los Angeles",
          "value": "los_angeles"
        }
      ]
    }
  ]
}

Lấy báo giá

POST/api/v1/quoteKhông cần khóa

Tính tổng đơn hàng mà không đụng đến số dư. Gửi đúng nội dung bạn sẽ gửi khi đặt hàng.

TrườngÝ nghĩa
productBắt buộcMột trong unlimited, residential, isp, datacenter.
quantityBắt buộcSố ngày cho unlimited (1~365), số GB cho residential (5~5,000), số IP cho isp (1~1,000) hoặc datacenter (5~5,000).
concurrencyKhông bắt buộcChỉ cho unlimited. Chọn 200, 500, 1000 hoặc 2000.
bandwidthKhông bắt buộcChỉ cho unlimited, tính bằng Mbps. Chọn 100, 200, 500 hoặc 1000.
monthsKhông bắt buộcChỉ cho isp và datacenter. Chọn 1, 3, 6 hoặc 12.
countryKhông bắt buộcChỉ cho isp và datacenter. Mã quốc gia hai chữ cái như jp. Các giá trị hợp lệ có trong /countries.
Yêu cầu
curl -X POST https://hiproxy.shop/api/v1/quote \
  -H "Content-Type: application/json" \
  -d '{"product":"unlimited","quantity":30,"concurrency":1000,"bandwidth":200}'
Phản hồi
{
  "product": "unlimited",
  "quantity": 30,
  "unit_price_usd": 8.78,
  "unit": "day",
  "total_usd": 263.4
}

Đặt hàng

POST/api/v1/ordersCần khóa API

Trừ tổng tiền từ số dư và tạo đơn hàng. Đơn bắt đầu ở trạng thái pending (đang kích hoạt) và chuyển sang active khi sẵn sàng. Đơn không kích hoạt được sẽ thành refunded, toàn bộ số tiền đã trả được hoàn về số dư. Nếu số dư không đủ, bạn nhận 402.

TrườngÝ nghĩa
productBắt buộcMột trong unlimited, residential, isp, datacenter.
quantityBắt buộcSố ngày cho unlimited (1~365), số GB cho residential (5~5,000), số IP cho isp (1~1,000) hoặc datacenter (5~5,000).
concurrencyKhông bắt buộcChỉ cho unlimited. Chọn 200, 500, 1000 hoặc 2000.
bandwidthKhông bắt buộcChỉ cho unlimited, tính bằng Mbps. Chọn 100, 200, 500 hoặc 1000.
monthsKhông bắt buộcChỉ cho isp và datacenter. Chọn 1, 3, 6 hoặc 12.
countryKhông bắt buộcChỉ cho isp và datacenter. Mã quốc gia hai chữ cái như jp. Các giá trị hợp lệ có trong /countries.
Yêu cầu
curl -X POST https://hiproxy.shop/api/v1/orders \
  -H "Authorization: Bearer hpk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"product":"unlimited","quantity":30,"concurrency":1000,"bandwidth":200}'
Phản hồi
{
  "order": {
    "id": "HP-7KQ2M-X4HTD",
    "product": "unlimited",
    "quantity": 30,
    "months": null,
    "concurrency": 1000,
    "bandwidth_mbps": 200,
    "country": null,
    "unit_price_usd": 8.78,
    "total_usd": 263.4,
    "status": "pending",
    "created_at": "2026-10-31T09:12:44.120Z",
    "updated_at": "2026-10-31T09:12:44.120Z"
  },
  "balance_usd": 1036.6
}

Danh sách đơn hàng

GET/api/v1/ordersCần khóa API

Hiển thị tối đa 100 đơn hàng của bạn, mới nhất trước.

TrườngÝ nghĩa
statusKhông bắt buộcMột trong pending, active, refunded. Bỏ trống để lấy đơn hàng ở mọi trạng thái.
Yêu cầu
curl "https://hiproxy.shop/api/v1/orders?status=pending" \
  -H "Authorization: Bearer hpk_your_api_key"
Phản hồi
{
  "orders": [
    {
      "id": "HP-7KQ2M-X4HTD",
      "product": "unlimited",
      "quantity": 30,
      "months": null,
      "concurrency": 1000,
      "bandwidth_mbps": 200,
      "country": null,
      "unit_price_usd": 8.78,
      "total_usd": 263.4,
      "status": "pending",
      "created_at": "2026-10-31T09:12:44.120Z",
      "updated_at": "2026-10-31T09:12:44.120Z"
    }
  ]
}

Xem một đơn hàng

GET/api/v1/orders/{id}Cần khóa API

Hiển thị một đơn hàng theo id. Tiện để kiểm tra việc kích hoạt đã xong chưa.

TrườngÝ nghĩa
idBắt buộcId đơn hàng, như HP-7KQ2M-X4HTD.
Yêu cầu
curl https://hiproxy.shop/api/v1/orders/HP-7KQ2M-X4HTD \
  -H "Authorization: Bearer hpk_your_api_key"
Phản hồi
{
  "order": {
    "id": "HP-7KQ2M-X4HTD",
    "product": "unlimited",
    "quantity": 30,
    "months": null,
    "concurrency": 1000,
    "bandwidth_mbps": 200,
    "country": null,
    "unit_price_usd": 8.78,
    "total_usd": 263.4,
    "status": "active",
    "created_at": "2026-10-31T09:12:44.120Z",
    "updated_at": "2026-10-31T09:40:02.511Z"
  }
}

Tạo tên người dùng proxy

GET/api/v1/proxy-userCần khóa API

Trả về tên người dùng proxy có sẵn các tùy chọn của bạn, cùng URL HTTP và SOCKS5 có thể dán dùng ngay. Không có session thì IP đổi theo từng yêu cầu.

TrườngÝ nghĩa
productKhông bắt buộcMột trong unlimited, residential, isp, datacenter. Bỏ trống nghĩa là unlimited.
countryKhông bắt buộcMã quốc gia hai chữ cái, ví dụ jp.
cityKhông bắt buộcGiá trị thành phố từ /countries như tokyo. Chỉ dùng được cùng với country.
sessionKhông bắt buộc1~32 chữ cái hoặc chữ số. Các yêu cầu có cùng session dùng cùng một IP.
ttlKhông bắt buộcSố phút giữ IP của phiên, 1~60. Bỏ trống nghĩa là 30.
Yêu cầu
curl "https://hiproxy.shop/api/v1/proxy-user?product=residential&country=jp&city=tokyo&session=job42&ttl=30" \
  -H "Authorization: Bearer hpk_your_api_key"
Phản hồi
{
  "username": "hpexample1-zone-res-cc-jp-city-tokyo-sid-job42-ttl-30",
  "password": "your_password",
  "http": "http://hpexample1-zone-res-cc-jp-city-tokyo-sid-job42-ttl-30:your_password@gate.hiproxy.shop:6100",
  "socks5": "socks5h://hpexample1-zone-res-cc-jp-city-tokyo-sid-job42-ttl-30:your_password@gate.hiproxy.shop:6200"
}

Ví dụ từng bước

Một script kiểm tra giá, đặt hàng từ số dư và kết nối qua IP Nhật Bản.

Python (requests)
import requests

API = "https://hiproxy.shop/api/v1"
HEAD = {"Authorization": "Bearer hpk_your_api_key"}

# 1) Check the price first
plan = {"product": "residential", "quantity": 100}
print(requests.post(f"{API}/quote", json=plan).json())

# 2) Order from your balance
r = requests.post(f"{API}/orders", json=plan, headers=HEAD)
order = r.json()["order"]
print(order["id"], order["status"])

# 3) Get a username for Japanese IPs
u = requests.get(f"{API}/proxy-user", headers=HEAD,
                 params={"product": "residential", "country": "jp"}).json()
proxies = {"http": u["http"], "https": u["http"]}
print(requests.get("https://ipinfo.io/json", proxies=proxies, timeout=30).json())
Node.js 18+
const API = "https://hiproxy.shop/api/v1";
const HEAD = { Authorization: "Bearer hpk_your_api_key", "Content-Type": "application/json" };

// Check the balance
const acc = await fetch(`${API}/account`, { headers: HEAD }).then((r) => r.json());
console.log(acc.balance_usd);

// Order 7 days of unlimited
const res = await fetch(`${API}/orders`, {
  method: "POST",
  headers: HEAD,
  body: JSON.stringify({ product: "unlimited", quantity: 7, concurrency: 500, bandwidth: 100 }),
});
if (res.status === 402) console.log("Top up first");
else console.log((await res.json()).order.id);

Đơn đặt qua API được xử lý giống đơn trong bảng điều khiển và hiện ở tab Lịch sử. Thay hpk_your_api_key trong ví dụ bằng khóa API của bạn.

Gọi HiProxy từ code của bạn

Đăng ký bằng tên đăng nhập, tạo khóa API trong bảng điều khiển là sẵn sàng.

Tạo tài khoảnHướng dẫn cài đặt