ProxyWorld API

Những gì bạn làm trong bảng điều khiển đều làm được bằng code. Xem số dư, kiểm tra giá, đặt hàng từ số dư và lấy tên người dùng proxy kèm tùy chọn, tất cả qua một REST API.

Lấy khóa APIXem các endpoint

Mới bắt đầu? Làm theo các bước sau

  1. 1Đăng ký bằng email và mật khẩu, hoặc bằng token, rồi mở 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, ngay lúc tạo, nên hãy lưu lại ngay.
  3. 3Đặt khóa vào header Authorization của mọi yêu cầu cần đến nó.
  4. 4Gọi /account trước để chắc chắn khóa được chấp nhận, sau đó đặt hàng bằng /orders.

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

Các yêu cầu liên quan đến 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 pwk_... Giá, quốc gia và báo giá mở cho mọi người, gọi được mà không cần khóa.

Máy chủ ProxyWorld không lưu khóa, chỉ lưu hash của khóa. Nếu 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. Chỉ đặt khóa trong code phía máy chủ. Nếu khóa lọt vào code chạy trên trình duyệt hoặc repository công khai, người khác có thể dùng nó.

HTTP header
Authorization: Bearer pwk_your_api_key

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

Base URL
https://proxyworld.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ụ 1058.50
Thời gian
ISO 8601 (UTC)

Tôi được gọi bao nhiêu lần?

Mỗi khóa API được gọi 60 lần mỗi phút. Endpoint công khai gọi không cần khóa cho phép 60 lần mỗi phút cho mỗi IP. Vượt quá sẽ nhận HTTP 429. Chờ khoảng một phút rồi thử lại.

Khi có lỗi thì nhận được gì?

Bạn nhận được mã trạng thái HTTP và nội dung JSON gồm mã lỗi ngắn và lời giải thích.

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 gửi giá trị mà sản phẩm này không chấp nhận.
unauthorizedHTTP 401Thiếu khóa API hoặc khóa không hợp lệ.
insufficient_balanceHTTP 402Số dư nhỏ hơn tổng đơn hàng. Số dư chưa bị trừ.
not_foundHTTP 404Tài khoản của bạn không có đơn hàng với mã này.
rate_limitedHTTP 429Bạn đã vượt quá số lần gọi cho phép mỗi phút.
server_errorHTTP 500Máy chủ không xử lý xong yêu cầu. Số dư chưa bị trừ.

Endpoint

Xem tài khoản

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

Trả về cách bạn đăng nhập (login: email hoặc token), email, số dư, host và cổng proxy, tên người dùng và mật khẩu proxy, và các IP được cho phép. Với tài khoản tạo bằng token, email là null.

Yêu cầu
curl https://proxyworld.shop/api/v1/account \
  -H "Authorization: Bearer pwk_your_api_key"
Phản hồi
{
  "login": "email",
  "email": "you@example.com",
  "balance_usd": 1300,
  "proxy": {
    "host": "gate.proxyworld.shop",
    "http_port": 6100,
    "socks5_port": 6200,
    "username": "pwexample1",
    "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

Trả về phạm vi đặt hàng của từng sản phẩm, đơn giá theo từng mức số lượng và giảm giá theo thời hạn. Dùng cùng bảng giá với trang bảng giá.

Yêu cầu
curl https://proxyworld.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",
      "...": "..."
    }
  ]
}

Quốc gia và thành phố

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

Trả về các quốc gia có thể chọn cho từng sản phẩm, kèm giá trị thành phố dùng trong tùy chọn -city- của tên người dùng.

TênÝ nghĩa
productKhông bắt buộcMột trong unlimited, residential, isp, datacenter. Nếu bỏ trống, dùng residential.
Yêu cầu
curl "https://proxyworld.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.

