经销商 API

面向已审核经销商的程序化接口:查询产品目录、余额下单、获取代理凭据、为每位客户单独开子账号、监控流量消耗 —— 全部通过简单的 REST API 完成。

把完整 API 文档(Markdown)复制到剪贴板,粘贴给 ChatGPT / Claude 帮你接入

速览

Base URL:https://hellworld.io/openapi/v1(https://hellworld.io/hellworld/openapi/v1 是同一 API 的等价路径)
鉴权:Authorization: Bearer <key_id>.<key_secret>
格式:JSON over HTTPS
计费:预付账户余额(USD)
限流:按经销商计 —— 读 300 次/分、写(下单,以及子账号的建号/加量/回收)60 次/分;最多 5 个活跃 Key。

概览

经销商 API 仅对已审核的经销商账户开放。您的客户经理会为账户开通具体产品并配置经销商价格,只有对您开通的产品才会出现在 API 中。

典型集成流程:

GET /products — 查看已开通产品与单价
POST /orders — 下单,从预付余额扣款
GET /orders/{order_ref} — 确认订单状态
GET /proxies — 获取代理凭据与流量消耗
按下方各产品的网关格式拼接代理串

如果您是转卖给终端客户、每位客户都要有自己的账密,请改用子账号:POST /subusers 会新建一套独立凭据和独立流量额度,之后可以单独加量,也可以按整数 GB 回收它未用完的流量并拿到退款(见 DELETE)—— 回收不会断开这个子账号。

当前可用产品:

product_code	产品	类别	计费	子账号
`MOBILE-ET`	ET Mobile	移动	按 GB	支持
`RES-GEOFAST`	Geofast	住宅	按 GB	—
`RES-ETH`	ET Hearth	住宅	按 GB	支持

产品要为您的账户开通并配好价格后才能使用,届时会出现在您的 GET /products 里。如需更多产品,联系客户经理开通。

鉴权

在经销商门户(控制台 → 经销商门户 → API Keys)创建 API Key。Key 由两部分组成:

Key ID — dk_live_ 开头,可安全记录到日志
Key Secret — 仅创建时展示一次,请妥善保存

每个请求都要带上两者,用点号连接:

Authorization: Bearer dk_live_AbCdEf1234567890.YOUR_KEY_SECRET

bash

curl -s https://hellworld.io/openapi/v1/products \
  -H "Authorization: Bearer dk_live_AbCdEf1234567890.YOUR_KEY_SECRET"

常见坑

Header 值 = Bearer + 一个空格 + key_id.key_secret,第一个点号分隔 ID 与 Secret。
写操作还需要 Content-Type: application/json 与 Idempotency-Key 头(见幂等章节)。
限流按经销商(所有 Key 共享):读 300 次/分、写 60 次/分(下单与子账号建号/加量/回收共用这一份额度);收到 429 RATE_LIMITED 请按响应头 Retry-After 退避。最多可持有 5 个活跃 Key。
Key 可随时在门户吊销并重建,吊销即时生效。
Python 自带的 urllib 默认 User-Agent 会被我们的边缘网络拦截(403),请自行设置 User-Agent 头;requests、curl、Node、Go 的默认值都没问题。

鉴权错误:

HTTP	code	含义
401	`AUTH_MISSING_KEY`	缺少 `Authorization` 头
401	`AUTH_INVALID_KEY`	Key 格式错误、不存在或 Secret 不匹配
401	`AUTH_KEY_REVOKED`	Key 已吊销
401	`AUTH_KEY_EXPIRED`	Key 已过期
403	`DEALER_SUSPENDED`	经销商账户被停用 — 联系客户经理
429	`RATE_LIMITED`	超过经销商级限流(读 300/分、写 60/分);见 `Retry-After`

接口错误统一用下面的信封:

json

{ "error": { "code": "INSUFFICIENT_BALANCE", "message": "Account balance is insufficient for this order" } }

服务器根本无法解析的请求 —— 写操作没带请求体或 JSON 写错、没带 Content-Type: application/json、字段的 JSON 类型不对(例如 product_code 传成数字),或 pageNum / pageSize 不是数字 —— 会得到一个不带这个信封的通用错误应答(可能是 4xx,也可能是 500)。这种情况下什么都不会创建、也不会扣费;改正请求后重新发送即可。

产品

GET /products

返回对您开通的产品及您的单价。

bash

curl -s https://hellworld.io/openapi/v1/products \
  -H "Authorization: Bearer $KEY"

json

{
  "data": [
    { "product_code": "MOBILE-ET", "display_name": "ET Mobile", "category": "mobile", "billing_unit": "gb", "unit_price": 2.50, "currency": "USD" },
    { "product_code": "RES-GEOFAST", "display_name": "Geofast", "category": "residential", "billing_unit": "gb", "unit_price": 0.30, "currency": "USD" }
  ]
}

unit_price 为您的协议价(按 billing_unit 计)。没有 unit_price 的产品表示尚未为您的账户配价,暂时不能购买(下单和建子账号都会返回 422 NO_DEALER_PRICE),请联系客户经理配置。

余额

GET /balance

bash

curl -s https://hellworld.io/openapi/v1/balance -H "Authorization: Bearer $KEY"

json

{ "balance": 152.40, "currency": "USD" }

充值:登录 hellworld.io 用常规余额充值(PayPal / 加密货币等),或与客户经理线下打款入账 —— 都进入 API 扣款的同一余额。

订单

POST /orders

从预付余额下单。必须带 Idempotency-Key 头 —— 1–64 个 ASCII 字符,仅允许英文字母、数字以及 .、_、:、-(不允许空格;UUID 正好符合);超长或含其它字符返回 422 IDEMPOTENCY_KEY_INVALID。

bash

curl -s -X POST https://hellworld.io/openapi/v1/orders \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c9e6679-7425-40de-963d-1a4a6e4c1b2f" \
  -d '{ "product_code": "RES-GEOFAST", "quantity": 10 }'

字段	类型	必填	含义
`product_code`	string	是	见 `GET /products`
`quantity`	number	是	按 `billing_unit` 计的数量(GB),须 > 0

成功 — 200:

json

{ "order_ref": "a1b2c3d4e5f6...", "state": "active", "total_amount": 3.00, "currency": "USD" }

流量会累加到该产品的代理凭据上(见代理与消耗);同产品重复购买是对同一凭据充值。

已受理 — 202(人工审核):

json

{ "order_ref": "a1b2c3d4e5f6...", "state": "manual_review", "message": "Order was recorded but pending manual verification; do not retry this request" }

202 = 已扣款,切勿重试

202 manual_review 表示余额已扣、订单已记录,只是自动履约需人工确认。换新 Idempotency-Key 重试会产生(并扣款)第二笔订单。请轮询 GET /orders/{order_ref} 直到状态变为 completed。

错误:

HTTP	code	含义
400	`IDEMPOTENCY_KEY_REQUIRED`	缺 `Idempotency-Key` 头
422	`IDEMPOTENCY_KEY_INVALID`	Key 不是 1–64 个 `A-Za-z0-9._:-` 字符
402	`INSUFFICIENT_BALANCE`	余额不足,先充值
404	`PRODUCT_NOT_FOUND`	无此可购产品(编码未知,或未对您开通)
422	`NO_DEALER_PRICE`	未为您配价 —— 联系客户经理
409 / 422	`IDEMPOTENCY_KEY_CONFLICT`	见幂等
422	`VALIDATION_ERROR`	`product_code`/`quantity` 缺失或非法
422	`ORDER_REJECTED`	下单被拒
500	`ORDER_STATE_UNKNOWN`	结果未核实 — 切勿换新 Key 重试;轮询 `GET /orders` 或联系支持
403	`SANDBOX_KEY_DISABLED`	沙箱 Key 暂不可用 — 请创建正式 Key

