购买动态资源2、选择地区、提取代理并查询账户和流量。基础地址：https://backend.ztproxy.net/api

API 基础地址

https://backend.ztproxy.net/api

全球用户统一使用此地址。需要认证的接口必须携带有效的访问令牌。

动态资源2接入指南

动态资源2是按流量计费的动态代理产品。完整调用流程为：

1. 登录并获取 Bearer Token。

2. 使用公开产品号 dynamic_2 购买流量。

3. 从购买响应中保存 accountId。

4. 按需查询支持的国家、州/省和城市。

5. 使用 accountId 提取代理凭据。

6. 查询账户状态和流量用量。

所有示例都使用以下基础地址和认证信息：

export ZTPROXY_BASE="https://backend.ztproxy.net/api"
export ZTPROXY_TOKEN="<token>"

Token 的获取方式见认证。请只在服务端保存 Token 和代理密码，不要写入浏览器代码、公开仓库或日志。

1. 购买动态资源2

普通用户只能为自己购买；代理商只能为直属下级用户购买。userId 应填写最终使用资源的站内用户 ID。

curl -X POST "$ZTPROXY_BASE/open/app/order/create/v2" \
  -H "Authorization: Bearer $ZTPROXY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orderType": "dynamic_proxy",
    "poolId": "dynamic_2",
    "trafficAmount": 3,
    "userId": 1001,
    "unitPrice": 0,
    "totalAmount": 0,
    "ipCount": 1,
    "duration": 30,
    "unit": 1,
    "remark": "API dynamic resource 2 order"
  }'

trafficAmount 的单位是 GB，必须大于 0。unitPrice 和 totalAmount 是兼容字段，请传 0；实际价格和扣款金额由服务端按用户角色与价格配置计算。

成功响应示例：

{
  "code": 0,
  "msg": "动态IP池2开通成功",
  "data": {
    "orderNo": "DYN2...",
    "accountId": 123,
    "productNo": "dynamic_2",
    "productName": "动态IP池2",
    "limitBytes": 3000000000,
    "status": "active"
  }
}

请保存 data.accountId。后续账户详情、代理提取和用量查询均使用此 ID。limitBytes、usedBytes 和 todayUsedBytes 都以字节为单位，平台按 1 GB = 1,000,000,000 bytes 换算。

2. 查询动态资源账户

列出当前 Token 有权访问的动态资源2账户：

curl "$ZTPROXY_BASE/business/dynamic-accounts" \
  -H "Authorization: Bearer $ZTPROXY_TOKEN"

查询指定账户的实时状态与流量：

curl "$ZTPROXY_BASE/business/dynamic-accounts/123" \
  -H "Authorization: Bearer $ZTPROXY_TOKEN"

常用账户字段：

字段	说明
`id`	动态资源账户 ID，即提取接口使用的 `accountId`。
`productNo`	固定为 `dynamic_2`。
`status`	`active` 可用、`paused` 已暂停、`disabled` 已停用。
`limitBytes`	总流量额度，单位为字节。
`usedBytes`	累计已用流量，单位为字节。
`todayUsedBytes`	当日已用流量，单位为字节。

3. 查询可用地区

不传地区时将使用全球随机 IP。需要定向时，应先查询平台提供的标准地区名称，不要自行猜测州/省或城市拼写。

查询国家：

curl "$ZTPROXY_BASE/business/dynamic-accounts/locations/countries" \
  -H "Authorization: Bearer $ZTPROXY_TOKEN"

国家响应中的 code 是提取时使用的两位国家代码，例如 US。

查询州/省：

curl "$ZTPROXY_BASE/business/dynamic-accounts/locations/regions?country=US" \
  -H "Authorization: Bearer $ZTPROXY_TOKEN"

查询城市：

curl "$ZTPROXY_BASE/business/dynamic-accounts/locations/cities?country=US&region=California" \
  -H "Authorization: Bearer $ZTPROXY_TOKEN"

地区参数必须按国家 → 州/省 → 城市的层级传递：只选国家时可不传 state 和 city；传 city 时必须同时传 country 和 state。

4. 提取代理

全球随机 IP

curl -X POST "$ZTPROXY_BASE/business/dynamic-accounts/123/extract" \
  -H "Authorization: Bearer $ZTPROXY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "socks5"
  }'

按地区提取

curl -X POST "$ZTPROXY_BASE/business/dynamic-accounts/123/extract" \
  -H "Authorization: Bearer $ZTPROXY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "socks5",
    "country": "US",
    "state": "California",
    "city": "Los Angeles"
  }'

批量提取

传入 quantity 可一次返回多条代理凭据，范围为 1 至 200，默认值为 1。批量结果读取 data.proxy.list：

curl -X POST "$ZTPROXY_BASE/business/dynamic-accounts/123/extract" \
  -H "Authorization: Bearer $ZTPROXY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "socks5",
    "country": "US",
    "quantity": 10
  }'

批量提取时，每条凭据会使用独立的 5 分钟会话。如果同时传入 sessionId 和 sessionMinutes，平台会为每条凭据派生独立的会话标识，并使用指定的会话时长。

