经销商 API

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

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

速览

Base URL:https://hellworld.io/openapi/v1
鉴权: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 — 获取代理凭据与实时流量消耗
按下方各产品的网关格式拼接代理串

当前可用产品(首批):

product_code	产品	类别	计费
`MOBILE-ET`	ET Mobile	移动	按 GB
`RES-GEOFAST`	Geofast	住宅	按 GB

如需更多产品,联系客户经理开通。

鉴权

在经销商门户(控制台 → 经销商门户 → 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 可随时在门户吊销并重建,吊销即时生效。

鉴权错误:

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

产品

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,下单时按平台默认价成交。

余额

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/

单个订单查询 —— 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`(不过期)

消耗新鲜度

每账户最多 60 秒刷新一次消耗;窗口内返回上次的值。轮询频率高于每分钟一次不会拿到更新的数据 —— 建议最多每分钟一次。

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

代理串格式

用 GET /proxies 返回的 username / password 拼代理串;国家定向与粘性会话编码在用户名里。

ET Mobile(`MOBILE-ET`)


网关	`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.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,用户名语法相同。

自定义网关域名(白标)

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

配置

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

你的记录	类型	目标
`mproxy.yourbrand.com`	`CNAME`	`etmobile.hellworld.io`
`proxy.yourbrand.com`	`CNAME`	`geofast.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,Geofast HTTP 6969 / SOCKS5 9696)。
凭据仍由本 API 下发——自定义域名只是换个主机名的品牌皮;username / password 始终来自 GET /proxies。

会影响速度吗?

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

Webhook

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

事件 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`	POST /orders	缺幂等键头
422	`IDEMPOTENCY_KEY_INVALID`	POST /orders	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	余额不足
403	`DEALER_SUSPENDED`	全部	账户停用
404	`PRODUCT_NOT_FOUND`	POST /orders	无此可购产品
422	`NO_DEALER_PRICE`	POST /orders	已在白名单但未设批发价
404	`PRODUCT_NOT_FOUND`	POST /orders	未知产品码
404	`ORDER_NOT_FOUND`	GET /orders/	无此订单
409	`IDEMPOTENCY_KEY_CONFLICT`	POST /orders	同 Key 处理中 — 稍后重发
422	`IDEMPOTENCY_KEY_CONFLICT`	POST /orders	同 Key 异 Body
422	`VALIDATION_ERROR`	POST /orders	参数非法
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 全接口禁用

FAQ

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

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

如何付款?

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

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

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

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

不会。同产品的购买累加到同一凭据 —— limit_gb 增长,用户名不变。

used_gb 有多实时?

每账户最多 60 秒刷新一次消耗(响应里的 usage_refresh_seconds)。轮询最多每分钟一次。

收到 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/ ​

代理与消耗 ​

GET /proxies ​

代理串格式 ​

ET Mobile(MOBILE-ET) ​

Geofast(RES-GEOFAST) ​

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

配置 ​

规则 ​

会影响速度吗? ​

Webhook ​

错误码总表 ​

FAQ ​

经销商 API

概览

鉴权

产品

GET /products

余额

GET /balance

订单

POST /orders

幂等

GET /orders

GET /orders/

代理与消耗

GET /proxies

代理串格式

ET Mobile(`MOBILE-ET`)

Geofast(`RES-GEOFAST`)

自定义网关域名(白标)

配置

规则

会影响速度吗?

Webhook

错误码总表

FAQ