幂等

每个 POST /orders 都必须带 Idempotency-Key,语义:

场景	结果
同 Key 同 Body,此前已处理完	原样重放当时的响应(不会重复扣款)
同 Key 同 Body,仍在处理中	`409 IDEMPOTENCY_KEY_CONFLICT` — 稍后原样重发即可取到结果
同 Key 不同 Body	`422 IDEMPOTENCY_KEY_CONFLICT` — 一个 Key 只能对应一份请求体
该 Key 终结为校验类失败(`VALIDATION_ERROR`/`PRODUCT_NOT_FOUND`/`INSUFFICIENT_BALANCE` 等)	重放该错误;这类已证无副作用 — 可换新 Key重试
该 Key 终结为 `ORDER_STATE_UNKNOWN`	结果无法核实。绝不换新 Key 重试(可能重复扣款)— 轮询 `GET /orders` 或持该 Key 联系支持

建议每次下单生成新 UUID 并与本地订单记录一起持久化。Key 须匹配 [A-Za-z0-9._:-]{1,64} —— 上限 64 字符,不允许空格。

GET /orders

分页订单历史(新单在前)。

bash

curl -s "https://hellworld.io/openapi/v1/orders?pageNum=1&pageSize=20" -H "Authorization: Bearer $KEY"

json

{
  "data": [
    {
      "order_ref": "a1b2c3d4e5f6...", "order_no": "CZ20260825...", "state": "completed",
      "total_amount": 3.00, "currency": "USD", "created_at": "2026-08-25 10:12:03",
      "products": [ { "product_code": "RES-GEOFAST", "display_name": "Geofast", "quantity": 10 } ]
    }
  ],
  "pagination": { "page": 1, "page_size": 20, "total": 42 }
}

pageSize 上限 100。

GET /orders/{order_ref}GET /orders/{ref}

单个订单查询 —— 202 manual_review 后用它轮询结局。响应与列表条目同形。查无(或不属于您的账户)返回 404 ORDER_NOT_FOUND。

订单状态:

state	含义
`pending`	已建单未支付
`completed`	已支付,履约完成(流量已入账)
`manual_review`	已扣款,待人工确认 — 轮询至 `completed`
`failed`	支付失败,未扣款
`disputed`	争议中
`refunded`	已退款
`unknown`	其它内部状态

代理与消耗

GET /proxies

您的代理凭据与流量消耗 —— 每个已购买的开通产品一条。

bash

curl -s https://hellworld.io/openapi/v1/proxies -H "Authorization: Bearer $KEY"

json

{
  "data": [
    {
      "product_code": "RES-GEOFAST", "display_name": "Geofast", "billing_unit": "gb",
      "username": "hw_ab12cd34", "password": "s3cr3tPass",
      "traffic": { "limit_gb": 50.0, "used_gb": 12.345, "remaining_gb": 37.655 },
      "status": "active", "expires_at": null
    }
  ],
  "usage_refresh_seconds": 60
}

字段	含义
`username` / `password`	该产品代理网关的账密(拼法见下)
`traffic.limit_gb`	历史累计购买 GB(充值累加)
`traffic.used_gb`	已消耗 GB(我们最近一次记录的值,可能已过时,见下)
`traffic.remaining_gb`	`limit - used`,下限 0
`status`	`active` 或 `suspended`(如流量用尽)
`expires_at`	GB 存量类产品为 `null`(不过期)
`usage_refresh_seconds`	两次尝试刷新用量之间的最短间隔 —— 不代表数据就有这么新

用量可能已过时

used_gb 和 remaining_gb 是我们最近一次记录的值。目前调用 GET /proxies 时用量可能不会刷新,所以这些数字可能明显落后于实际消耗 —— 远不止 60 秒。请当作近似值,不要据此给客户计费,也不要据此决定何时停用客户。轮询频率高于每分钟一次也不会拿到更新的数据。

同产品再次购买(POST /orders)是给同一凭据加 limit_gb,不会产生新用户名。

子账号

子账号是一套独立的代理凭据 —— 有自己的 username / password 和自己的流量额度 —— 由您通过 API 为某一位客户开设。每个子账号可以单独加量,也可以按整数 GB 回收它未用完的流量并拿到退款,不影响您的其他客户。回收不会断开子账号:它仍为 active,凭据不变(见 DELETE)。

	下单(`POST /orders`)	子账号(`/subusers`)
凭据	每个产品一套共用凭据(`GET /proxies`)	每个子账号一套新凭据
流量	加到共用凭据上	每个子账号各有额度
没用完的流量	留在共用凭据上	用 `DELETE /subusers/{subuser_ref}` 按整数 GB 回收并退款;子账号仍为 `active`
停掉某一位客户的访问	做不到,会影响其他人	没有对应的接口 —— `DELETE` 不会停用子账号,也不会更换凭据;见要停用某位客户时
出现在 `GET /orders`、Webhook 里	是	否 —— 只体现在余额变化上
支持的产品	为您开通的任意产品	`MOBILE-ET`、`RES-ETH`

自己用流量、或多人共用一个账密时用下单;转卖给终端客户、每人要有自己的账密和额度时用子账号。

接口一览(Base URL、Key、限流与本文其余接口相同):

方法	路径	作用	扣费
`POST`	`/subusers`	建子账号	`unit_price × quota_gb`
`GET`	`/subusers`	子账号列表	—
`GET`	`/subusers/{subuser_ref}`	凭据、额度与用量	—
`PATCH`	`/subusers/{subuser_ref}`	加量	`unit_price × add_gb`
`DELETE`	`/subusers/{subuser_ref}`	按整数 GB 回收未用完的流量(子账号仍为 `active`)	退款 `reclaimed_gb` × 您付过的最低单价

产品与计费

支持子账号的产品(点击产品名查看连接格式):

product_code	产品
`MOBILE-ET`	ET Mobile
`RES-ETH`	ET Hearth

前提是该产品出现在您自己的 GET /products 里且带 unit_price;否则建号会被拒 —— 404 PRODUCT_NOT_FOUND(未为您开通)或 422 NO_DEALER_PRICE(未配价),不会扣费。GET /products 不标注哪些产品支持子账号,以上表为准。

怎么扣费

建号和加量按您的 unit_price(每 GB)从预付余额扣:金额 = unit_price × GB,四舍五入到分(5 GB × $2.50 → $12.50)。价格以请求那一刻为准。
GB 数四舍五入保留 6 位小数后须至少 0.001,金额至少 $0.01;更小的请求返回 422 VALIDATION_ERROR。
回收按整数 GB 退款。 DELETE 收回子账号未用完的已购流量的整数 GB 部分,并按您为这个子账号付过的最低每 GB 单价退到余额;留在子账号上的部分(例如不足 1 GB 的零头)不退款。见 DELETE。
结果未知时扣款保留。 建号或加量返回 500 SUBUSER_STATE_UNKNOWN / 500 TOPUP_STATE_UNKNOWN 时,已扣的金额核实期间不会退回(少数情况几分钟内自动结清,其余由我们人工核实)。可原样重发同一请求查看最新状态,不要换新 Key 重试(见幂等与重试),并联系客服。同样,回收返回 500 REVOKE_STATE_UNKNOWN 时,核实期间不退款。
子账号的扣款和退款都不是订单:不出现在 GET /orders 里,也不发 Webhook。GET /balance 会立即反映 —— 请按 subuser_ref 自行记账。

