Tài liệu API

Tài liệu này chứa danh sách đầy đủ tất cả các endpoint API trong dự án ProxyTool, bao gồm các tham số, nội dung yêu cầu (request body) và các phản hồi dự kiến.

🛠 Cấu hình Middleware & Xác thực

Để sử dụng API, bạn cần nắm rõ các loại mã xác thực và tiêu đề (Headers) sau:

1. Các loại mã xác thực (Keys)

JWT Token: Nhận được sau khi gọi API /api/login. Có thời hạn 14 ngày.

Fixed API Key: Mã cố định được cấu hình trong file .env (Biến ALLOWED_API_KEY). Dùng để định danh các ứng dụng client hoặc webhook.

2. Cách gửi Tiêu đề (Headers)

Hệ thống sử dụng các tiêu đề sau để kiểm soát quyền truy cập:

Loại Endpoint	Header yêu cầu	Giá trị mẫu	Ghi chú
Quản trị (Users, Proxies...)	`Authorization`	`Bearer <JWT_TOKEN>`	Có thể dùng `ALLOWED_API_KEY` thay thế
Client (Get Proxy, Webhooks)	`Authorization`	`<ALLOWED_API_KEY>`	Không kèm tiền tố "Bearer "
Thông tin hệ thống (`/`)	`show-env`	`true`	(Tùy chọn) Hiển thị biến môi trường

🔐 Module API Chung (Auth & Registration)

Thẻ (Tag): api

Endpoint: POST /api/login

Mô tả: Xác thực người dùng và nhận mã JWT.

Yêu cầu (Body):

{
  "email": "admin@example.com",
  "password": "password123"
}

2. Đăng ký (Register)

Endpoint: POST /api/register

Mô tả: Tạo một người dùng quản trị mới (Mật khẩu sẽ được mã hóa bcrypt).

3. Lấy thông tin cá nhân (Get Me)

Endpoint: GET /api/me

Header: Authorization: Bearer <token>

👥 Module Người dùng (Users)

Thẻ (Tag): Users (🔐 Xác thực JWT hoặc API_KEY)

GET /api/users/users - Danh sách người dùng.

POST /api/users/users - Tạo người dùng (Admin).

PUT /api/users/users/:id - Cập nhật người dùng.

DELETE /api/users/users/:id - Xóa người dùng.

🌐 Module Proxy (Proxies)

Thẻ (Tag): Proxies (🔐 Xác thực JWT hoặc API_KEY)

1. Quản lý chung

GET /api/proxies/ - Danh sách proxy (Query get_full=true để xem hết).

POST /api/proxies/ - Thêm nhiều proxy (Mảng JSON).

PUT /api/proxies/:id - Cập nhật thông tin proxy.

DELETE /api/proxies/:id - Xóa 1 proxy.

POST /api/proxies/bulk-delete - Xóa nhiều proxy bằng mảng ID.

2. Nhập & Xử lý đặc biệt

POST /api/proxies/import - Nhập từ Excel/CSV (Multipart/form-data).

Nội dung file mẫu (CSV): Bạn có thể copy nội dung dưới đây, lưu thành file .csv để sử dụng:

host,port,username,password,area,rotate_url,provider,package_code,expired_at,is_active,disable_auto_rotate,rotate_time
103.116.12.1,8080,user01,pass01,vn,http://api.proxy.vn/rotate?key=abc,KiotProxy,PKG_VN_01,2025-12-31 23:59:59,true,false,60
104.22.33.44,9090,user02,pass02,global,http://api.global.com/rotate?key=xyz,KiotProxy,PKG_GLOBAL_01,2025-12-31 23:59:59,true,false,60

Ý nghĩa các cột:

host, port: Thông tin IP và Cổng.

area: Nhận giá trị vn hoặc global.

provider: Tên nhà cung cấp (Ví dụ: KiotProxy).

package_code: Mã gói (Ví dụ: PKG_VN_01).

expired_at: Định dạng YYYY-MM-DD.

POST /api/proxies/import-kiot - Tự động đồng bộ từ KiotProxy API.

POST /api/proxies/drop - Xóa sạch DB Proxy (Cẩn thận!).

⚡ Lấy Proxy (Dành cho Client/Tool)

Thẻ (Tag): Get proxy (🔑 Yêu cầu Fixed API Key và IP được phép)

1. Lấy một Proxy trống

Endpoint: GET /api/get-proxy/

Header: Authorization: <ALLOWED_API_KEY>

Query Params:

area (tùy chọn): "vn" hoặc "global".

🪝 Module Webhook

Thẻ (Tag): Webhooks (🔑 Yêu cầu Fixed API Key)

1. Trả lại Proxy

Endpoint: POST /webhook/return-proxy/:id

Header: Authorization: <ALLOWED_API_KEY>

Query Params:

key (bắt buộc): Mã session nhận được lúc lấy proxy để xác minh phiên dùng.

Tài liệu API

Tài liệu API#

🛠 Cấu hình Middleware & Xác thực#

1. Các loại mã xác thực (Keys)#

2. Cách gửi Tiêu đề (Headers)#

🔐 Module API Chung (Auth & Registration)#

1. Đăng nhập (Login)#

2. Đăng ký (Register)#

3. Lấy thông tin cá nhân (Get Me)#

👥 Module Người dùng (Users)#

🌐 Module Proxy (Proxies)#

1. Quản lý chung#

2. Nhập & Xử lý đặc biệt#

⚡ Lấy Proxy (Dành cho Client/Tool)#

1. Lấy một Proxy trống#

🪝 Module Webhook#

1. Trả lại Proxy#

Tài liệu API

🛠 Cấu hình Middleware & Xác thực

1. Các loại mã xác thực (Keys)

2. Cách gửi Tiêu đề (Headers)

🔐 Module API Chung (Auth & Registration)

1. Đăng nhập (Login)

2. Đăng ký (Register)

3. Lấy thông tin cá nhân (Get Me)

👥 Module Người dùng (Users)

🌐 Module Proxy (Proxies)

1. Quản lý chung

2. Nhập & Xử lý đặc biệt

⚡ Lấy Proxy (Dành cho Client/Tool)

1. Lấy một Proxy trống

🪝 Module Webhook

1. Trả lại Proxy