# 白名单

管理子账号与 ISP 批次的 IP 白名单。把出口 IP 加入白名单后，从该 IP 发出的请求可免 `Proxy-Authorization`——适合无凭证的服务器对服务器场景。

## 作用范围

白名单按**资源**作用：

* **子账号白名单** — 用于网关产品（`residential`、`mobile`）。IP 仅在该子账号、该产品下生效。
* **ISP 批次白名单** — IP 对该批次的所有 IP 生效。

同一来源 IP 可独立加入多个白名单。

## 端点

| 方法       | 路径                                 | 用途       |
| -------- | ---------------------------------- | -------- |
| `GET`    | `/whitelists?subuser={id}`         | 列出子账号白名单 |
| `POST`   | `/whitelists`                      | 添加 IP    |
| `DELETE` | `/whitelists/{id}`                 | 删除 IP    |
| `GET`    | `/isp/batches/{id}/whitelist`      | 列出批次白名单  |
| `POST`   | `/isp/batches/{id}/whitelist`      | 添加到批次    |
| `DELETE` | `/isp/batches/{id}/whitelist/{id}` | 从批次移除    |

## 添加到子账号

```bash
curl -X POST -H "Authorization: Bearer API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "subuser": "sub_01HX2K3PQ4M5",
       "product": "residential",
       "ip":      "203.0.113.5",
       "label":   "prod-eu-west-1"
     }' \
     https://api.helodata.com/v1/whitelists
```

响应：

```json
{
  "id":         "wl_01HX2K3PQ4M5",
  "subuser":    "sub_01HX2K3PQ4M5",
  "product":    "residential",
  "ip":         "203.0.113.5",
  "label":      "prod-eu-west-1",
  "active":     true,
  "created_at": "2026-05-28T10:00:00Z"
}
```

### IP / CIDR 格式

| 输入                          | 是否接受              |
| --------------------------- | ----------------- |
| 单个 IPv4（`203.0.113.5`）      | 是                 |
| IPv4 CIDR（`203.0.113.0/24`） | 是——每条最大 `/24`     |
| IPv6                        | 是（完整地址或 `/64` 以内） |
| 主机名                         | 否                 |

## 列出

```bash
curl -H "Authorization: Bearer API_KEY" \
     "https://api.helodata.com/v1/whitelists?subuser=sub_01HX2K3PQ4M5&product=residential"
```

## 删除

```bash
curl -X DELETE -H "Authorization: Bearer API_KEY" \
     "https://api.helodata.com/v1/whitelists/wl_01HX2K3PQ4M5"
```

约 60 秒内生效。

## ISP 批次白名单

```bash
# 列出
curl -H "Authorization: Bearer API_KEY" \
     "https://api.helodata.com/v1/isp/batches/bat_01HXabc/whitelist"

# 添加
curl -X POST -H "Authorization: Bearer API_KEY" \
     -d '{"ip":"203.0.113.5","label":"prod"}' \
     "https://api.helodata.com/v1/isp/batches/bat_01HXabc/whitelist"

# 删除
curl -X DELETE -H "Authorization: Bearer API_KEY" \
     "https://api.helodata.com/v1/isp/batches/bat_01HXabc/whitelist/wl_01HX..."
```

## 上限

| 范围        | 最大条目 |
| --------- | ---- |
| 每子账号（每产品） | 50   |
| 每 ISP 批次  | 50   |

一个 `/24` CIDR 算 1 条，网关在服务端展开。

## 错误

| 状态码   | code                  | 含义                            |
| ----- | --------------------- | ----------------------------- |
| `409` | `already_whitelisted` | 该 IP/CIDR 已在白名单中              |
| `422` | `invalid_cidr`        | CIDR 比 `/24`（v4）或 `/64`（v6）更宽 |
| `422` | `over_limit`          | 超过 50 条                       |


---

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