各种结果对余额的影响:

结果	余额
建号 / 加量 `200`	扣 `unit_price × GB`
回收 `200 RECLAIMED`(`DELETE`)	退回 `refunded_amount`
建号 / 加量被拒:`400`、`402`、`404`、`503`;`422` `VALIDATION_ERROR` / `NO_DEALER_PRICE` / `LIMIT_EXCEEDED` / `IDEMPOTENCY_KEY_*`;`409` `SUBUSER_REF_CONFLICT` / `SUBUSER_OP_IN_FLIGHT` / `SUBUSER_NOT_ACTIVE`,以及 Key 已用于其它接口时的 `IDEMPOTENCY_KEY_CONFLICT`	不扣
`422 SUBUSER_CREATE_FAILED`、`422 TOPUP_FAILED`	扣了又已退回 —— 净额为零
`409`「仍在处理」(`SUBUSER_IN_FLIGHT`、`TOPUP_IN_FLIGHT`、`REVOKE_IN_FLIGHT`、`IDEMPOTENCY_KEY_CONFLICT`)	原请求还在执行 —— 建号或加量可能已扣,回收仍可能完成并退款。稍后用同一个 Key 原样重发同一个请求取结果,不要换新 Key
`500 SUBUSER_STATE_UNKNOWN`、`500 TOPUP_STATE_UNKNOWN`	扣款保留,待核实
回收 `500 REVOKE_STATE_UNKNOWN`(`DELETE`)	核实期间不退款
`200 NOTHING_TO_RECLAIM`,或 `DELETE` 被拒:`400`、`404`、`422`、`501`,或 `409` `REVOKE_NOT_STARTED` / `SUBUSER_OP_IN_FLIGHT`	不扣、不退
同 Key 原样重发	绝不重复扣费,也绝不重复退款

快速上手

建号 → 取凭据 → 连接 → 加量 → 回收。每个写操作都要用自己的 Idempotency-Key(新生成的 UUID);$KEY 为您的 key_id.key_secret。

1. 建号:给客户开一个 5 GB 的 ET Mobile 子账号。subuser_ref 是您自己给这位客户定的 ID:

bash

curl -s -X POST https://hellworld.io/openapi/v1/subusers \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0b6f3c2e-8d1a-4f7b-9c55-2a7e4d1f6b90" \
  -d '{ "product_code": "MOBILE-ET", "subuser_ref": "cust-1001", "quota_gb": 5 }'

json

{
  "subuser_ref": "cust-1001",
  "status": "active",
  "username": "USERNAME",
  "password": "PASSWORD",
  "traffic": { "limit_gb": 5.000000 }
}

2. 取凭据:随时可以再查:

bash

curl -s https://hellworld.io/openapi/v1/subusers/cust-1001 \
  -H "Authorization: Bearer $KEY"

3. 连接:按该产品的代理串格式把代理串交给客户:

bash

curl -x etmobile.hellworld.io:5000 \
  -U "USERNAME-country-us:PASSWORD" \
  https://ipinfo.io

4. 加量 2 GB(距上一次写操作请隔几分钟,见时序与建议):

bash

curl -s -X PATCH https://hellworld.io/openapi/v1/subusers/cust-1001 \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5d2a9e71-3c4b-4e08-a6f1-9b0c7e2d4a13" \
  -d '{ "add_gb": 2 }'

json

{ "subuser_ref": "cust-1001", "status": "active", "traffic": { "limit_gb": 7.000000 } }

5. 回收:客户不再使用时,收回未用完的流量(同样距上一次写操作隔几分钟,并在子账号空闲时进行):

bash

curl -s -X DELETE https://hellworld.io/openapi/v1/subusers/cust-1001 \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: 9a4e1b7c-6f2d-4a83-b5c0-1d8e3f7a2c64"

json

{
  "subuser_ref": "cust-1001",
  "status": "active",
  "code": "RECLAIMED",
  "reclaimed_gb": 6.000000,
  "refunded_amount": 15.00,
  "currency": "USD",
  "remaining_gb": 0.996000,
  "message": "…"
}

这里客户用掉了 7 GB 里的 0.004 GB,所以收回整数部分 6 GB,$15.00(6 × $2.50)退回您的余额。子账号仍为 active、凭据不变,上面剩下的 0.996 GB 您的客户仍可继续使用 —— DELETE 不会断开子账号(见要停用某位客户时)。规则与其它结果见 DELETE。

POST /subusers建号 (POST)

新建子账号,并从余额扣 unit_price × quota_gb。必须带 Idempotency-Key。

字段	类型	必填	含义
`product_code`	string	是	`MOBILE-ET` 或 `RES-ETH`,须为 JSON 字符串(须已为您开通并配价)
`subuser_ref`	string	是	您给这个子账号定的 ID:1–128 个 `A-Za-z0-9._:-` 字符,区分大小写。在您的账户下永久唯一 —— 永远不能再用于别的子账号
`quota_gb`	number	是	流量额度(GB),须 > 0(四舍五入保留 6 位小数;至少 `0.001` GB 且金额至少 $0.01)

成功 — 200:

json

{
  "subuser_ref": "cust-1001",
  "status": "active",
  "username": "USERNAME",
  "password": "PASSWORD",
  "traffic": { "limit_gb": 5.000000 }
}

username / password 在三个地方返回:这里、用同一个 Key 原样重发本请求时、以及子账号处于 active 时的 GET /subusers/{subuser_ref}。请妥善保存。
应答里没有 product_code、created_at 和用量 —— 需要时查 GET /subusers/{subuser_ref}。
建号约需 10 秒。客户端超时请设为至少 60 秒;超时后用同一个 Key 原样重发同一个请求 —— 绝不要换新 Key 或新的 subuser_ref。

错误:

HTTP	code	含义 / 怎么办
400	`IDEMPOTENCY_KEY_REQUIRED`	缺 `Idempotency-Key` 头
422	`IDEMPOTENCY_KEY_INVALID`	Key 不是 1–64 个 `A-Za-z0-9._:-` 字符
422	`VALIDATION_ERROR`	缺字段、`quota_gb` 不是正数、`subuser_ref` 格式不对,或数量低于 0.001 GB / 金额低于 $0.01
404	`PRODUCT_NOT_FOUND`	该产品不支持子账号,或未为您开通
422	`NO_DEALER_PRICE`	未为您配价 —— 联系客户经理
402	`INSUFFICIENT_BALANCE`	充值后用新 Key 重试(同一个 `subuser_ref` 仍可用)
409	`SUBUSER_REF_CONFLICT`	该 `subuser_ref` 已被之前另一个 Key 的请求用过 —— 换一个新的 `subuser_ref`
409 / 422	`IDEMPOTENCY_KEY_CONFLICT`	见幂等与重试
409	`SUBUSER_IN_FLIGHT`	您重发的请求还在处理 —— 稍后用同一个 Key 再重发;约 20 分钟后仍是这个结果,请联系客服
409	`SUBUSER_SUSPENDED`	您重发的建号请求对应的子账号已按之前的 `DELETE` 行为停用(见 DELETE)
422	`SUBUSER_CREATE_FAILED`	确定没有建成,扣款已退回。用新的 `subuser_ref` 和新 Key 重试
503	`SUBUSER_UNAVAILABLE`	建号暂不可用,未扣费。稍后用新 Key 重试
500	`SUBUSER_STATE_UNKNOWN`	结果无法确认;如已扣款,扣款保留待人工核实。不要换新 Key 或新 `subuser_ref`;可原样重发查看最新状态,或带上 Key 与 `subuser_ref` 联系客服。另外,子账号正在回收或回收后等待客服处理时,重发当初的建号请求也会得到这个码 —— 该子账号已建成、只扣过一次,重发不会再扣

