TÀI LIỆU API

Điều khiển proxy bằng code

Dành cho lập trình viên muốn tự động hóa việc lấy IP, đổi IP và quản lý key proxy. Hỗ trợ SDK TypeScript và gọi trực tiếp qua HTTP/cURL — copy code là chạy.

SDK TypeScript

npm install @nestproxy/sdk — gọi API type-safe, có autocomplete đầy đủ, chạy ngay không cần cấu hình.

Chọn IP theo tỉnh

Truyền province_id khi lấy IP để nhận proxy ở đúng tỉnh thành bạn cần. Hỗ trợ 63 tỉnh.

Auth chỉ 1 header

Gửi API Key qua header user-api-key — không cần OAuth, không cần token, đơn giản nhất có thể.

BẮT ĐẦU NHANH

3 bước để gọi API lấy proxy

Bạn chỉ cần 2 thứ: API Key (lấy ở Dashboard → Tài khoản) và Proxy Key (lấy ở Dashboard → Key của tôi)

1

Lấy API Key & Proxy Key

Đăng nhập Dashboard. Vào Tài khoản để copy API Key. Vào Key của tôi để lấy Proxy Key (hoặc mua key nếu chưa có).

# API Key → dùng cho header xác thực
# Proxy Key → dùng để chỉ định key nào cần lấy/đổi IP
2

Gọi API lấy IP proxy mới

Gọi endpoint /proxy/available với proxy_key của bạn. Server sẽ trả về IP:Port để kết nối.

curl "https://nestproxy.com/api/client/proxy/available?proxy_key=YOUR_KEY"
3

Đổi IP khi cần

Khi muốn đổi IP, gọi /proxy/remove để xóa IP cũ, sau đó gọi lại /proxy/available để lấy IP mới.

# Bước a: Xóa IP cũ
curl -X POST "https://nestproxy.com/api/client/proxy/remove?proxy_key=YOUR_KEY"

# Bước b: Lấy IP mới
curl "https://nestproxy.com/api/client/proxy/available?proxy_key=YOUR_KEY"

Mẹo: Đổi IP = 2 bước

Luôn nhớ: Xóa IP cũ trước (POST /proxy/remove), rồi mới lấy IP mới (GET /proxy/available). Nếu gọi lấy IP mới mà chưa xóa IP cũ, server sẽ trả về IP giống lần trước.

DANH SÁCH ENDPOINT

Tất cả 15 endpoint API

Chia thành 4 nhóm: Thao tác proxy, Quản lý key, Thông tin chung và Tài khoản. Mỗi endpoint kèm mô tả chi tiết và tham số cần truyền.

Cách xác thực (Authentication)

Endpoint có nhãn Cần API Key yêu cầu bạn gửi header sau trong mỗi request:

user-api-key: YOUR_API_KEY

📍 Lấy API Key ở đâu? Đăng nhập → Dashboard → Tài khoản → Copy API Key.
Endpoint có nhãn Công khai không cần gửi header — gọi trực tiếp là được.

GET
/api/client/proxy/available
Lấy IP mới Công khai

Gọi để nhận 1 IP proxy mới. Trả về IP:Port để kết nối.

Tham số: proxy_key, province_id?
GET
/api/client/proxy/current
Xem IP hiện tại Công khai

Kiểm tra IP đang sử dụng và thời gian có thể đổi IP tiếp.

Tham số: proxy_key
POST
/api/client/proxy/remove
Xóa IP cũ (để đổi IP) Công khai

Xóa IP hiện tại. Sau đó gọi 'Lấy IP mới' để nhận IP khác.

Tham số: proxy_key
GET
/api/client/key/detail
Chi tiết 1 key Công khai

Xem trạng thái, loại key, ngày hết hạn của 1 key cụ thể.

Tham số: proxy_key
GET
/api/client/key/list
Danh sách tất cả key Cần API Key

Xem toàn bộ key đang có trong tài khoản của bạn.

POST
/api/client/key/buy
Mua key mới Cần API Key

Mua key proxy mới, trừ tiền từ số dư tài khoản.

Tham số: body: keyType, quantity?, duration?
POST
/api/client/key/renewal
Gia hạn key Cần API Key

Gia hạn thêm ngày sử dụng cho key sắp hết hạn.

Tham số: body: proxyKey, duration?
POST
/api/client/key/remove
Xóa key Cần API Key

Xóa vĩnh viễn key không dùng nữa khỏi tài khoản.

Tham số: proxy_key
GET
/api/client/provinces
Danh sách tỉnh thành Công khai

Lấy danh sách 63 tỉnh thành kèm ID. Dùng ID để chọn vùng khi lấy IP.

Tham số: search_text?
GET
/api/client/pricing
Xem bảng giá Công khai

Xem giá các loại key (Thường, VIP, VIP 1h) theo ngày.

Tham số: domain?
GET
/api/client/user/current
Thông tin tài khoản Cần API Key

Xem tên, email, số dư và thông tin tài khoản hiện tại.

POST
/api/client/gift-code/redeem
Đổi Gift Code Cần API Key

Nhập gift code để nạp tiền vào tài khoản.

Tham số: body: code
GET
/api/client/ip-history
Lịch sử đổi IP Cần API Key

Xem lại tất cả các lần lấy IP và đổi IP trước đó.

Tham số: page?, limit?
GET
/api/client/key-orders
Lịch sử mua key Cần API Key

