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

接口参考

API 基础地址：

https://backend.ztproxy.net/api

中国大陆和海外网络均使用此地址。

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

Authorization: Bearer <token>

认证

POST /auth/login

获取 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": "[email protected]",
  "phone": "13812345678",
  "remark": "API sub-user",
  "balance": 0
}

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"

响应位于 data.items，兼容字段 data.list 返回同一列表。每个子账号包含 id、username、email、phone、remark、status、balance、lumi_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"
}

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

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

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

{
  "username": "sub_user_002",
  "password": "newPassword123"
}

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

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

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

{
  "status": "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"
}

响应项通常包含 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"

响应数据位于 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": 3,
  "unitPrice": 0,
  "totalAmount": 0,
  "remark": "API dynamic order",
  "userId": 1001,
  "ipCount": 1,
  "duration": 30,
  "unit": 1
}

trafficAmount 的单位为 GB。unitPrice 和 totalAmount 为兼容字段，请传 0；动态订单会复用网页开通逻辑，由服务端按用户、代理层级和流量阶梯重新计价，并统一完成余额预检、资源开通及账务记录。客户端提交的价格和金额不会作为扣款依据。

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

通过 API 直接提取动态代理。当前公开接入仅说明动态资源2（dynamic_2）；推荐使用账户级提取接口，并按 动态资源2接入指南 查询标准地区、生成粘性会话和读取结构化代理凭据。

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，并提示该产品支持的地区。

受理成功响应示例：

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

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

查询消费记录。

GET /transaction/agent/transactions

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

USDT 充值

详见 USDT 充值。