GET /subusers列表 (GET)

子账号列表,新建的在前。查询参数:pageNum(默认 1)、pageSize(默认 20,上限 100)。

bash

curl -s "https://hellworld.io/openapi/v1/subusers?pageNum=1&pageSize=20" \
  -H "Authorization: Bearer $KEY"

json

{
  "data": [
    {
      "subuser_ref": "cust-1001",
      "product_code": "MOBILE-ET",
      "status": "active",
      "traffic": { "limit_gb": 7.000000 },
      "created_at": "2026-10-08T02:14:50"
    }
  ],
  "pagination": { "page": 1, "page_size": 20, "total": 1 }
}

只列出 active、pending、unknown 的子账号(见状态值);回收之后子账号照常在列表里。按之前的 DELETE 行为停用的子账号、确定建号失败的子账号不会出现。
列表项不含凭据和用量 —— 需要时查单个子账号。
created_at 为 UTC 时间,格式 YYYY-MM-DDTHH:MM:SS,不带时区后缀。

GET /subusers/{subuser_ref}详情 (GET)

单个子账号的凭据、额度与用量。

bash

curl -s https://hellworld.io/openapi/v1/subusers/cust-1001 \
  -H "Authorization: Bearer $KEY"

json

{
  "subuser_ref": "cust-1001",
  "product_code": "MOBILE-ET",
  "status": "active",
  "username": "USERNAME",
  "password": "PASSWORD",
  "traffic": {
    "limit_gb": 7.000000,
    "used_gb": 0.000000,
    "remaining_gb": 7.000000,
    "usage_source": "cached"
  },
  "usage_refresh_seconds": 60,
  "created_at": "2026-10-08T02:14:50"
}

字段	含义
`username` / `password`	代理凭据 —— 仅在 `status` 为 `active` 时返回
`traffic.limit_gb`	该子账号累计购买的 GB(建号 + 各次加量),减去用 `DELETE` 收回的 GB
`traffic.used_gb`	已消耗 GB(我们最近一次记录的值)
`traffic.remaining_gb`	`limit_gb − used_gb`,最小为 0
`traffic.usage_source`	`live` = 本次请求刚刷新;`cached` = 最近一次记录的值,可能已过时
`usage_refresh_seconds`	每个子账号最多每隔这么多秒尝试刷新一次
`created_at`	创建时间,UTC,不带时区后缀

用量数值有多新

used_gb / remaining_gb 会在请求时从网络刷新，每个子账号每 usage_refresh_seconds 秒最多刷新一次。usage_source: "live" 表示这次返回的是刚读到的数值;"cached" 表示上一次记录的数值(例如这次没有刷新或刷新失败),可能落后于实际消耗。只用 live 的数值给客户计费或停用客户。

错误:404 SUBUSER_NOT_FOUND —— 您的账户下没有这个子账号(建号失败的、按之前的 DELETE 行为停用的也是 404);500 SUBUSER_CRED_UNREADABLE —— 凭据暂时无法读取,请带上 subuser_ref 联系客服。

PATCH /subusers/{subuser_ref}加量 (PATCH)

给 active 的子账号加流量,并扣 unit_price × add_gb。账号和密码不变。必须带 Idempotency-Key。

bash

curl -s -X PATCH https://hellworld.io/openapi/v1/subusers/cust-1001 \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5d2a9e71-3c4b-4e08-a6f1-9b0c7e2d4a13" \
  -d '{ "add_gb": 2 }'

字段	类型	必填	含义
`add_gb`	number	是	要加的 GB,须 > 0(四舍五入保留 6 位小数;至少 `0.001` GB 且金额至少 $0.01)

成功 — 200 —— limit_gb 是加量后的总额度:

json

{ "subuser_ref": "cust-1001", "status": "active", "traffic": { "limit_gb": 7.000000 } }

错误:

HTTP	code	含义 / 怎么办
400 / 422	`IDEMPOTENCY_KEY_REQUIRED` / `IDEMPOTENCY_KEY_INVALID`	缺 Key 或格式不对
422	`VALIDATION_ERROR`	`add_gb` 缺失或不是正数、`subuser_ref` 格式不对,或数量低于 0.001 GB / 金额低于 $0.01
404	`SUBUSER_NOT_FOUND`	没有这个处于 active 的子账号(不存在、按之前的 `DELETE` 行为停用,或当前为 `pending` / `unknown`)
404	`PRODUCT_NOT_FOUND`	该产品已不再为您开通
422	`NO_DEALER_PRICE`	未为您配价
402	`INSUFFICIENT_BALANCE`	充值后用新 Key 重试
409	`SUBUSER_OP_IN_FLIGHT`	该子账号另有加量或回收尚未结束,本次未扣费。等它结束后用新 Key 重试 —— 用原来的 Key 重发只会一直得到这个 `409`
409	`SUBUSER_NOT_ACTIVE`	处理过程中子账号已不是 active,未扣费
422	`LIMIT_EXCEEDED`	加量后总额度超过上限;未扣费
422	`TOPUP_FAILED`	没有加上,扣款已退回。通常是子账号刚被改动过 —— 等 2–3 分钟后用新 Key 重试;反复出现请联系客服
409	`TOPUP_IN_FLIGHT`	您重发的请求还在处理(可能已扣款)—— 稍后用同一个 Key 再重发,不要换新 Key;约 20 分钟后仍是这个结果,请联系客服
409 / 422	`IDEMPOTENCY_KEY_CONFLICT`	见幂等与重试
500	`TOPUP_STATE_UNKNOWN`	结果无法确认,扣款保留待人工核实。处理完之前,该子账号再加量或回收都会返回 `409 SUBUSER_OP_IN_FLIGHT`(凭据照常可用)。不要换新 Key;带上 Key 与 `subuser_ref` 联系客服

DELETE /subusers/{subuser_ref}回收 (DELETE)

DELETE 不会断开子账号

DELETE 只按整数 GB 收回未用完的流量,并把这部分退款到您的余额。它不会停用子账号:子账号仍为 active,账号和密码不变,留在上面的流量您的客户照常可以继续用。目前没有任何接口可以停用子账号或更换它的密码 —— 见要停用某位客户时。

这取代了之前的行为:之前 DELETE 会停用子账号,且不退款。

按整数 GB 回收子账号未用完的流量,并把这部分退款到您的余额。无请求体。必须带 Idempotency-Key。

bash

curl -s -X DELETE https://hellworld.io/openapi/v1/subusers/cust-1001 \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: 9a4e1b7c-6f2d-4a83-b5c0-1d8e3f7a2c64"

成功 — 200。 顶层的 code 说明这次有没有收回流量。以快速上手里的子账号为例(按每 GB $2.50 共买了 7 GB,已用 0.004 GB):

json

