> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nexalayer.net/llms.txt
> Use this file to discover all available pages before exploring further.

# 接口参考

> ZTProxy 对外 API 接口参考。基础地址：https://backend.ztproxy.net/api

# 接口参考

基础地址：

```text theme={null}
https://backend.ztproxy.net/api
```

需要认证的接口必须携带：

```text theme={null}
Authorization: Bearer <token>
```

## 认证

### POST `/auth/login`

获取 JWT token。

```json 请求 theme={null}
{
  "username": "your_username",
  "password": "your_password"
}
```

```json 响应 theme={null}
{
  "code": 0,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": 1001,
      "username": "your_username",
      "balance": 1000,
      "status": "active"
    }
  }
}
```

## 用户

### POST `/open/app/user/v2`

在当前代理商账号下创建下级用户。

```json 请求 theme={null}
{
  "username": "sub_user_001",
  "password": "password123",
  "email": "user@example.com",
  "phone": "13812345678",
  "remark": "API sub-user",
  "balance": 0
}
```

| 字段         | 类型     |  必填 | 说明             |
| ---------- | ------ | :-: | -------------- |
| `username` | string |  是  | 3-50 个字符，必须唯一。 |
| `password` | string |  是  | 6-50 个字符。      |
| `email`    | string |  否  | 邮箱。            |
| `phone`    | string |  否  | 11 位手机号。       |
| `balance`  | number |  否  | 初始余额。          |

### GET `/open/app/user/balance/current`

查询当前登录用户余额。

```bash theme={null}
curl "$ZTPROXY_BASE/open/app/user/balance/current" \
  -H "Authorization: Bearer $ZTPROXY_TOKEN"
```

### GET `/open/app/agent/sub-users`

代理商查询自己的直属下级用户列表和余额。

```bash theme={null}
curl "$ZTPROXY_BASE/open/app/agent/sub-users?page=1&pageSize=20" \
  -H "Authorization: Bearer $ZTPROXY_TOKEN"
```

| 参数               | 类型      | 说明                               |
| ---------------- | ------- | -------------------------------- |
| `page`           | number  | 页码，默认 `1`。                       |
| `pageSize`       | number  | 每页数量，默认 `20`，最大 `100`。           |
| `search`         | string  | 按用户名、邮箱或手机号模糊搜索。                 |
| `status`         | string  | `active`、`disabled` 或 `deleted`。 |
| `includeDeleted` | boolean | 是否包含已删除账号，默认 `false`。            |

响应位于 `data.items`，兼容字段 `data.list` 返回同一列表。每个子账号包含 `id`、`username`、`email`、`phone`、`remark`、`status`、`balance`、`lumi_balance`、`ipweb_balance`、`total_recharge`、`total_consumption`、`agent_id`、`created_at` 和 `updated_at`。

### POST `/open/app/agent/sub-users/{user_id}/balance`

代理商调整自己的直属下级用户余额。

```json 请求 theme={null}
{
  "amount": 100,
  "remark": "API balance adjustment"
}
```

| 字段       | 类型     |  必填 | 说明                  |
| -------- | ------ | :-: | ------------------- |
| `amount` | number |  是  | 调整金额。正数增加余额，负数扣减余额。 |
| `remark` | string |  是  | 调整备注。               |

目标用户必须是当前代理商的直属下级用户，且扣减后余额不能小于 0。

### PATCH `/open/app/agent/sub-users/{user_id}/account`

代理商编辑自己的直属下级用户登录账号信息。

```json 请求 theme={null}
{
  "username": "sub_user_002",
  "password": "newPassword123"
}
```

| 字段         | 类型     |  必填 | 说明                                  |
| ---------- | ------ | :-: | ----------------------------------- |
| `username` | string |  否  | 新用户名，3-50 个字符，支持字母、数字、下划线和连字符，必须唯一。 |
| `password` | string |  否  | 新密码，6-50 个字符。                       |

`username` 和 `password` 至少传一个。此接口只修改 ZTProxy 登录账号，不修改供应商侧账号字段。

