概览

helodata REST API 让你用代码完成控制台里能点的所有事——子账号、订单、白名单、流量报表——便于自动化分发、计费管线、自建仪表盘。

API 与代理网关分离：网关在 gate.helodata.io，API 在 api.helodata.com。

Base URL

https://api.helodata.com/v1

所有端点 URL 中带版本。破坏性变更通过新主版本发布，并提供 6 个月废弃过渡期——详见 更新日志。

身份认证

每次 API 调用都需要从 控制台 → API 签发的 Bearer Token。详见 身份认证。

curl -H "Authorization: Bearer API_KEY" https://api.helodata.com/v1/users/me

资源一览

资源	端点	用途
用户	/users	账号资料与安全
子账号	/subusers	按产品的凭证与限额
订单	/orders、/isp/batches	IP 批次的购买与管理
订阅	/subscriptions	周期性流量与 IP 套餐
流量与用量	/{product}/traffic	带宽与请求分析
白名单	/whitelists	认证用的 IP 白名单
会话	/{product}/sessions	查看活跃粘性会话
报表	/reports	定时或临时导出
限流	—	限流策略
Postman 集合	—	全 API 可导入的集合

约定

• Content-Type：所有写入请求使用 application/json
• 日期：RFC 3339 / ISO 8601，UTC
• ID：按资源类型前缀的 ULID（sub_01HX…、bat_01HX…、ord_01HX…）
• 分页：基于游标 ?cursor=…&limit=…；Link 头指向下一页
• 错误：结构化 JSON，含 code、message、request_id

错误示例：

{
  "code":       "invalid_argument",
  "message":    "region must be a 2-letter ISO 3166 code",
  "request_id": "req_01HX2K3PQ4M5",
  "field":      "region"
}

联系客服请带上 request_id，便于我们追溯调用。

幂等性

写入类端点接受 Idempotency-Key 头——最长 64 字符的任意字符串。带同一 key 的重试得到相同响应，便于安全地重试网络故障。

curl -X POST \
     -H "Authorization: Bearer API_KEY" \
     -H "Idempotency-Key: order-2026-05-28-001" \
     -H "Content-Type: application/json" \
     -d '{"product":"residential","gb":50}' \
     https://api.helodata.com/v1/orders

Webhooks

通过 控制台 → API → Webhooks 订阅事件（订单完成、批次即将到期、流量阈值）。Payload 格式与签名密钥见 Webhooks 页（即将发布）。