{
  "subuser_ref": "cust-1001",
  "status": "active",
  "code": "RECLAIMED",
  "reclaimed_gb": 6.000000,
  "refunded_amount": 15.00,
  "currency": "USD",
  "remaining_gb": 0.996000,
  "message": "…"
}

几分钟后再调用一次(用新 Key),剩下可回收的已不足 1 GB:

json

{
  "subuser_ref": "cust-1001",
  "status": "active",
  "code": "NOTHING_TO_RECLAIM",
  "reclaimed_gb": 0.000000,
  "refunded_amount": 0.00,
  "currency": "USD",
  "remaining_gb": 0.996000,
  "message": "…"
}

字段	含义
`code`	`RECLAIMED` —— 已收回整数 GB(见 `reclaimed_gb`),并已把 `refunded_amount` 退到您的余额。`NOTHING_TO_RECLAIM` —— 未用完的已购流量不足 1 GB:什么都没收回、没有退款,子账号没有任何变化
`status`	`active` —— 子账号没有被停用,凭据不变(剩余流量可能为 0 GB)
`reclaimed_gb`	收回的整数 GB(`NOTHING_TO_RECLAIM` 时为 `0`)
`refunded_amount` / `currency`	退到余额的金额,美元(`NOTHING_TO_RECLAIM` 时为 `0.00`)
`remaining_gb`	本次调用后子账号上实际还剩的流量(含赠送部分)—— 您的客户可以继续用。它可能与 `GET /subusers/{subuser_ref}` 里的 `traffic.remaining_gb` 不同,后者只算您付过费的流量
`message`	给人看的说明,内容可能调整 —— 请按 `code` 判断

收回多少、退多少

收回:子账号未用完的已购流量里的整数 GB 部分,即 limit_gb − used_gb 向下取整到整数 GB。用量按请求那一刻实测,不是 GET 返回的缓存 used_gb。收回的量不会超过子账号上实际剩下的流量。
留在子账号上:其余部分 —— 不足 1 GB 的零头,以及超出您已购额度的流量(如有)。这部分不收回、不退款,请您自己与客户结算。
退款 = 收回的 GB × 您为这个子账号付过的最低每 GB 单价(建号时或任一次成功加量时),与扣款一样四舍五入到分。一个子账号累计的退款不会超过它累计的扣款。
回收后,GET /subusers/{subuser_ref} 返回的 limit_gb 会相应减少 reclaimed_gb。
未用完的已购流量不足 1 GB 时 —— 包括流量已经用完的子账号 —— 返回 NOTHING_TO_RECLAIM:什么都不收回、不退款、不改动,可以放心再调。

举例:一个子账号建号时按每 GB $2.50 买了 8 GB,之后按每 GB $2.00 加量 2 GB —— 共买 10 GB、扣款 $24.00,退款按每 GB $2.00 计:

回收时已用	`code`	`reclaimed_gb`	`refunded_amount`	留在子账号上
5.2 GB	`RECLAIMED`	4	8.00	0.8 GB
0 GB	`RECLAIMED`	10	20.00	0 GB —— 子账号仍为 `active`,只是没有流量了
9.6 GB	`NOTHING_TO_RECLAIM`	0	0.00	0.4 GB
10 GB(已用完)	`NOTHING_TO_RECLAIM`	0	0.00	0 GB

什么时候回收

请在子账号空闲时回收。回收进行时如果您的客户还在通过它跑流量,结果可能无法确认:会返回 500 REVOKE_STATE_UNKNOWN,核实期间不退款(见回收结果无法确认时)。
同一个子账号加量或上一次回收之后,请隔约 3 分钟再回收。发得太早会被安全地拒绝,返回 409 REVOKE_NOT_STARTED(什么都没改)—— 稍后用新 Key 重试即可。
回收约需 10 秒。这期间子账号显示 status: "unknown",GET /subusers/{subuser_ref} 不返回凭据,也不能加量或再次回收;子账号不会被停用、凭据也不变,客户还能不能用,取决于实际还剩多少流量。

之前已停用的子账号。 本次调整之前,DELETE 会停用子账号。按那种方式停用的子账号保留原来的结果:用同一个 Key 重发当时的请求,返回与当时相同的 200 —— code: "QUOTA_SUSPENDED"(revocation: "drain_confirmed")或 code: "QUOTA_SUSPENDED_UNVERIFIED"(revocation: "unverified");用新 Key 对它调用 DELETE,返回 200、code: "QUOTA_SUSPENDED_UNVERIFIED"。两者都带 status: "suspended",都不含退款;这类子账号已不出现在列表里,GET 也查不到。其它子账号不会得到这两个码。

错误(本接口的错误码沿用原来 REVOKE_… 开头的名字):

HTTP	code	含义 / 怎么办
400 / 422	`IDEMPOTENCY_KEY_REQUIRED` / `IDEMPOTENCY_KEY_INVALID`	缺 Key 或格式不对
422	`VALIDATION_ERROR`	`subuser_ref` 格式不对
404	`SUBUSER_NOT_FOUND`	您的账户下没有这个子账号
409	`REVOKE_NOT_STARTED`	回收没有开始 —— 常见原因是子账号刚被改动过(刚加量或刚回收过)。什么都没改,也没有退款。等 2–3 分钟后用新 Key 重试;反复出现请联系客服
409	`SUBUSER_OP_IN_FLIGHT`	该子账号另有加量或回收正在进行,或子账号当前状态(`pending` / `unknown`)不能回收。什么都没改。状态解除后用新 Key 重试 —— 用原来的 Key 重发只会一直得到这个 `409`;一直如此请联系客服
409	`REVOKE_IN_FLIGHT`	您重发的回收还在执行 —— 稍后用同一个 Key 再重发;约 20 分钟后仍是这个结果,请联系客服
409	`REVOKE_IN_PROGRESS_OR_FAILED`	这个 Key 还没有结果。稍后原样重发;一直如此就换新 Key 或联系客服
409 / 422	`IDEMPOTENCY_KEY_CONFLICT`	该 Key 已用于其它接口,或用于另一个子账号
501	`REVOKE_NOT_SUPPORTED`	该子账号的产品不支持回收。什么都没改
500	`REVOKE_STATE_UNKNOWN`	回收结果无法确认。核实期间不退款 —— 见回收结果无法确认时。不要换新 Key;带上 Key 与 `subuser_ref` 联系客服

回收结果无法确认时回收结果未确认

500 REVOKE_STATE_UNKNOWN 表示回收请求已经发出,但结果无法确认 —— 可能的原因包括回收时子账号上还有流量在跑、网络侧的结果或我们的结算无法确认 —— 或者回收没能自动完成:

json

{ "error": { "code": "REVOKE_STATE_UNKNOWN", "message": "…" } }

这意味着:

暂不退款 —— 核实期间不会往您的余额退任何金额。
子账号不会被停用、凭据不变,但它的流量可能已经部分或全部被收回 —— 客户还能不能用,取决于实际还剩多少。不能因为「暂未退款」就认为「没有收回」。
客服处理完之前,该子账号在 GET /subusers 和 GET /subusers/{subuser_ref} 里显示为 status: "unknown";详情不返回凭据,API 也不能给它加量(404 SUBUSER_NOT_FOUND)或再次回收(用新 Key 会得到 409 SUBUSER_OP_IN_FLIGHT)。
用同一个 Idempotency-Key 原样重发是安全的,但结果不变 —— 它不会自行恢复。
此时重发该子账号当初的建号请求,会返回 500 SUBUSER_STATE_UNKNOWN。这不代表新的扣款:该子账号已经建成,只扣过一次。