Xem lại các đơn mua key và gia hạn key.

Tham số: page?, limit?
GET
/api/client/deposits
Lịch sử nạp tiền Cần API Key

Xem lại tất cả giao dịch nạp tiền vào tài khoản.

Tham số: page?, limit?

Code mẫu đầy đủ

Copy và chỉnh sửa cho phù hợp với dự án của bạn. Code có comment tiếng Việt chi tiết từng bước.

typescript — @nestproxy/sdk
1import { NestProxySDK } from '@nestproxy/sdk';
2
3// ═══ Bước 1: Khởi tạo SDK ═══
4// apiKey lấy ở Dashboard → Tài khoản → API Key
5const sdk = new NestProxySDK({
6 apiKey: 'YOUR_API_KEY',
7});
8
9// ═══ Bước 2: Lấy proxy IP mới ═══
10// Truyền vào proxy key (lấy ở Dashboard → Key của tôi)
11const proxy = await sdk.getNewIP('your-proxy-key');
12console.log(proxy.proxy); // "103.1.2.3:8080" ← IP:Port để dùng
13console.log(proxy.province); // "Thành phố Hà Nội"
14
15// Muốn lấy IP ở tỉnh cụ thể? Truyền thêm provinceId
16// (provinceId = 1 là Hà Nội, xem danh sách đầy đủ bên dưới)
17const proxyHN = await sdk.getNewIP('your-proxy-key', 1);
18
19// ═══ Bước 3: Đổi IP khi cần ═══
20// Bước 3a: Xóa IP cũ
21await sdk.removeOldIP('your-proxy-key');
22// Bước 3b: Lấy IP mới
23const newProxy = await sdk.getNewIP('your-proxy-key');
24
25// ═══ Xem IP đang dùng ═══
26const current = await sdk.getCurrentIP('your-proxy-key');
27console.log(current.proxy); // IP hiện tại
28console.log(current.canChangeAt); // Thời điểm sớm nhất được đổi IP
29
30// ═══ Các thao tác khác ═══
31
32// Lấy bảng giá
33const pricing = await sdk.getPricing();
34
35// Lấy danh sách 63 tỉnh thành (dùng để chọn vùng)
36const provinces = await sdk.getProvinces();
37// Tìm theo tên
38const filtered = await sdk.getProvinces('Hà Nội');
39
40// Xem danh sách key đang có
41const keys = await sdk.getKeyList();
42
43// Mua key mới (trừ tiền từ số dư tài khoản)
44const newKeys = await sdk.buyKey({
45 keyType: 'NORMAL', // 'NORMAL' | 'VIP' | 'VIP_1H'
46 quantity: 2, // mua 2 key
47 duration: 30, // sử dụng 30 ngày
48});
49
50// Gia hạn key sắp hết hạn
51const renewed = await sdk.renewKey({
52 proxyKey: 'proxy-key-uuid',
53 duration: 7, // thêm 7 ngày
54});
55
56// Xem thông tin tài khoản + số dư
57const user = await sdk.getCurrentUser();
58console.log(user.balance); // số dư (VNĐ)
59
60// Đổi gift code lấy tiền
61const gift = await sdk.redeemGiftCode('GIFT-CODE-ABC');
62
63// Xem lịch sử
64const ipHistory = await sdk.getIpHistory(); // lịch sử đổi IP
65const orders = await sdk.getKeyOrders(); // lịch sử mua key
66const deposits = await sdk.getDeposits(); // lịch sử nạp tiền

📦 Cài đặt SDK (chạy lệnh này trong terminal dự án của bạn):

$ npm install @nestproxy/sdk

Dữ liệu trả về (Response)

Đây là cấu trúc JSON mà API trả về. Bạn sẽ nhận được đúng các trường này khi gọi thành công.

ProxyInfo

Nhận được khi gọi lấy IP mới hoặc xem IP hiện tại

{
  proxy: "103.1.2.3:8080",   // ← IP:Port để kết nối
  province: "TP Hà Nội",     // ← Tỉnh thành của IP
  provinceId: 1               // ← ID tỉnh
}

KeyDetail

Nhận được khi xem chi tiết 1 key proxy

{
  id: 1,
  proxyKey: "uuid-string",   // ← Mã key để kết nối
  keyType: "NORMAL",         // ← Loại: NORMAL / VIP / VIP_1H
  isActive: true,            // ← Đang hoạt động?
  expiredAt: "2025-04-01",   // ← Ngày hết hạn
  createdAt: "2025-03-01"    // ← Ngày tạo
}

UserInfo

Nhận được khi xem thông tin tài khoản

{
  id: 1,
  userName: "john",
  email: "john@mail.com",
  balance: 500000,           // ← Số dư (VNĐ)
  role: "USER",
  apiKey: "your-api-key",    // ← API Key của bạn
  paymentCode: "NP12345"     // ← Mã nạp tiền
}

Province

Nhận được khi lấy danh sách tỉnh thành

{
  id: 1,                     // ← province_id dùng để chọn vùng
  name: "TP Hà Nội",         // ← Tên tỉnh thành
  level: "Thành phố TW"      // ← Cấp hành chính
}

Cần hỗ trợ tích hợp?

Nếu bạn gặp lỗi hoặc cần giúp đỡ khi tích hợp API, liên hệ đội ngũ kỹ thuật qua Zalo — chúng tôi sẽ hỗ trợ tận tình.

Chat Zalo với kỹ thuật