粘性会话

默认不指定会话时，请求可获得轮换 IP。需要在一段时间内保持同一出口 IP 时，传入 sessionId 和 sessionMinutes：

curl -X POST "$ZTPROXY_BASE/business/dynamic-accounts/123/extract" \
  -H "Authorization: Bearer $ZTPROXY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "socks5",
    "country": "US",
    "sessionId": "cart01",
    "sessionMinutes": 10
  }'

sessionId 仅使用字母和数字并最多保留 6 个字符；平台会把它与当前标准地区层级绑定，生成实际使用的 6 位会话标识。sessionMinutes 支持 1 至 60 分钟。

> 使用粘性会话时，切换国家、州/省或城市，应同时生成新的 sessionID。仅修改地区参数、沿用旧 sessionID，可能继续使用原地区的出口 IP。

同一地区、同一会话标识在会话时长内会尽量保持同一出口 IP，但不保证出口绝不变化。业务侧应为需要隔离的任务使用不同 sessionId。

请求字段：

字段	类型	必填	说明
`protocol`	string	否	默认 `socks5`。本文的 HTTPS 目标访问示例只验证 SOCKS5 隧道，不代表 HTTP 代理或 HTTPS CONNECT 已可用。
`country`	string	否	国家代码；不传表示全球随机。
`state`	string	否	州/省标准名称，必须属于所选国家。
`city`	string	否	城市标准名称，必须属于所选州/省。
`quantity`	integer	否	提取数量，范围 `1`–`200`，默认 `1`。
`sessionId`	string	否	粘性会话标识。
`sessionMinutes`	integer	否	粘性会话时长，范围 `1`–`60` 分钟。

成功响应示例：

{
  "code": 0,
  "msg": "代理提取成功",
  "data": {
    "productNo": "dynamic_2",
    "productName": "动态IP池2",
    "protocol": "socks5",
    "host": "<proxy-host>",
    "port": 10000,
    "username": "<proxy-username>",
    "password": "<proxy-password>",
    "quantity": 2,
    "proxy": {
      "list": [
        "<host>:<port>:<username-1>:<password>",
        "<host>:<port>:<username-2>:<password>"
      ]
    },
    "formatted_proxy": "<host>:<port>:<username>:<password>"
  }
}

单条提取时，应用程序可读取结构化的 host、port、username 和 password 字段。批量提取时应读取 proxy.list；结构化字段与 formatted_proxy 均表示列表中的第一条代理。formatted_proxy 的顺序固定为 host:port:username:password，适合需要单行导入的代理客户端。

平台会按所选地区返回入口域名：当前实现中，美国地区使用 host5.ztproxy.net；亚洲、欧洲及其他非美国地区或全球随机使用默认入口 host4.ztproxy.net。入口域名不改变地区参数和粘性会话规则。

例如，通过返回的 SOCKS5 代理访问外部服务：

curl --proxy "socks5h://<host>:<port>" \
  --proxy-user "<username>:<password>" \
  "https://api.ipify.org?format=json"

5. 查询流量用量

按日查询：

curl "$ZTPROXY_BASE/business/dynamic-accounts/123/usage?granularity=day&start=2026-10-01&end=2026-10-03&page=1&pageSize=100" \
  -H "Authorization: Bearer $ZTPROXY_TOKEN"

granularity 支持：

值	说明
`day`	按日汇总，默认值。
`hour`	按小时汇总。
`detail`	用量明细。

日期使用 YYYY-MM-DD 格式，pageSize 范围为 1–500。用量数据可能存在短暂统计延迟；业务侧应以账户 limitBytes - usedBytes 判断剩余额度，并在接近上限时停止创建新任务。

6. 暂停或恢复账户

curl -X POST "$ZTPROXY_BASE/business/dynamic-accounts/123/status" \
  -H "Authorization: Bearer $ZTPROXY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "paused"}'

status 支持 active、paused 和 disabled。流量已经用尽的账户不能恢复为 active。

常见错误

HTTP	含义	处理建议
`400`	地区层级无效、会话参数错误或流量已用尽。	检查响应 `detail`，重新查询地区目录或购买流量。
`401`	Token 缺失、无效或已过期。	重新登录并更新 Bearer Token。
`403`	当前账号无权访问目标用户或账户。	普通用户使用自己的 `userId`；代理商仅操作直属下级用户。
`404`	动态资源账户不存在。	重新查询账户列表，确认使用的是 `accountId` 而不是订单号。
`503`	动态资源状态、用量或代理入口暂时不可用。	不要无限重试；采用指数退避并保留请求时间与订单号供排查。

接入建议

不要自行拼接或修改代理用户名；每次通过提取接口获取完整凭据。
Token 和代理密码只保存在服务端或密钥管理系统中。
对 503 使用带上限的指数退避；对 400、403、404 不应盲目重试。
长任务使用稳定且彼此隔离的 sessionId；希望轮换 IP 时不要复用粘性会话。
定期查询账户详情与用量，在额度不足前购买额外流量。