# Postman 集合

我们提供持续维护的 Postman 集合，覆盖本节所有端点，外加三款上线产品的代理示例请求。

## 导入

### 从 URL

Postman 中：**Import → Link**，粘贴：

```
https://api.helodata.com/v1/postman/collection.json
```

集合在每次 API 发布时更新，重新导入即可刷新。

### 从文件

下载一次，再拖到 Postman：

```bash
curl -H "Authorization: Bearer API_KEY" \
     https://api.helodata.com/v1/postman/collection.json \
     -o helodata.postman_collection.json
```

本文档仓库也直接附带集合文件，路径 [`assets/helodata.postman_collection.json`](https://github.com/teokunsuper/helodata-docs/blob/main/assets/helodata.postman_collection.json)，外加起步环境 [`assets/helodata-prod.postman_environment.json`](https://github.com/teokunsuper/helodata-docs/blob/main/assets/helodata-prod.postman_environment.json)——一并导入开箱可用。

## 包含内容

```
helodata/
├── 0 — Welcome
├── 1 — Auth check (GET /users/me)
├── 2 — Sub-users
│   ├── List
│   ├── Create
│   ├── Get
│   ├── Update
│   ├── Rotate password
│   └── Delete
├── 3 — Orders
│   ├── Create residential
│   ├── Create mobile
│   └── Create ISP batch
├── 4 — ISP batches
│   ├── List
│   ├── Download IPs (plain / csv / json)
│   ├── Replace IP
│   ├── Refresh batch
│   └── Renew
├── 5 — Subscriptions
├── 6 — Traffic & reports
├── 7 — Whitelists
├── 8 — Sessions
└── 9 — Proxy gateway samples
    ├── Residential — basic
    ├── Residential — city + session
    ├── Mobile — ASN-pinned
    └── ISP — single IP
```

## 环境

集合附两个可导入环境：

* **helodata-prod** — 生产端点
* **helodata-test** — 沙箱（即将上线）

需你填入的变量：

| 变量             | 值                |
| -------------- | ---------------- |
| `api_key`      | 你的 API Token     |
| `subuser_name` | 例如 `s1a2b3c4d5e` |
| `subuser_pass` | 子账号密码            |
| `isp_ip`       | 代理示例用的某个 ISP IP  |

## 在 Newman 中运行（CI）

```bash
newman run helodata.postman_collection.json \
       --environment helodata-prod.postman_environment.json \
       --env-var "api_key=$HELODATA_API_KEY" \
       --folder "1 — Auth check"
```

适合凭证轮换后做 CI 冒烟测试。

## OpenAPI

如果工具偏好 OpenAPI，相同接口也以 OpenAPI 规范发布：

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

兼容 Swagger UI、Redoc、Stoplight 及多数代码生成器。

## 版本管理

`collection.json` 与 `openapi.json` 与 API 本身共用 `/v1` 版本号。破坏性变更发布时会推出新主版本规范；旧版本仍可在 `/v0/...`、`/v1/...` 等地址导入。


---

# 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/postman.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.