订单

通过 Orders 端点购买流量（住宅 / 移动）或 ISP 批次。不同产品使用不同子资源，但都共用 /orders 信封。

通用形态

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

响应：

{
  "id":         "ord_01HX2K3PQ4M5",
  "product":    "residential",
  "status":     "completed",
  "total_usd":  225.00,
  "details":    { "gb": 50, "price_per_gb": 4.50 },
  "created_at": "2026-05-28T10:00:00Z"
}

住宅 / 移动（按流量）

-d '{
  "product": "residential",        // 或 "mobile"
  "gb":      50
}'

带宽立即加入子账号池，账号下该产品的所有子账号共用。

ISP 批次

ISP 订单会创建一个批次——一组专属静态 IP。

curl -X POST -H "Authorization: Bearer API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "product":  "isp",
       "country":  "us",
       "city":     "newyork",
       "asn":      7922,
       "quantity": 20,
       "months":   1,
       "subuser":  "sub_01HX2K3PQ4M5"
     }' \
     https://api.helodata.com/v1/orders

返回订单信封 + batch_id（后续 IP 管理需用）：

{
  "id":         "ord_01HXabc",
  "product":    "isp",
  "status":     "provisioning",
  "total_usd":  120.00,
  "details": {
    "batch_id": "bat_01HXabc",
    "quantity": 20,
    "country":  "us",
    "city":     "newyork",
    "asn":      7922,
    "expires_at": "2026-06-28T10:00:00Z"
  }
}

status 流转：provisioning → completed（T1 通常 1–5 分钟，长尾国家最长 24 小时）。

ISP 批次生命周期

方法	路径	用途
GET	/isp/batches	列出批次
GET	/isp/batches/{id}	获取单批次
GET	/isp/batches/{id}/ips?format=plain|csv|json	下载 IP 清单
POST	/isp/batches/{id}/refresh	整批刷新（每周期一次）
POST	/isp/batches/{id}/renew	续费
POST	/isp/batches/{id}/rotate-password	修改批次密码
DELETE	/isp/batches/{id}	释放整批
POST	/isp/ips/{ip_id}/replace	替换单个失效 IP

列出

curl -H "Authorization: Bearer API_KEY" \
     https://api.helodata.com/v1/isp/batches

替换单 IP

curl -X POST -H "Authorization: Bearer API_KEY" \
     -d '{"reason":"target-blocked"}' \
     "https://api.helodata.com/v1/isp/ips/{ip_id}/replace"

购买后 14 天内免费替换，之后每周期免费额度为批次的 10%。详见 IP 管理。

续费

curl -X POST -H "Authorization: Bearer API_KEY" \
     -d '{"months":1}' \
     "https://api.helodata.com/v1/isp/batches/{id}/renew"

下单前查库存

curl -H "Authorization: Bearer API_KEY" \
     "https://api.helodata.com/v1/isp/inventory?country=us&asn=7922"

返回各 ASN 的可用数量、可选城市、定价。

错误

状态码	code	含义
409	insufficient_balance	账户余额不足
409	kyc_required	账号处于风险复核中，需完成 KYC 才能继续（默认不需要）
422	insufficient_inventory	指定地理/ASN 库存不足
422	quantity_out_of_range	数量 <5 或 >5000