白名单

管理子账号与 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}	从批次移除

添加到子账号

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

响应：

{
  "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 以内）
主机名	否

列出

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

删除

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

约 60 秒内生效。

ISP 批次白名单

# 列出
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 条