### PATCH `/open/app/agent/sub-users/{user_id}/status`

代理商启用或禁用自己的直属下级用户。

```json 请求 theme={null}
{
  "status": "disabled"
}
```

| 字段       | 类型     |  必填 | 说明                             |
| -------- | ------ | :-: | ------------------------------ |
| `status` | string |  是  | `active` 表示启用，`disabled` 表示禁用。 |

### DELETE `/open/app/agent/sub-users/{user_id}`

代理商软删除自己的直属下级用户。

```bash theme={null}
curl -X DELETE "$ZTPROXY_BASE/open/app/agent/sub-users/1001" \
  -H "Authorization: Bearer $ZTPROXY_TOKEN"
```

删除后账号状态为 `deleted`。此接口只用于删除直属下级普通用户。

## 产品与地区

### POST `/open/app/product/query-standard/v2`

查询可用产品、库存、价格和地区代码。

```json 请求 theme={null}
{
  "proxyType": 103,
  "standardCountryCode": "US",
  "standardCityCode": "NEW_YORK",
  "language": "zh"
}
```

| 字段                    | 类型                 |  必填 | 说明                           |
| --------------------- | ------------------ | :-: | ---------------------------- |
| `proxyType`           | number 或 number\[] |  否  | 代理类型筛选，默认 `103`。             |
| `productNo`           | string             |  否  | 产品编号。                        |
| `standardCountryCode` | string             |  否  | 标准国家代码，使用 ISO2，如 `US`、`JP`。  |
| `standardCityCode`    | string             |  否  | 标准城市代码，如 `NEW_YORK`。         |
| `language`            | string             |  否  | 名称语言，支持 `zh` 或 `en`，默认 `en`。 |

响应项通常包含 `productId`、`name`、`proxyType`、`product_type` / `productType`、`project_list` / `projects` / `projectList`、`stock`、`countryCode`、`countryName`、`countryNameEn`、`countryNameZh`、`cityCode`、`cityName`、`cityNameEn`、`cityNameZh`、`nameLanguage`、`duration`、`unit` 和 `price` 等字段。

### 地区字段说明

创建静态订单时，请使用产品查询接口返回的 `productId`、`countryCode` 和 `cityCode`。

### 共享静态和独享静态判别

`product_type` / `productType` 为 `2` 或 `shared` 表示共享静态；`1` 或 `exclusive` 表示独享静态。若产品响应的 `project_list` / `projects` / `projectList` 非空，也应按共享静态处理。共享静态创建订单时必须传 `projectId`；独享静态不需要传。`staticType` 表示静态资源/供应商类型，不用于判别共享或独享。

### GET `/open/app/product/ip-ranges/v2`

查询指定国家、城市或产品下可用的 CIDR/IP 段列表。

```bash theme={null}
curl "$ZTPROXY_BASE/open/app/product/ip-ranges/v2?proxyType=103&countryCode=<countryCode-from-product>&cityCode=<cityCode-from-product>" \
  -H "Authorization: Bearer $ZTPROXY_TOKEN"
```

| 参数                | 类型      |  必填 | 说明                           |
| ----------------- | ------- | :-: | ---------------------------- |
| `proxyType`       | number  |  否  | 产品代理类型，默认 `103`。             |
| `productNo`       | string  |  否  | 产品编号。                        |
| `areaCode`        | string  |  否  | 区域代码。                        |
| `countryCode`     | string  |  否  | 国家代码。                        |
| `cityCode`        | string  |  否  | 城市代码。                        |
| `includeDisabled` | boolean |  否  | 是否包含停用 IP 段，默认 `false`。      |
| `language`        | string  |  否  | 名称语言，支持 `zh` 或 `en`，默认 `en`。 |

响应数据位于 `data.items`，每个产品项包含 `product_type` / `productType`、`project_list` / `projects` / `projectList`、`countryName`、`countryNameEn`、`countryNameZh`、`stateName`、`cityName`、`cityNameEn`、`cityNameZh`、`nameLanguage` 和 `ipRanges`。`ipRanges[].ipRange` 即可用 CIDR/IP 段。