TênÝ nghĩa
productBắt buộcMột trong unlimited, residential, isp, datacenter.
quantityBắt buộcSố lượng đặt: số ngày cho unlimited (1~365), 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 một trong 200, 500, 1000, 2000.
bandwidthKhông bắt buộcChỉ cho unlimited, tính bằng Mbps. Một trong 100, 200, 500, 1000.
monthsKhông bắt buộcChỉ cho isp và datacenter. Một trong 1, 3, 6, 12.
countryKhông bắt buộcChỉ cho isp và datacenter. Mã quốc gia hai chữ cái, ví dụ jp. Các giá trị hợp lệ có trong /countries.
Yêu cầu
curl -X POST https://proxyworld.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.05,
  "unit": "day",
  "total_usd": 241.5
}

Đặ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 trả lại vào số dư. Nếu số dư không đủ, bạn nhận 402.

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

Xem đơn hàng

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

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

TênÝ 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://proxyworld.shop/api/v1/orders?status=pending" \
  -H "Authorization: Bearer pwk_your_api_key"
Phản hồi
{
  "orders": [
    {
      "id": "PW-7KQ2M-X4HTD",
      "product": "unlimited",
      "quantity": 30,
      "months": null,
      "concurrency": 1000,
      "bandwidth_mbps": 200,
      "country": null,
      "unit_price_usd": 8.05,
      "total_usd": 241.5,
      "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

Trả về đơn hàng khớp với mã đơn. Tiện để kiểm tra đã kích hoạt xong chưa.

TênÝ nghĩa
idBắt buộcMã đơn hàng, ví dụ PW-7KQ2M-X4HTD.
Yêu cầu
curl https://proxyworld.shop/api/v1/orders/PW-7KQ2M-X4HTD \
  -H "Authorization: Bearer pwk_your_api_key"
Phản hồi
{
  "order": {
    "id": "PW-7KQ2M-X4HTD",
    "product": "unlimited",
    "quantity": 30,
    "months": null,
    "concurrency": 1000,
    "bandwidth_mbps": 200,
    "country": null,
    "unit_price_usd": 8.05,
    "total_usd": 241.5,
    "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 kèm tùy chọn của bạn, cùng URL HTTP và SOCKS5 có thể dán dùng ngay. Nếu không gửi session, IP sẽ đổi ở mỗi yêu cầu.

TênÝ nghĩa
productKhông bắt buộcMột trong unlimited, residential, isp, datacenter. Nếu bỏ trống, dùng 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ố có trong /countries, ví dụ tokyo. Gửi kèm country.
sessionKhông bắt buộc1~32 chữ cái và chữ số. Các yêu cầu cùng session dùng cùng một IP.
ttlKhông bắt buộcThời gian phiên giữ IP, 1~60 phút. Nếu bỏ trống, 30 phút.
Yêu cầu
curl "https://proxyworld.shop/api/v1/proxy-user?product=residential&country=jp&city=tokyo&session=job42&ttl=30" \
  -H "Authorization: Bearer pwk_your_api_key"
Phản hồi
{
  "username": "pwexample1-zone-res-cc-jp-city-tokyo-sid-job42-ttl-30",
  "password": "your_password",
  "http": "http://pwexample1-zone-res-cc-jp-city-tokyo-sid-job42-ttl-30:your_password@gate.proxyworld.shop:6100",
  "socks5": "socks5h://pwexample1-zone-res-cc-jp-city-tokyo-sid-job42-ttl-30:your_password@gate.proxyworld.shop:6200"
}

Ví dụ đầy đủ từ đầu đến cuối

Một script lấy báo giá, đặt hàng từ số dư rồi kết nối qua IP tại Nhật Bản.

Python (requests)
import requests

API = "https://proxyworld.shop/api/v1"
HEAD = {"Authorization": "Bearer pwk_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://proxyworld.shop/api/v1";
const HEAD = { Authorization: "Bearer pwk_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ử cùng các đơn khác. Thay pwk_your_api_key trong ví dụ bằng khóa API của bạn.

Kết nối ProxyWorld với code của bạn

Đăng ký bằng email hoặc token, tạo khóa API trong bảng điều khiển, và bạn có thể bắt đầu gọi ngay.

Tạo tài khoản miễn phíCách kết nối