怎么办: 带上 subuser_ref 和当时用的 Idempotency-Key 联系客服。不要换新 Key 重试。

要停用某位客户时停用客户

目前没有任何接口可以停用子账号或更换它的密码,DELETE 也不会这样做。客户不再使用时:

不再给这个子账号加量。
等它空闲时调用 DELETE,收回未用完的整数 GB 并拿到退款。
留在子账号上的部分 —— 不足 1 GB 的零头,以及超出已购额度的流量(如有)—— 凭原来的账密仍可使用,直到用完为止。这部分请您自己与客户结算。

subuser_ref 不能再用于别的子账号;新客户请用新的 ref 建号。

幂等与重试

POST /subusers、PATCH、DELETE 都必须带 Idempotency-Key —— 1–64 个 A-Za-z0-9._:- 字符,与下单相同。每个新操作用一个新 UUID,并和您的记录一起保存,超时后才能原样重发。

场景	结果
同 Key、同请求,已处理完	返回该操作的当前结果,绝不重复扣费或重复退款。子账号为 `active` 时(回收之后也是),重发建号请求会拿到当前凭据和当前 `limit_gb`(已计入之后的加量和回收);正在回收或回收后等待客服处理时,重发建号会得到 `500 SUBUSER_STATE_UNKNOWN`;按之前的 `DELETE` 行为停用的子账号得到 `409 SUBUSER_SUSPENDED` —— 都不是新的扣款。重发回收请求会得到与第一次相同的 `code` 和金额
同 Key、同请求,仍在处理:`409` `SUBUSER_IN_FLIGHT`、`TOPUP_IN_FLIGHT`、`REVOKE_IN_FLIGHT`、`REVOKE_IN_PROGRESS_OR_FAILED`,或 `IDEMPOTENCY_KEY_CONFLICT`(正在处理)	稍后用同一个 Key 原样重发。不要换新 Key —— 建号或加量可能已经扣款,换 Key 会再执行一次;回收也可能仍会完成。这类结果通常几秒内就会结束;同一个 `409` 持续超过约 20 分钟,请带上 Key 与 `subuser_ref` 联系客服
同 Key,请求体不同或 `subuser_ref` 不同	`422 IDEMPOTENCY_KEY_CONFLICT`
同 Key 已用在其它接口上(包括 `POST /orders`)	`409 IDEMPOTENCY_KEY_CONFLICT` —— 所有写接口共用同一套 Key
被拒:`400`、`402`、`404`、`422`、`503`,或上一行「仍在处理」以外的 `409`(例如 `SUBUSER_REF_CONFLICT`、`SUBUSER_OP_IN_FLIGHT`、`REVOKE_NOT_STARTED`)	修正原因后用新 Key 重试(遇到 `SUBUSER_CREATE_FAILED` 或 `SUBUSER_REF_CONFLICT` 还要换新的 `subuser_ref`);旧 Key 可能一直返回同样的错误
`500 SUBUSER_STATE_UNKNOWN` / `TOPUP_STATE_UNKNOWN` / `REVOKE_STATE_UNKNOWN`	绝不换新 Key 或新 `subuser_ref` 重试 —— 可能重复建号或重复扣费。原样重发是安全的,会返回最新状态;请带上 Key 与 `subuser_ref` 联系客服

重发必须是完全相同的请求:同一路径、同样的 JSON 字段和字段顺序、同样的数字写法(1 与 1.0 不同)。空白不影响。
Key 请按不区分大小写对待:不要使用只差大小写的两个 Key。
Key 不会过期。
请按 code 处理结果;message 只是给人看的说明,内容可能调整。

状态值

status	含义	详情是否返回凭据	能否加量 / 回收
`active`	可以使用 —— 回收之后也是	是	能
`pending`	建号中(通常约 10 秒)	否	不能
`unknown`	正在回收,或某个操作的结果正在核实 / 等待客服处理	否	不能
`suspended`	只用于按之前的 `DELETE` 行为停用的子账号:只出现在 `DELETE` 的应答里,与 `code` `QUOTA_SUSPENDED` / `QUOTA_SUSPENDED_UNVERIFIED` 一起返回;其它接口不再返回这类子账号	—	—

时序与建议

写操作约需 10 秒。客户端超时请设为至少 60 秒;超时后用同一个 Key 原样重发。
同一个子账号的两次写操作(建号 → 加量 → 回收)之间请间隔约 3 分钟。变更后读数需要一点时间才稳定;发得太早会被安全地拒绝 —— 422 TOPUP_FAILED(已退款)或 409 REVOKE_NOT_STARTED(什么都没改)—— 稍后用新 Key 重试即可。
DELETE 不会断开客户:子账号仍为 active,凭据不变。见要停用某位客户时。
只在子账号空闲时回收;有流量在跑时,结果可能无法确认(500 REVOKE_STATE_UNKNOWN,核实期间不退款)。
写操作与 POST /orders 共用每分钟 60 次的经销商写限额;读为每分钟 300 次。
子账号凭据同样可以配合您的自定义网关域名使用,与 GET /proxies 的凭据完全一样。

代理串格式

用 GET /proxies 返回的 username / password,或子账号的凭据(GET /subusers/{subuser_ref})拼代理串,语法相同;国家/地区定向与粘性会话编码在用户名里。

ET Mobile(`MOBILE-ET`)ET Mobile


网关	`etmobile.hellworld.io`
端口	`5000`
协议	HTTP / HTTPS

轮换(每请求换 IP):

etmobile.hellworld.io:5000:USERNAME-country-us:PASSWORD

粘性会话(TTL 内保持同 IP):

etmobile.hellworld.io:5000:USERNAME-country-us-sid-a1b2c3d4-ttl-10m:PASSWORD

-country-<cc> — 可选,2 位国家/地区码小写(省略=全球随机)
-sid-<id> — 任意 8 位字母数字会话 ID;同 sid = 同 IP
-ttl-<N>m — 会话时长(分钟)

Geofast(`RES-GEOFAST`)Geofast


网关	`geofast.hellworld.io`
HTTP/HTTPS 端口	`6969`
SOCKS5 端口	`9696`

轮换:

geofast.hellworld.io:6969:USERNAME-country-US:PASSWORD

粘性会话(约 10 分钟,同 session = 同 IP):

geofast.hellworld.io:6969:USERNAME-country-US-session-a1b2c3d4e5:PASSWORD

-country-<CC> — 可选,2 位国家/地区码大写(省略=全球随机)
-session-<id> — 任意 10 位字母数字会话 ID

SOCKS5 用端口 9696,用户名语法相同。

ET Hearth(`RES-ETH`)ET Hearth


网关	`ethearth.hellworld.io`
端口	`5000`
协议	HTTP / HTTPS

轮换(每请求换 IP):

ethearth.hellworld.io:5000:USERNAME-country-us:PASSWORD

粘性会话(TTL 内保持同 IP):

ethearth.hellworld.io:5000:USERNAME-country-us-sid-a1b2c3d4-ttl-10m:PASSWORD

-country-<cc> — 可选,2 位国家/地区码小写(省略=全球随机)
-sid-<id> — 任意 8 位字母数字会话 ID;同 sid = 同 IP
-ttl-<N>m — 会话时长,整数分钟,1–240
另支持州/省、城市、运营商定向(写在国家/地区与会话参数之间),所需代码请向客户经理索取。