## 订单

### POST `/open/app/order/create/v2`

创建动态代理订单。

```json 动态代理请求 theme={null}
{
  "orderType": "dynamic_proxy",
  "poolId": "<dynamic_product_no>",
  "trafficAmount": 1,
  "unitPrice": 5,
  "totalAmount": 5,
  "remark": "API dynamic order",
  "userId": 1001,
  "ipCount": 1,
  "duration": 30,
  "unit": 1
}
```

### GET `/dynamic`

查询动态订单列表。支持 `page`、`page_size`、`user_id`、`order_no`、`pool_type` 等参数。

### GET `/dynamic/{order_id}`

按订单 ID 查询动态订单详情。

### GET `/dynamic/order-info/{order_no}`

按订单号或应用订单号查询动态订单详情。

### POST `/business/dynamic-proxy/extract`

提取动态代理。必填 `productNo` 和 `proxyType`，可通过 `extractConfig.method` 指定提取方式。

### GET `/user/{user_id}/products-flow`

查询用户所有产品的剩余流量。

### GET `/user/{user_id}/remaining-flow/{product_no}`

查询用户指定动态产品的剩余流量。

### 动态子账户

| 方法    | 接口                 | 说明 |
| ----- | ------------------ | -- |
| 能力    | 说明                 |    |
| ---   | ---                |    |
| 创建子账户 | 为动态代理主账户创建子账户。     |    |
| 查询子账户 | 查询可见子账户及实时流量。      |    |
| 调整流量  | 在主账户和子账户之间分配或回收流量。 |    |
| 修改状态  | 启用或停用子账户。          |    |
| 修改密码  | 修改子账户代理密码。         |    |
| 删除子账户 | 停用并删除子账户记录。        |    |

详见 [动态子账户](/sessions/dynamic-sub-users)。

### POST `/open/app/static/order/create-standard/v2`

创建静态代理订单。标准静态创建接口采用异步受理模式：校验通过后先返回本系统订单号，后台继续完成供应商开通。

```json 标准静态代理请求 theme={null}
{
  "orderType": "static_proxy",
  "poolId": "ZT_US_New York City_2",
  "trafficAmount": null,
  "unitPrice": 10,
  "totalAmount": 10,
  "remark": "API static order",
  "userId": 1001,
  "countryCode": "US",
  "cityCode": "NEW_YORK",
  "staticType": "isp",
  "ipCount": 1,
  "cycleTimes": 1,
  "duration": 30,
  "unit": 1
}
```

如果地区不适用于当前产品，接口会返回 `location_not_supported_for_product`，并提示该产品支持的地区。

| 字段               | 类型     |  必填 | 说明                       |
| ---------------- | ------ | :-: | ------------------------ |
| `orderType`      | string |  是  | 静态代理使用 `static_proxy`。   |
| `poolId`         | string |  是  | 产品编号。                    |
| `userId`         | number |  是  | 目标用户 ID。代理商只能为自己的下级用户下单。 |
| `unitPrice`      | number |  是  | 单价。传 `0` 时后端可能按配置价格计算。   |
| `totalAmount`    | number |  是  | 总金额。传 `0` 时部分产品支持后端计算。   |
| `regionCode`     | string |  否  | 区域代码。                    |
| `countryCode`    | string |  否  | 国家代码。                    |
| `cityCode`       | string |  否  | 城市代码。                    |
| `staticType`     | string |  否  | 静态资源类型。                  |
| `ipCount`        | number |  是  | IP 数量。                   |
| `cycleTimes`     | number |  是  | 购买周期数。                   |
| `duration`       | number |  是  | 时长。                      |
| `unit`           | number |  是  | `1` = 天，`3` = 月，`4` = 年。 |
| `cidrBlocks`     | array  |  否  | 支持 CIDR 分配的产品可传网段和数量。    |
| `assignedIp`     | string |  否  | 指定单个 IP。                 |
| `assignedIpList` | array  |  否  | 指定多个 IP。                 |
| `projectId`      | string |  否  | 共享静态代理产品的项目/业务类型。        |

