# 概览

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

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

## Base URL

```
https://api.helodata.com/v1
```

所有端点 URL 中带版本。破坏性变更通过新主版本发布，并提供 6 个月废弃过渡期——详见 [更新日志](/helodata-zh/zi-yuan/changelog.md)。

## 身份认证

每次 API 调用都需要从 **控制台 → API** 签发的 Bearer Token。详见 [身份认证](/helodata-zh/api-can-kao/authentication.md)。

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

## 资源一览

| 资源                                                | 端点                       | 用途           |
| ------------------------------------------------- | ------------------------ | ------------ |
| [用户](/helodata-zh/api-can-kao/users.md)           | `/users`                 | 账号资料与安全      |
| [子账号](/helodata-zh/api-can-kao/sub-users.md)      | `/subusers`              | 按产品的凭证与限额    |
| [订单](/helodata-zh/api-can-kao/orders.md)          | `/orders`、`/isp/batches` | IP 批次的购买与管理  |
| [订阅](/helodata-zh/api-can-kao/subscriptions.md)   | `/subscriptions`         | 周期性流量与 IP 套餐 |
| [流量与用量](/helodata-zh/api-can-kao/traffic.md)      | `/{product}/traffic`     | 带宽与请求分析      |
| [白名单](/helodata-zh/api-can-kao/whitelists.md)     | `/whitelists`            | 认证用的 IP 白名单  |
| [会话](/helodata-zh/api-can-kao/sessions.md)        | `/{product}/sessions`    | 查看活跃粘性会话     |
| [报表](/helodata-zh/api-can-kao/reports.md)         | `/reports`               | 定时或临时导出      |
| [限流](/helodata-zh/api-can-kao/rate-limits.md)     | —                        | 限流策略         |
| [Postman 集合](/helodata-zh/api-can-kao/postman.md) | —                        | 全 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`

错误示例：

```json
{
  "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 的重试得到相同响应，便于安全地重试网络故障。

```bash
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 页（即将发布）。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.helodata.com/helodata-zh/api-can-kao/api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.