Tài liệu API ProxyZing.Com

curl "https://api.proxyzing.com/api/v1/me/" \
  -H "X-API-Key: ...pxy"

Tạo body mua từ cấu hình gói

Mọi giá trị gửi lên đều lấy từ configuration của gói (chi tiết gói). Tên option nào cũng thêm hậu tố _code, riêng protocol giữ nguyên.

curl -X POST "https://api.proxyzing.com/api/v1/public/proxy-plans/proxy-dan-cu-viettel/purchase/" \
  -H "X-API-Key: ...pxy" \
  -H "Idempotency-Key: 7f3c9a2e-4b1d-4c8e-9a51-2d6f0b8e1c33" \
  -H "Content-Type: application/json" \
  -d '{"period_code":"daily","quantity":1,"selected_options":{"location_code":"17","protocol":"http"}}'

curl -X POST "https://api.proxyzing.com/api/v1/proxies/<proxy_id>/renew/" \
  -H "X-API-Key: ...pxy" \
  -H "Idempotency-Key: 0c5e8a1b-6d24-4f7a-8b39-91e2a4c7d5f0" \
  -H "Content-Type: application/json" \
  -d '{"days":30}'

Tạo API key. Sau đó gửi key trong header của mọi request:

• Key đầy đủ chỉ hiển thị một lần lúc tạo. Mất key thì xóa và tạo key mới. Có thể thu hồi key bất cứ lúc nào, key ngừng hoạt động ngay.
• Không gửi key qua query string. Không dùng Authorization: Bearer cho API key.
• Chỉ dùng key ở phía server của bạn, không đưa vào ứng dụng web hoặc mobile.
• Key thuộc tài khoản nào thì mọi thao tác (đọc dữ liệu, trừ tiền) áp dụng cho tài khoản đó.
• Lưu key trong biến môi trường hoặc kho bí mật, không ghi vào mã nguồn hay đưa lên kho mã. Nghi ngờ key bị lộ thì thu hồi ngay và tạo key mới.
• Các thao tác tài khoản (tạo hoặc thu hồi key, đổi mật khẩu, nạp và rút tiền, sửa hồ sơ) không dùng được bằng API key, chỉ làm trên dashboard.
• Chỉ tài khoản có role customer dùng được API key. Key tạo bởi tài khoản staff hoặc admin bị từ chối khi gọi API (401).

Tài khoản

Gói

Đơn hàng

Proxy

* Proxy revoked: các trường ip_address, http_port, socks5_port, country, username, password đều là null. Hãy xử lý null cho cả nhóm này.

Giao dịch số dư

Cách dùng

1. Sinh một mã duy nhất cho mỗi hành động của bạn (khuyến nghị UUID v4, tối đa 255 ký tự) và gửi trong header Idempotency-Key.
2. Nếu request lỗi mạng hoặc timeout, gửi lại đúng request đó với đúng mã đó (cùng URL, cùng body).
3. Muốn thực hiện một lần mua mới thì dùng mã mới.

Server phản hồi

Lưu ý

• Mã áp dụng riêng cho từng tài khoản và có hiệu lực 24 giờ. Sau 24 giờ dùng lại mã cũ sẽ được coi là request mới.
• Kết quả replay được dựng lại từ dữ liệu hiện tại, nên với gia hạn, proxy trả về là trạng thái mới nhất.
• Nếu nhận 409 nhiều lần liên tiếp (vài phút), request gốc có thể đã bị gián đoạn giữa chừng. Hãy kiểm tra GET /proxy-orders/?ordering=-created_at hoặc GET /proxies/{id}/ để xem đơn hoặc hạn đã cập nhật chưa, đừng đổi mã và mua lại khi chưa kiểm tra.
• Nếu bạn không gửi Idempotency-Key, server không chống trùng và mỗi request là một lần mua hoặc gia hạn mới.

Cách sinh và giữ mã

• Mã do bên gọi tự sinh (server không cấp), ví dụ crypto.randomUUID() trong JavaScript hoặc uuid.uuid4() trong Python. Mã phải có trước khi gửi request thì mới dùng lại được khi request bị timeout.
• Sinh một lần cho mỗi lần người dùng bắt đầu mua hoặc gia hạn (ví dụ khi mở form hoặc modal xác nhận) và giữ lại. Đừng sinh mã mới mỗi lần bấm nút hoặc mỗi lần gọi hàm gửi request, vì như vậy không chống được trùng.
• Mọi lần gửi lại của cùng lần mua đó (retry, bấm đúp) dùng lại đúng mã cũ với body giống hệt.
• Mua hoặc gia hạn thành công thì bỏ mã. Lần mua tiếp theo, kể cả cùng gói, dùng mã mới. Người dùng chủ động mua hai lần thì dùng hai mã khác nhau và cả hai đều được tính.

Xử lý phản hồi phía client

