接口参考

基础地址：

https://backend.ztproxy.net/api

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

Authorization: Bearer <token>

认证

获取 JWT token。

请求

{
  "username": "your_username",
  "password": "your_password"
}

响应

{
  "code": 0,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": 1001,
      "username": "your_username",
      "balance": 1000,
      "status": "active"
    }
  }
}

用户

POST `/open/app/user/v2`

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

请求

{
  "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`

查询当前登录用户余额。

curl "$ZTPROXY_BASE/open/app/user/balance/current" \
  -H "Authorization: Bearer $ZTPROXY_TOKEN"

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

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

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`

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

请求

{
  "amount": 100,
  "remark": "API balance adjustment"
}

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

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

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

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

请求

{
  "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`

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

请求

{
  "status": "disabled"
}

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

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

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

curl -X DELETE "$ZTPROXY_BASE/open/app/agent/sub-users/1001" \
  -H "Authorization: Bearer $ZTPROXY_TOKEN"

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

产品与地区

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

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

请求

{
  "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 段列表。

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`

创建动态代理订单。

动态代理请求

{
  "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}`

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

动态子账户

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

详见动态子账户。

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

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

标准静态代理请求

{
  "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	否	共享静态代理产品的项目/业务类型。

受理成功响应示例：

{
  "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`

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

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 充值。

​接口参考

​认证

​POST /auth/login

​用户

​POST /open/app/user/v2

​GET /open/app/user/balance/current

​GET /open/app/agent/sub-users

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

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

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

​DELETE /open/app/agent/sub-users/{user_id}

​产品与地区

​POST /open/app/product/query-standard/v2

​地区字段说明

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

​GET /open/app/product/ip-ranges/v2

​订单

​POST /open/app/order/create/v2

​GET /dynamic

​GET /dynamic/{order_id}

​GET /dynamic/order-info/{order_no}

​POST /business/dynamic-proxy/extract

​GET /user/{user_id}/products-flow

​GET /user/{user_id}/remaining-flow/{product_no}

​动态子账户

​POST /open/app/static/order/create-standard/v2

​GET /open/app/static/order/list/v2

​GET /open/app/static/order/statistics

​POST /open/app/static/order/renew

​POST /open/app/static/order/{order_no}/cancel

​仪表盘和记录

​GET /open/app/dashboard/info/v2

​GET /open/app/user/transactions

​GET /transaction/agent/transactions

​USDT 充值