# 🔌 OpenAPI

EProxies cung cấp 5 endpoint HTTP (trích xuất proxy ở chế độ danh sách trắng và quản lý danh sách trắng). Trang này là tra cứu nhanh; xem chi tiết tại [Trích xuất qua API (chế độ danh sách trắng)](https://www.eproxies.io/docs/usage/api-extraction).

> Định nghĩa máy đọc được: [openapi.json](https://www.eproxies.io/docs/openapi.json) — đặc tả OpenAPI 3.0, nhập trực tiếp vào Postman / Swagger UI / Insomnia, hoặc đưa cho AI agent để gọi tự động.

## Thông tin cơ bản

| Mục | Giá trị |
| --- | --- |
| Base URL | `https://api.eproxies.net` |
| Xác thực (trích xuất) | Yêu cầu phải xuất phát từ **IP trong danh sách trắng**; không cần thông tin đăng nhập |
| Xác thực (quản lý) | Tham số `userName` + `userKeyValue` (khóa người dùng, lấy ở bảng điều khiển) |
| Cổng proxy | `proxy.eproxies.net:23333` (HTTP/HTTPS/SOCKS5 — không thuộc HTTP API này) |

## Danh sách endpoint

### `GET /gateway_api/extract_ip`

Trích xuất proxy — Trích xuất một loạt endpoint proxy. Yêu cầu phải xuất phát từ IP trong danh sách trắng; proxy trả về dùng trực tiếp, không cần thông tin đăng nhập.

**Tham số yêu cầu**

| Trường | Kiểu | Bắt buộc | Giá trị hợp lệ | Mô tả |
| --- | --- | --- | --- | --- |
| `count` | integer | Có | `1` ~ N | Số lượng proxy cần trích xuất |
| `country` | string | Không | `US` `GB` `JP` … / `Global` | Mã quốc gia ISO 3166-1 alpha-2; `Global` = mọi quốc gia |
| `protocol` | string | Không | `http` / `socks5` | Giao thức proxy |
| `format` | string | Không | `txt` / `json` | Định dạng phản hồi; `json` trả về mảng đối tượng, `txt` trả về dòng văn bản |
| `separator` | string | Không | `crlf` `br` `cr` `lf` `tab` | Dấu phân cách cho định dạng `txt`: lần lượt `\r\n`, `</br>`, `\r`, `\n`, `\t` |
| `st` | string | Không | — | Dấu phân cách tùy chỉnh; thay thế `separator` nếu có |
| `session` | string | Không | `sticky` / `random` | Loại IP: `sticky` dùng lại cùng nhóm IP, `random` trả về ngẫu nhiên |

**Trường phản hồi**

| Trường | Kiểu | Mô tả |
| --- | --- | --- |
| `ipAddress` | string | Địa chỉ IP proxy |
| `portValue` | integer | Cổng proxy |

Với `format=json` phản hồi là mảng các đối tượng trên; với `format=txt` là các dòng `IP:cổng` phân tách bởi `separator`.

**Ví dụ**

```bash
curl "https://api.eproxies.net/gateway_api/extract_ip?count=10&country=US&protocol=http&format=json&session=sticky"
```

```json
[
  { "ipAddress": "203.0.113.10", "portValue": 23333 },
  { "ipAddress": "203.0.113.11", "portValue": 23333 }
]
```

### `GET /gateway_api/country-list`

Danh sách quốc gia hỗ trợ — Liệt kê mọi quốc gia khả dụng cho trích xuất ở chế độ danh sách trắng.

**Tham số yêu cầu**

Không có tham số yêu cầu.

**Trường phản hồi**

| Trường | Kiểu | Mô tả |
| --- | --- | --- |
| `country` | string | Mã ISO 3166-1 alpha-2 — dùng làm tham số `country` của `extract_ip` |
| `name` | string | Tên quốc gia |
| `flag_url` | string | URL biểu tượng cờ |

**Ví dụ**

```bash
curl "https://api.eproxies.net/gateway_api/country-list"
```

```json
[
  { "country": "US", "name": "United States", "flag_url": "https://file.eproxies.net/flags/us.png" }
]
```

### `GET /gateway_api/add-ip`

Thêm IP vào danh sách trắng — Thêm một IP đầu ra vào danh sách trắng; IP đó sau đó có thể trích xuất proxy không cần thông tin đăng nhập.

**Tham số yêu cầu**

| Trường | Kiểu | Bắt buộc | Giá trị hợp lệ | Mô tả |
| --- | --- | --- | --- | --- |
| `userName` | string | Có | — | Tên người dùng tài khoản |
| `userKeyValue` | string | Có | — | Khóa người dùng, lấy ở bảng điều khiển |
| `ipAddress` | string | Có | — | Địa chỉ IP cần thêm vào danh sách trắng |

**Trường phản hồi**

Trả về đối tượng kết quả thao tác; căn cứ theo phản hồi thực tế.

**Ví dụ**

```bash
curl "https://api.eproxies.net/gateway_api/add-ip?userName=USERNAME&userKeyValue=USER_KEY&ipAddress=203.0.113.10"
```

### `GET /gateway_api/del-ip`

Xóa IP khỏi danh sách trắng — Xóa một IP khỏi danh sách trắng; IP đó không còn trích xuất được nếu không có thông tin đăng nhập.

**Tham số yêu cầu**

| Trường | Kiểu | Bắt buộc | Giá trị hợp lệ | Mô tả |
| --- | --- | --- | --- | --- |
| `userName` | string | Có | — | Tên người dùng tài khoản |
| `userKeyValue` | string | Có | — | Khóa người dùng, lấy ở bảng điều khiển |
| `ipAddress` | string | Có | — | IP cần xóa khỏi danh sách trắng |

**Trường phản hồi**

Trả về đối tượng kết quả thao tác; căn cứ theo phản hồi thực tế.

**Ví dụ**

```bash
curl "https://api.eproxies.net/gateway_api/del-ip?userName=USERNAME&userKeyValue=USER_KEY&ipAddress=203.0.113.10"
```

### `GET /gateway_api/lists-ip`

Xem danh sách trắng — Liệt kê mọi mục danh sách trắng của tài khoản hiện tại.

**Tham số yêu cầu**

| Trường | Kiểu | Bắt buộc | Giá trị hợp lệ | Mô tả |
| --- | --- | --- | --- | --- |
| `userName` | string | Có | — | Tên người dùng tài khoản |
| `userKeyValue` | string | Có | — | Khóa người dùng, lấy ở bảng điều khiển |

**Trường phản hồi**

| Trường | Kiểu | Mô tả |
| --- | --- | --- |
| `ipAddress` | string | IP trong danh sách trắng |
| `remarkText` | string | Ghi chú |

**Ví dụ**

```bash
curl "https://api.eproxies.net/gateway_api/lists-ip?userName=USERNAME&userKeyValue=USER_KEY"
```

## Gọi nhanh

```bash
# Trích xuất 10 proxy HTTP của Mỹ (JSON, IP cố định)
curl "https://api.eproxies.net/gateway_api/extract_ip?count=10&country=US&protocol=http&format=json&session=sticky"

# Thêm IP máy chủ hiện tại vào danh sách trắng
curl "https://api.eproxies.net/gateway_api/add-ip?userName=USERNAME&userKeyValue=USER_KEY&ipAddress=203.0.113.10"
```

## Dùng trong AI Agent

Đưa địa chỉ đặc tả cho agent, nó sẽ tự suy ra toàn bộ tham số và cấu trúc phản hồi:

```
https://www.eproxies.io/docs/openapi.json
```

Kết hợp với [Bảng tra cứu nhanh cho Agent](https://www.eproxies.io/docs/agent-reference) (cú pháp tham số username của cổng proxy) là đủ toàn bộ thông tin tích hợp.