Với ứng dụng web gọi API từ phía server (ví dụ Next.js server action), mã phải được sinh ở phía giao diện khi mở form rồi truyền xuống server để chuyển tiếp thành header. Nếu server action tự sinh mã mỗi lần được gọi thì không có tác dụng chống trùng.

import { randomUUID } from "node:crypto";

const API_BASE = "https://api.proxyzing.com/api/v1/";
const API_KEY = process.env.PROXYZING_API_KEY;

async function api(path, { method = "GET", body, idempotencyKey } = {}) {
  const headers = { "X-API-Key": API_KEY };

  if (body) headers["Content-Type"] = "application/json";
  if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;

  const response = await fetch(API_BASE + path, {
    method,
    headers,
    body: body ? JSON.stringify(body) : undefined,
    signal: AbortSignal.timeout(90_000),
  });
  const data = await response.json();

  if (!response.ok) {
    throw Object.assign(new Error(data.error.message), {
      status: response.status,
      code: data.error.code,
      details: data.error.details,
    });
  }

  return data;
}

async function purchase(slug, body) {
  const idempotencyKey = randomUUID();

  for (let attempt = 1; attempt <= 3; attempt++) {
    try {
      return await api("public/proxy-plans/" + slug + "/purchase/", {
        method: "POST",
        body,
        idempotencyKey,
      });
    } catch (error) {
      const retryable =
        error.status === undefined || error.code === "request_in_progress";

      if (!retryable || attempt === 3) throw error;

      await new Promise((resolve) => setTimeout(resolve, 3000));
    }
  }
}

console.log(await api("me/"));
console.log(
  await purchase("proxy-dan-cu-viettel", {
    period_code: "daily",
    quantity: 1,
    selected_options: { location_code: "17", protocol: "http" },
  }),
);

import os
import time
import uuid

import requests

API_BASE = "https://api.proxyzing.com/api/v1/"
HEADERS = {"X-API-Key": os.environ["PROXYZING_API_KEY"]}


def get_me():
    response = requests.get(API_BASE + "me/", headers=HEADERS, timeout=30)
    response.raise_for_status()
    return response.json()


def purchase(slug, body):
    headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}

    for attempt in range(1, 4):
        try:
            response = requests.post(
                API_BASE + "public/proxy-plans/" + slug + "/purchase/",
                json=body,
                headers=headers,
                timeout=90,
            )
        except requests.RequestException:
            if attempt == 3:
                raise
            time.sleep(3)
            continue

        if response.status_code == 409 and attempt < 3:
            time.sleep(3)
            continue

        response.raise_for_status()
        return response.json()


print(get_me())
print(
    purchase(
        "proxy-dan-cu-viettel",
        {
            "period_code": "daily",
            "quantity": 1,
            "selected_options": {"location_code": "17", "protocol": "http"},
        },
    )
)

const API_BASE = "https://api.proxyzing.com/api/v1/";
const API_KEY = process.env.PROXYZING_API_KEY;

let url = API_BASE + "proxy-orders/?page_size=100";

while (url) {
  const response = await fetch(url, { headers: { "X-API-Key": API_KEY } });
  const page = await response.json();

  for (const order of page.results) {
    console.log(order.id);
  }

  url = page.next;
}

import os

import requests

API_BASE = "https://api.proxyzing.com/api/v1/"
HEADERS = {"X-API-Key": os.environ["PROXYZING_API_KEY"]}

url = API_BASE + "proxy-orders/?page_size=100"

while url:
    page = requests.get(url, headers=HEADERS, timeout=30).json()

    for order in page["results"]:
        print(order["id"])

    url = page["next"]

Tôi làm mất API key thì phải làm sao?

Key đầy đủ chỉ hiển thị một lần lúc tạo và không xem lại được. Hãy xóa key cũ và tạo key mới.

Có dùng API key trong ứng dụng web hoặc mobile được không?

Không. Chỉ dùng key ở phía server của bạn, không đưa vào ứng dụng web hoặc mobile.

Giá khi mua được tính như thế nào?

Giá do server tự tính, bạn không gửi giá. Tổng tiền = unit_total × quantity (gói tính theo băng thông: price_per_gb × bandwidth_gb).

Mua thất bại thì có bị trừ tiền không?

Số dư không đủ hoặc dữ liệu sai thì không trừ tiền và không tạo đơn. Nếu xử lý đơn thất bại sau khi đã trừ tiền, hệ thống tự hoàn đúng số tiền đã trừ và đơn chuyển sang failed.

Request mua bị timeout thì có nên gửi lại không?

Có, gửi lại đúng request đó với cùng Idempotency-Key. Server không mua hoặc trừ tiền lần nữa. Nếu vẫn lỗi, kiểm tra GET /proxy-orders/?ordering=-created_at trước khi mua lại.

Proxy đã hết hạn có gia hạn được không?

Không. Proxy có expires_at nhỏ hơn thời điểm hiện tại không gia hạn được. API trả lỗi 400 với details.expires_at và không trừ tiền.