自定义网关域名(白标)

默认情况下,你的客户连接上面的公共网关域名(etmobile.hellworld.io、geofast.hellworld.io、ethearth.hellworld.io)。如果你希望客户走你自己的品牌域名,只需加一条 CNAME 指向我们的网关即可——不用改代码,也不影响速度。

配置

针对你用到的每个网关,各加一条 CNAME,指向我们的网关主机名:

你的记录	类型	目标
`mproxy.yourbrand.com`	`CNAME`	`etmobile.hellworld.io`
`proxy.yourbrand.com`	`CNAME`	`geofast.hellworld.io`
`rproxy.yourbrand.com`	`CNAME`	`ethearth.hellworld.io`

客户照旧连接,只把主机名换成你的域名——端口与用户名语法完全不变:

proxy.yourbrand.com:6969:USERNAME-country-US-session-a1b2c3d4e5:PASSWORD

规则

务必把 CNAME 指向我们的 *.hellworld.io 网关主机名(如 geofast.hellworld.io),不要指向某个固定 IP。我们可能随时调整网关背后的 IP;由于你的记录指向的是我们的主机名,这些变化会自动生效,你无需任何操作。若把记录写死到固定 IP,IP 变更时你会断。
必须 DNS-only——前面不要套 CDN/代理层(如 Cloudflare 橙云)。代理端口是裸 TCP,套一层 CDN 会直接断连。请保持灰云 / 仅 DNS。
端口保持不变(ET Mobile 5000,ET Hearth 5000,Geofast HTTP 6969 / SOCKS5 9696)。
凭据仍由本 API 下发——自定义域名只是换个主机名的品牌皮;username / password 始终来自 GET /proxies 或子账号接口。

会影响速度吗?

不会。自定义域名只是纯 DNS 别名——代理流量依然直连网关 IP,既不经过我们的服务器,也不经过这个额外的域名。多出来的一跳 CNAME 只影响首次 DNS 解析(几毫秒,之后走缓存);实际代理延迟和吞吐与用公共域名完全一致。

Webhook

API 订单创建后主动推送通知,免轮询。在经销商门户(Webhook 区)配置回调 URL,并获得签名密钥。子账号操作不发 Webhook。

事件 order.created —— API 订单记录后发送(active 或 manual_review):

json

{
  "event_type": "order.created", "event_id": "…", "dealer_uuid": "…",
  "created_at": "2026-08-25T10:12:03Z",
  "data": { "order_ref": "a1b2c3d4e5f6...", "state": "active", "total_amount": 3.00, "currency": "USD" }
}

签名 —— 每次投递带:

X-Dealer-Signature: sha256=<hex>

<hex> = HMAC-SHA256(webhook_secret, 原始请求体)。验证示例(Node):

const crypto = require('crypto');
function verify(rawBody, header, secret) {
    const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
    return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}

投递与重试:您的端点须在数秒内返回 2xx;失败按指数退避重试(30s、60s、120s…封顶 1h),最多 12 次后放弃。门户的 Test webhook 按钮可发 webhook.test 事件验证端点。

TIP

Webhook 是尽力而为的推送。订单结局(尤其 manual_review 的转变)以轮询 GET /orders/{order_ref} 为准。

错误码总表

HTTP	code	出现于	含义
400	`IDEMPOTENCY_KEY_REQUIRED`	所有写接口	缺幂等键头
422	`IDEMPOTENCY_KEY_INVALID`	所有写接口	Key 不是 1–64 个 `A-Za-z0-9._:-` 字符
401	`AUTH_MISSING_KEY`	全部	缺 Authorization
401	`AUTH_INVALID_KEY`	全部	Key 非法/不存在/Secret 错
401	`AUTH_KEY_REVOKED`	全部	Key 已吊销
401	`AUTH_KEY_EXPIRED`	全部	Key 已过期
402	`INSUFFICIENT_BALANCE`	POST /orders、POST/PATCH /subusers	余额不足
403	`DEALER_SUSPENDED`	全部	账户停用
404	`PRODUCT_NOT_FOUND`	POST /orders、POST/PATCH /subusers	无此可购产品(编码未知或未对您开通)
422	`NO_DEALER_PRICE`	POST /orders、POST/PATCH /subusers	未为您配价 —— 联系客户经理
404	`ORDER_NOT_FOUND`	`GET /orders/{ref}`	无此订单
409	`IDEMPOTENCY_KEY_CONFLICT`	所有写接口	同 Key 处理中 — 稍后重发;或该 Key 已用于其它接口
422	`IDEMPOTENCY_KEY_CONFLICT`	所有写接口	同 Key 异 Body(或不同 `subuser_ref`)
422	`VALIDATION_ERROR`	所有写接口	参数缺失/非法,或数量过小
422	`ORDER_REJECTED`	POST /orders	下单被拒
429	`RATE_LIMITED`	全部	超限流
500	`INTERNAL_ERROR`	任意	服务器错误
500	`ORDER_STATE_UNKNOWN`	POST /orders	结果未核实 — 绝不换新 Key 重试;轮询 `GET /orders`
403	`SANDBOX_KEY_DISABLED`	全部	沙箱上线前 sandbox Key 全接口禁用
404	`SUBUSER_NOT_FOUND`	`/subusers/{ref}`	您的账户下没有这个子账号(`PATCH` 时指没有 active 的)
409	`SUBUSER_REF_CONFLICT`	POST /subusers	`subuser_ref` 已被用过 — 换一个
409	`SUBUSER_IN_FLIGHT`	POST /subusers	仍在建号 — 稍后用同一个 Key 原样重发
409	`SUBUSER_SUSPENDED`	POST /subusers	重发的建号对应的子账号已按之前的 `DELETE` 行为停用
422	`SUBUSER_CREATE_FAILED`	POST /subusers	未建成,扣款已退 — 用新 `subuser_ref` 和新 Key 重试
503	`SUBUSER_UNAVAILABLE`	POST /subusers	建号暂不可用,未扣费 — 稍后用新 Key 重试
500	`SUBUSER_STATE_UNKNOWN`	POST /subusers	结果未核实,扣款保留待人工核实(或重发建号时该子账号正在回收、或回收后等待客服处理)— 绝不换新 Key 或新 `subuser_ref`
500	`SUBUSER_CRED_UNREADABLE`	`GET /subusers/{ref}`	凭据暂时无法读取 — 联系客服
409	`SUBUSER_OP_IN_FLIGHT`	`PATCH`、`DELETE /subusers/{ref}`	另有操作进行中,或当前不能回收 — 稍后用新 Key 重试
409	`SUBUSER_NOT_ACTIVE`	`PATCH /subusers/{ref}`	子账号已不是 active;未扣费
422	`LIMIT_EXCEEDED`	`PATCH /subusers/{ref}`	加量后超过额度上限;未扣费
422	`TOPUP_FAILED`	`PATCH /subusers/{ref}`	未加上,扣款已退 — 2–3 分钟后用新 Key 重试
409	`TOPUP_IN_FLIGHT`	`PATCH /subusers/{ref}`	仍在处理,可能已扣款 — 稍后用同一个 Key 原样重发
500	`TOPUP_STATE_UNKNOWN`	`PATCH /subusers/{ref}`	结果未核实,扣款保留待人工核实 — 绝不换新 Key
409	`REVOKE_NOT_STARTED`	`DELETE /subusers/{ref}`	回收没有开始,什么都没改 — 2–3 分钟后用新 Key 重试
409	`REVOKE_IN_FLIGHT`	`DELETE /subusers/{ref}`	仍在处理 — 稍后用同一个 Key 原样重发
409	`REVOKE_IN_PROGRESS_OR_FAILED`	`DELETE /subusers/{ref}`	该 Key 暂无结果 — 稍后重发;仍如此则换新 Key 或联系客服
501	`REVOKE_NOT_SUPPORTED`	`DELETE /subusers/{ref}`	该产品不支持回收;什么都没改
500	`REVOKE_STATE_UNKNOWN`	`DELETE /subusers/{ref}`	结果未核实,核实期间不退款 — 绝不换新 Key;联系客服(见回收结果无法确认时)

