静态产品 API
适用产品：静态 ISP 代理（
product=static-isp）与 独享数据中心代理（product=static-dc）。 Base URL：https://api.ipxss.com全部接口走POST，请求体支持application/json或application/x-www-form-urlencoded。 响应统一结构：{ "code": 0, "data": {...}, "msg": "success", "timestamp": 1747036799 }，code != 0表示错误。
两个产品共用同一套 /v1/static_house/* 路径，通过请求体 product 区分。未传 product 时默认 static-isp。
1. 已开放接口
| 能力 | 路径 | 静态 ISP | 独享数据中心 |
|---|---|---|---|
| 换取访问令牌 | POST /v1/oauth2/token | ✅ | ✅ |
| 查询可售地区与库存 | POST /v1/static_house/region | ✅ | ✅ |
| 已分配 IP 列表 | POST /v1/static_house/list | ✅ | ✅ |
| 导出 IP 列表（CSV） | POST /v1/static_house/export | ✅ | ✅ |
| 下单开通 | POST /v1/static_house/open | ✅ | ✅ |
| 续费 | POST /v1/static_house/renew | ✅ | ✅ |
| 自动续费开关（推荐） | POST /v1/static_house/auto_renew | ✅ | ✅ |
| 自动续费开关（兼容） | POST /v1/static_house/renew_setting | ✅ | ✅ |
| 出货 webhook | POST /v1/static_house/webhook | ✅ | ✅ |
| 钱包余额 | POST /v1/wallet/balance | ✅ | ✅ |
| 钱包流水 | POST /v1/wallet/usage_record | ✅ | ✅ |
静态 ISP 仅标准档（
ip_type=normal），premium会被拒绝。独享数据中心不区分档位。时长为week（约 7 天）或month（约 30 天）。公开响应只含平台转发接入信息，不含上游渠道名或厂商凭证。
认证、钱包通用约定见 认证与调用约定 与 钱包、白名单与查询接口。
2. 接入步骤
2.1 申请凭证
- 用户登录 IPxSS 控制台，进入「设置 → API 密钥」生成 API Key。
- 第三方拿到
用户邮箱 + API Key两段凭证；API Key 等同密码，仅服务端保存。
2.2 换取 access_token
http
POST /v1/oauth2/token
Authorization: Basic base64(email:api_key)
Content-Type: application/x-www-form-urlencoded成功响应：
json
{
"code": 0,
"data": {
"access_token": "eyJhbGciOi...",
"expires_in": 604800,
"token_type": "bearer"
},
"msg": "success",
"timestamp": 1747036799
}- 默认 TTL：7 天。
- 后续业务请求均通过
Authorization: Bearer <access_token>携带。 - 建议本地缓存 token，到期前 1 天主动重换，不要每次请求都换。
3. 公共字段约定
| 字段 | 取值 | 说明 |
|---|---|---|
product | static-isp / static-dc | 不传默认为 static-isp；新接入请显式传递 |
ip_type | normal | static-isp 必填；premium 拒绝。static-dc 可不传，若传只能是 normal |
duration / package_type | week / month | 约 7 天或 30 天 |
region | us:2|hk:1 或 MIXISP-7973:50 | 多地区用 | 分隔；地区码与数量用 : 分隔；总和必须等于 num |
num | 整数 | 本次下单总 IP 数量 |
page / limit | 分页 | 默认 1 / 10；limit 上限 100（导出接口为 10000） |
地区码规则：
- 国家级：ISO Alpha-2 大写，如
US、GB、HK。无城市级库存；传入US-NY一类编码时按国家码校验。 - 以
/v1/static_house/region返回为准，不要写死历史国家表。 - 「套餐包」分组的
region为MIXISP-<id>（ISP）或MIXIPV4-<id>（DC），quantities仅20/50/100/200。一次只能下一个套餐，不可与国家码混下。
isp_type（isp-resi/isp-resi-hq）已废弃，请统一使用ip_type。
4. 业务接口
4.1 查询地区与库存
http
POST /v1/static_house/region
Authorization: Bearer <token>| 字段 | 必填 | 说明 |
|---|---|---|
product | 否 | static-isp 或 static-dc，默认 static-isp |
ip_type | static-isp 时必填 | 仅 normal |
响应要点：
| 字段 | 含义 |
|---|---|
data.list | 按文档分组的地区列表，可能含「套餐包」 |
data.stock_as_of | 库存快照 Unix 时间；当前无同步表快照时为 0 |
地区项 region / node / node_en / stock | 编码、中英文名、可下单标记 |
套餐项 quantities | 仅 20 / 50 / 100 / 200 |
stock为1表示可下单，不是精确剩余条数。为0或不在列表中表示不可售。
请求示例：
json
{
"product": "static-isp",
"ip_type": "normal"
}json
{
"product": "static-dc"
}4.2 下单开通
http
POST /v1/static_house/open
Authorization: Bearer <token>| 字段 | 必填 | 示例 | 说明 |
|---|---|---|---|
product | 否 | static-isp | 默认 static-isp |
ip_type | static-isp 时必填 | normal | DC 固定 normal 或可省略 |
duration | 是 | week / month | 约 7 天或 30 天 |
num | 是 | 3 | 必须等于 region 数量合计 |
region | 是 | hk:1|us:2 | 套餐包如 MIXISP-7973:50、MIXIPV4-<id>:50 |
notify_url | 否 | https://example.com/hook | HTTPS；需先登记 webhook 密钥才会投递 |
当前实现：
- 校验参数与数量，按国家或套餐单价扣减钱包；余额不足直接失败，不会只开通部分资源。
- 会创建订单、订阅和静态分配记录。
- 响应只含平台转发
http/socks5（ISP 端口10000/10001，DC 端口6666/6667），账号为ng_static_*。 - 新购可能异步出货：
awaiting_fulfillment=true且 allocationstatus=0（pending）时，请轮询 list，直到status=1且出现exit_ip。也可登记 webhook 收static.ready。
成功响应示例：
json
{
"code": 0,
"data": {
"quote": {
"amountUsd": 4.5,
"quantity": 1,
"duration": "month"
},
"order": {
"order_no": "PX202604080001",
"amount_usd": 4.5,
"product_code": "static-isp",
"quantity": 1,
"duration_label": "每月",
"status": "paid"
},
"allocations": [
{
"id": "alloc-1",
"http": {
"protocol": "http",
"host": "hk-server1.ipxss.com",
"port": "10000",
"account": "ng_static_isp_us_xxx",
"password": "***"
},
"socks5": {
"protocol": "socks5",
"host": "hk-server1.ipxss.com",
"port": "10001",
"account": "ng_static_isp_us_xxx",
"password": "***"
},
"status": 0,
"status_label": "pending"
}
],
"awaiting_fulfillment": true,
"gatewayRedisRefreshScheduled": true
},
"msg": "success",
"timestamp": 1747037000
}下单失败常见原因：
| code | 含义 |
|---|---|
40001 | 参数不合法（地区码、数量不匹配、ip_type 取值错误等） |
40002 | 钱包余额不足 / 地区不可售 / 业务校验失败，msg 给出具体原因 |
50201 | 上游开通失败 |
4.3 已分配列表
http
POST /v1/static_house/list
Authorization: Bearer <token>只返回当前 Bearer Token 对应账号名下的资源，不会跨账号串出其他采购人的线路。
| 字段 | 说明 |
|---|---|
product | static-isp / static-dc，默认 static-isp |
page / limit | 分页，默认 1 / 10，limit 最大 100 |
status | 0 待分配、1 使用中、2 已过期、3 已释放；留空=全部 |
region | 按地区码过滤，大写 |
key_word / keyword | IP / 账号 / 订单号 / 国家 模糊匹配 |
is_auto_renew | 1=仅自动续费；0 或 -1=仅未开自动续费；留空=全部 |
单条资源项：
| 字段 | 含义 |
|---|---|
id | 分配 ID（自动续费时使用） |
http / socks5 | 平台转发接入块（host、port、account、password） |
exit_ip | 已确认的公网出口 IPv4；pending 时不返回 |
region / country | 地区码与展示名 |
expire_time | 到期时间戳（秒） |
duration | 距到期剩余秒数 |
provisioned_at / duration_label / product_code / order_no | 开通时间、周期文案、产品、订单号 |
status / status_label | 0/pending、1/in_use、2/expired、3/released |
auto_renew | 1=已开启 |
type | 新购恒为 0；历史高级 ISP 可能为 1；DC 恒为 0 |
响应顶层还包含 page、total。
请求示例：
json
{
"product": "static-dc",
"page": 1,
"limit": 20,
"status": 1,
"region": "HK",
"is_auto_renew": 1
}4.4 导出资源
http
POST /v1/static_house/export
Authorization: Bearer <token>返回 text/csv（不是标准 JSON），Content-Disposition 文件名为 static-isp-export.csv 或 static-dc-export.csv。筛选参数与 list 相同。CSV 列：
id,host,http_port,socks_port,account,password,exit_ip,region,status,status_label,auto_renew,expire_time,provisioned_at,duration_label,order_no
4.5 续费
http
POST /v1/static_house/renew
Authorization: Bearer <token>| 字段 | 必填 | 说明 |
|---|---|---|
product | 否 | 默认 static-isp |
duration | 是 | week 或 month |
renew_ip_list | 是 | 逗号分隔的 出口 IP，不是分配 id |
任一 IP 不属于当前账号则整单失败。成功后写入续费订单和钱包流水，并更新到期时间。
json
{
"product": "static-isp",
"renew_ip_list": "203.0.113.10,203.0.113.11",
"duration": "month"
}响应重点：order、transaction、items[].allocation.expires_at、gatewayRedisRefreshScheduled。
4.6 自动续费开关
推荐：
http
POST /v1/static_house/auto_renew
Authorization: Bearer <token>| 字段 | 必填 | 说明 |
|---|---|---|
ids | 是 | 分配 ID，逗号分隔 |
enabled | 是 | true / false |
package_type | 否 | week / month |
product | 否 | 默认 static-isp |
兼容旧客户端：
http
POST /v1/static_house/renew_setting
Authorization: Bearer <token>| 字段 | 必填 | 说明 |
|---|---|---|
type | 是 | 固定值 static_house |
ids | 是 | 分配 ID，逗号分隔 |
package_type | 是 | week / month |
status | 是 | 1=开启，-1=关闭 |
product | 否 | 默认 static-isp |
json
{
"product": "static-dc",
"type": "static_house",
"ids": "7c9f2d5d-1111-2222-3333-444444444444",
"package_type": "month",
"status": 1
}开启后，调度器会在到期前自动扣款续费（默认每 5 分钟检查；余额不足则到期后标记 expired）。手动续费会继承原 auto_renew 设置。
4.7 出货 webhook
http
POST /v1/static_house/webhook
Authorization: Bearer <token>异步出货时不要只靠轮询。空 body 表示查询当前配置（不回显 secret）。
| 字段 | 说明 |
|---|---|
url / notify_url / webhook_url | HTTPS 回调地址，禁止 localhost / 内网 |
enabled | true / false |
rotate_secret | true 时轮换密钥，新 secret 只返回一次 |
服务端 POST JSON，请求头：
| 头 | 含义 |
|---|---|
X-IPxSS-Event | static.allocated（上游 IP 已写入，可能仍 pending）或 static.ready（落地验证通过，出现 exit_ip） |
X-IPxSS-Signature | sha256=<hex>，对原始请求体用登记的 secret 做 HMAC-SHA256 |
body 中的 allocations 与 list 条目相同，仅含平台转发，不含上游渠道信息。open 的 notify_url 需先有登记密钥才会投递。
5. 错误码
| code | 含义 | HTTP 状态 |
|---|---|---|
0 | 成功 | 200 |
40001 | 参数校验失败 | 400 |
40002 | 业务校验失败（余额、库存、产品状态、IP 不属于当前账号等） | 400 |
40101 | 缺少 Basic Auth 凭证 | 401 |
40102 | 用户邮箱或 API Key 不正确 | 401 |
40103 | access_token 缺失或失效 | 401 |
50001 | 服务内部错误 | 500 |
50201 | 上游开通失败 | 502 |
超出限流返回 HTTP 429。单 API Key 默认 60 req/min。
6. 调用样例（curl）
bash
# 1. 换 token
TOKEN=$(curl -s -X POST https://api.ipxss.com/v1/oauth2/token \
-u "[email protected]:my_api_key" \
| jq -r .data.access_token)
# 2. 查地区
curl -s -X POST https://api.ipxss.com/v1/static_house/region \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"product":"static-isp","ip_type":"normal"}' | jq
# 3. 开通：1 个 HK + 2 个 US，月付
curl -s -X POST https://api.ipxss.com/v1/static_house/open \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"product":"static-isp",
"ip_type":"normal",
"duration":"month",
"num":3,
"region":"hk:1|us:2"
}' | jq
# 4. 看已分配
curl -s -X POST https://api.ipxss.com/v1/static_house/list \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"product":"static-isp","page":1,"limit":20}' | jq
# 5. 续费两个 IP
curl -s -X POST https://api.ipxss.com/v1/static_house/renew \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"product":"static-isp","duration":"month","renew_ip_list":"203.0.113.10,203.0.113.11"}' | jq
# 6. 独享数据中心：2 个美国 IP，月付
curl -s -X POST https://api.ipxss.com/v1/static_house/open \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"product":"static-dc","duration":"month","num":2,"region":"us:2"}' | jq
# 7. 周付套餐包
curl -s -X POST https://api.ipxss.com/v1/static_house/open \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"product":"static-isp","ip_type":"normal","duration":"week","num":50,"region":"MIXISP-7973:50"}' | jq
# 8. 登记出货 webhook
curl -s -X POST https://api.ipxss.com/v1/static_house/webhook \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/ipxss-hook","enabled":true}' | jq7. 对接清单
| 步骤 | 需要做的事 |
|---|---|
| 1 | 在 IPxSS 控制台注册账号并生成 API Key |
| 2 | 在自己的服务端保存 email + api_key，不要落到浏览器 |
| 3 | 调 /v1/oauth2/token 换 access_token，本地缓存到剩余 1 天时刷新 |
| 4 | 调 /v1/static_house/region 拉地区列表 |
| 5 | 下单前先调 /v1/wallet/balance，再调 /v1/static_house/open |
| 6 | 把线路交给终端用户前，确认 status=1 且已有 exit_ip；也可登记 webhook 收 static.ready |
| 7 | 定期调 /v1/static_house/list 同步到期时间，到期前调 /v1/static_house/renew 或开启自动续费 |
8. 已知限制
- 库存无精确计数：
stock=1只表示国家可售；open若因无货失败，换国家或稍后重试。 - 异步出货：
open成功不等于立刻能连。awaiting_fulfillment=true或status=0时请轮询 list。 - 没有优质 ISP：
ip_type=premium会被拒绝。 - 不提供退货：上游无法回收已售 IP，公开 API 没有退货接口；误购请联系商务。
- 下单失败钱包不会扣款：
40002/50201失败路径会回滚事务。 - 重复下单：需调用方自己做幂等；当前接口不基于
client_request_id去重。 - 响应不含上游渠道：只使用平台转发
http/socks5与已确认的exit_ip。