受理成功响应示例：

```json theme={null}
{
  "code": 0,
  "msg": "订单已受理，正在处理中，请通过订单列表查询最终状态",
  "data": {
    "orderNo": "STA20260611102030abc123",
    "order_no": "STA20260611102030abc123",
    "appOrderNo": "APP20260611102030def456",
    "app_order_no": "APP20260611102030def456",
    "status": "processing",
    "queued": true,
    "async": true
  }
}
```

`queued: true` 表示订单已进入后台处理。请使用返回的 `orderNo` 查询 `/open/app/static/order/list/v2` 获取最终状态、供应商订单号和代理实例信息。

### GET `/open/app/static/order/list/v2`

查询静态订单和代理实例。

```bash theme={null}
curl "$ZTPROXY_BASE/open/app/static/order/list/v2?page=1&pageSize=10&status=active" \
  -H "Authorization: Bearer $ZTPROXY_TOKEN"
```

| 参数                              | 类型      | 说明                     |
| ------------------------------- | ------- | ---------------------- |
| `page`                          | number  | 页码，默认 `1`。             |
| `pageSize` / `page_size`        | number  | 每页数量，最大 `100`。         |
| `status`                        | string  | 订单状态筛选。                |
| `filter`                        | string  | 控制台使用的业务筛选。            |
| `user_id`                       | number  | 用户筛选。                  |
| `search`                        | string  | 搜索订单号、IP、端口、用户名、密码或备注。 |
| `region`                        | string  | 地区模糊筛选。                |
| `created_start` / `created_end` | string  | 创建时间范围。                |
| `expire_start` / `expire_end`   | string  | 到期时间范围。                |
| `show_recycle_bin`              | boolean | 普通用户是否查看回收站实例。         |

### GET `/open/app/static/order/statistics`

查询静态订单各状态数量。

### POST `/open/app/static/order/renew`

静态代理订单或实例续费。可传 `order_no` / `orderNo` / `order_id` 指定目标订单；未传 `instances` 时默认续费该订单下所有实例。`duration: 30, unit: 1, cycleTimes: 1` 按 1 个月处理。

### POST `/open/app/static/order/{order_no}/cancel`

释放或取消静态订单。

## 仪表盘和记录

### GET `/open/app/dashboard/info/v2`

查询当前账号的余额、资源数量和仪表盘概览。

### GET `/open/app/user/transactions`

查询消费记录。

| 参数                        | 类型     | 说明                    |
| ------------------------- | ------ | --------------------- |
| `page`                    | number | 页码。                   |
| `page_size`               | number | 每页数量，最大 `100`。        |
| `type`                    | string | 交易类型。                 |
| `order_type`              | string | `static` 或 `dynamic`。 |
| `start_date` / `end_date` | string | 日期范围，格式 `YYYY-MM-DD`。 |
| `username`                | string | 用户名筛选。                |
| `order_no`                | string | 订单号筛选。                |
| `keyword`                 | string | 搜索备注、类型、订单号或用户名。      |
| `target_user_id`          | number | 目标用户筛选。               |

### GET `/transaction/agent/transactions`

查询当前账号及下级用户权限范围内的充值和余额调整记录。

## USDT 充值

| 方法     | 接口                   | 说明                     |
| ------ | -------------------- | ---------------------- |
| `GET`  | `/usdt/wallet-info`  | 获取 USDT TRC20 收款钱包和汇率。 |
| `POST` | `/usdt/create-order` | 创建 USDT TRC20 充值订单。    |
| `GET`  | `/usdt/check-status` | 查询充值订单状态并自动检测链上转账。     |
| `GET`  | `/usdt/orders`       | 查询充值订单列表。              |
| `POST` | `/usdt/cancel-order` | 取消待支付充值订单。             |

详见 [USDT 充值](/billing/usdt)。