FAQ

如何成为经销商 / 开通产品?

经销商账户由我方团队开通:注册经销商档案、开产品白名单、配置协议价。请联系支持或客户经理。

如何付款?

API 消费预付余额。线上:登录 hellworld.io 走余额充值(PayPal、加密货币等);线下:与客户经理约定打款后人工入账。两种方式都进入 API 扣款的同一余额。

下单成功但 GET /proxies 看不到?

GET /proxies 只列(a)对您开通且(b)至少购买过一次的产品。首单后凭据开通可能需要片刻 —— 先确认 GET /orders/{order_ref} 为 completed 再重试。

每笔订单都会生成新代理账号吗?

不会。同产品的购买累加到同一凭据 —— limit_gb 增长,用户名不变。如果需要每位客户一套账密,请用子账号。

used_gb 有多实时?

没有保证。目前调用 GET /proxies 时用量可能不会刷新,所以 used_gb 可能明显落后于实际消耗。usage_refresh_seconds(60)只是两次尝试刷新之间的最短间隔,不代表数据有多新。请当作近似值,不要据此给客户计费或停用客户;轮询频率高于每分钟一次也不会拿到更新的数据。子账号见下一条。

子账号的用量是实时的吗?

会在请求时刷新。GET /subusers/{subuser_ref} 每个子账号每 usage_refresh_seconds 秒最多刷新一次;看 usage_source:live 是这次刚读到的数值,cached 是上一次记录的数值(这次没有刷新或刷新失败),可能落后于实际消耗。刷新间隔只是节流,不是新鲜度保证;只用 live 的数值给客户计费或停用客户。

该用子账号还是下单?

下单是给每个产品一套共用凭据充值 —— 适合自己使用流量。子账号让每位客户都有自己的账密和额度,可以单独加量,也可以单独回收(按整数 GB 收回未用完的流量并退款到余额)。见子账号。

subuser_ref 能重复使用吗?

用它建出过子账号就不能再用。建号返回过 200、409 SUBUSER_IN_FLIGHT、422 SUBUSER_CREATE_FAILED 或 500 SUBUSER_STATE_UNKNOWN 之后,请把这个 ref 视为永久占用 —— 回收之后也一样。建号在什么都没建之前就被拒(400、402、404、503,或 422 VALIDATION_ERROR / NO_DEALER_PRICE / IDEMPOTENCY_KEY_*)时,这个 ref 仍然可用。每个新子账号请用新的 ref(例如客户 ID 加序号)。

子账号没用完的流量能退款吗?

能,按整数 GB 退。DELETE /subusers/{subuser_ref} 收回子账号未用完的已购流量里的整数 GB 部分,并按您为这个子账号付过的最低每 GB 单价退款。不足 1 GB 的零头,以及超出已购额度的流量,留在子账号上,不退款。详见 DELETE。

子账号花了多少钱在哪里看?

看余额(GET /balance)。子账号的扣款和退款都不是订单,不出现在 GET /orders 里,也不发 Webhook —— 请按 subuser_ref 和 Idempotency-Key 自行记账。

调用 DELETE 会断开我的客户吗?

不会。DELETE 按整数 GB 收回未用完的流量并退款;子账号仍为 active,凭据不变,上面剩下的流量照常可用。目前没有任何接口可以停用子账号或更换它的密码 —— 见要停用某位客户时。

回收返回了 500 REVOKE_STATE_UNKNOWN,怎么办?

回收结果无法确认 —— 可能的原因包括回收时子账号上还有流量在跑、网络侧的结果或我们的结算无法确认。核实期间不退款,在此之前 API 也不能给这个子账号加量或再次回收;子账号不会被停用、凭据不变,但剩余流量可能已经减少或被收回。请带上 subuser_ref 和 Idempotency-Key 联系客服。不要换新 Key 重试。详见回收结果无法确认时。

加量返回 422 TOPUP_FAILED(或回收返回 409 REVOKE_NOT_STARTED)?

什么都没有发生:没有加上流量,也没有收回流量,不扣费也不退款(加量的扣款已当场退回)。通常是因为子账号刚被改动过 —— 等 2–3 分钟后用新的 Idempotency-Key 重试。反复出现请联系客服。

收到 202 manual_review,扣款了吗?

扣了。订单已记录、余额已扣,只是履约需我方人工确认。不要换新 Idempotency-Key 重试(那会是第二笔独立订单),请轮询 GET /orders/{order_ref}。

有沙箱吗?

暂无 —— 沙箱 Key 目前全接口拒绝(403 SANDBOX_KEY_DISABLED)。Mock 沙箱在计划中。

能开通更多产品吗?

可以 —— 目录内任何产品都可按账户开通,联系客户经理。

经销商 API ​

概览 ​

鉴权 ​

产品 ​

GET /products ​

余额 ​

GET /balance ​

订单 ​

POST /orders ​

幂等 ​

GET /orders ​

GET /orders/{order_ref}GET /orders/{ref} ​

代理与消耗 ​

GET /proxies ​

子账号 ​

产品与计费 ​

快速上手 ​

POST /subusers建号 (POST) ​

GET /subusers列表 (GET) ​

GET /subusers/{subuser_ref}详情 (GET) ​

PATCH /subusers/{subuser_ref}加量 (PATCH) ​

DELETE /subusers/{subuser_ref}回收 (DELETE) ​

回收结果无法确认时回收结果未确认 ​

要停用某位客户时停用客户 ​

幂等与重试 ​

状态值 ​

时序与建议 ​

代理串格式 ​

ET Mobile(MOBILE-ET)ET Mobile ​

Geofast(RES-GEOFAST)Geofast ​

ET Hearth(RES-ETH)ET Hearth ​

自定义网关域名(白标) ​

配置 ​

规则 ​

会影响速度吗? ​

Webhook ​

错误码总表 ​

FAQ ​

经销商 API

概览

鉴权

产品

GET /products

余额

GET /balance

订单

POST /orders

幂等

GET /orders

GET /orders/{order_ref}GET /orders/{ref}

代理与消耗

GET /proxies

子账号

产品与计费

快速上手

POST /subusers建号 (POST)

GET /subusers列表 (GET)

GET /subusers/{subuser_ref}详情 (GET)

PATCH /subusers/{subuser_ref}加量 (PATCH)

DELETE /subusers/{subuser_ref}回收 (DELETE)

回收结果无法确认时回收结果未确认

要停用某位客户时停用客户

幂等与重试

状态值

时序与建议

代理串格式

ET Mobile(`MOBILE-ET`)ET Mobile

Geofast(`RES-GEOFAST`)Geofast

ET Hearth(`RES-ETH`)ET Hearth

自定义网关域名(白标)

配置

规则

会影响速度吗?

Webhook

错误码总表

FAQ