美国
英国
德国
日本
泰国
墨西哥
印度
新加坡
中国香港海外静态IP查询
更新时间：2026-07-09
本文档介绍海外静态 IP 查询接口，支持按套餐类型、国家、地区等条件筛选，返回当前用户分配的静态 IP 列表及认证信息。
一、公共说明
1.1 请求域名
所有 OpenAPI 接口统一通过以下域名访问：
https://openapi.fanproxy.com
1.2 请求头要求
所有 OpenAPI 接口均通过 网关（Gateway） 进行签名认证，请求必须携带以下请求头。
必填请求头
| 请求头名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| X-Api-Key | String | 是 | 用户账号，即手机号 |
| X-Api-Signature | String | 是 | API 签名凭证，由平台生成，可前往官网控制台查看 |
| X-Api-Timestamp | String | 是 | 请求时间戳（秒），用于防重放攻击 |
请求头示例
POST /open-api/open/overseas/subaccount/add HTTP/1.1
Host: openapi.fanproxy.com
Content-Type: application/json
X-Api-Key: your_api_key_here
X-Api-Signature: your_signature_here
X-Api-Timestamp: 1711000000
1.3 统一响应格式
所有接口均返回统一的 JSON 结构，便于客户端统一解析处理：
响应字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
| code | Integer | 状态码，200 表示成功 |
| success | Boolean | 操作是否成功，true / false |
| data | Object/Array/null | 响应数据，成功时返回业务数据，失败时为 null |
| message | String | 错误描述信息，成功时为 null |
成功响应示例
{
"code": 200,
"success": true,
"data": { ... },
"message": null
}
失败响应示例
{
"code": 20000102,
"success": false,
"data": null,
"message": "子账号不存在"
}
1.4 错误码说明
业务层统一使用 OpenApiApiExceptionEnum（一般为 2000xxxx 段）。部分接口在调用内部 Facade 失败时，会透传下游返回的 code 与 message（非 200 且非下表枚举值时，以响应体为准）。
全局错误码表
| 错误码 | 说明 | 来源 |
|---|---|---|
| 200 | 成功 | 业务层 |
| 401 | 签名认证失败（缺少 Key、签名无效、请求过期、重复请求等） | 网关层 |
| 20000001 | 用户信息缺失（如缺少 X-Api-User-Id） | 业务层（@OpenApiAuth 校验 / 子账号锁） |
| 20000002 | 缺少开放接口账号头信息（缺少 X-Api-App-Key） | 业务层（@OpenApiAuth） |
| 20000003 | 用户中心查询失败 | 业务层（@OpenApiAuth） |
| 20000004 | 密钥与签名归属账号不一致 | 业务层（@OpenApiAuth） |
| 20000005 | 系统繁忙，请稍后重试（或同类前缀的详细 message） | 业务层（通用失败/异常兜底） |
| 20000101 | 操作频繁，请稍候（子账号接口分布式锁未获取到） | 业务层 |
| 20000102 | 子账号不存在 | 业务层 |
| 20000301 | 未找到指定的子账号（认证账号流量信息） | 业务层 |
| 20001001~20001014 | 参数校验（账户名、密码、套餐类型、时间等；含流量记录时间窗与区间） | 业务层 |
| 20002001 | 无效的套餐类型（订单查询 mealType） | 业务层 |
| 其他整数 | 内部服务 R 返回的非 200 code | 下游 Facade |
网关认证失败（401）时的响应体格式：
{
"code": 401,
"message": "缺少X-Api-Key请求头",
"timestamp": 1711000000000,
"path": "/open-api/open/overseas/subaccount/add",
"authType": "api_sign",
"traceId": "abc-123"
}
二、海外静态 IP 查询
接口地址：POST /open-api/open/overseas/ip/static
接口描述：查询当前用户的海外静态 IP 分配列表，支持按套餐类型、国家、地区等筛选。
2.1 请求参数（Body - JSON）
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| ipType | Integer | 是 | 套餐类型：1-住宅/共享/双 ISP，2-住宅/共享/原生双 ISP，3-住宅/独享，4-数据中心/共享/IPv4 |
| countryName | String | 否 | 国家名称（中文），如 “美国” |
| regionName | String | 否 | 地区名称（中文），如 “俄勒冈” |
| cmiId | Integer | 否 | 套餐 ID |
| expiry | Boolean | 否 | 是否过期：false-未过期，true-已过期 |
2.2 请求示例
{
"ipType": 1,
"countryName": "美国",
"regionName": "俄勒冈",
"expiry": false
}
2.3 返回字段说明（data 字段）
data 为 List<StaticIpItem>（直接返回数组）。
StaticIpItem 字段说明
| 字段名 | 类型 | 说明 |
|---|---|---|
| accountPassword | String | 账号和密码（格式：账号:密码） |
| addressStr | String | 国家地区名称 |
| cmiId | String | 套餐 ID |
| endTime | Long | 到期时间（秒时间戳） |
| ipPort | String | IP 地址 |
| lineIpPort | String | 代理地址（格式：ip:port） |
| ipType | String | 套餐类型描述 |
2.4 返回示例
{
"code": 200,
"success": true,
"data": [
{
"accountPassword": "user123:pass456",
"addressStr": "美国-俄勒冈",
"cmiId": "123",
"endTime": 1735660799,
"ipPort": "203.0.113.10",
"lineIpPort": "203.0.113.10:8080",
"ipType": "住宅双ISP"
},
{
"accountPassword": "user456:pass789",
"addressStr": "美国-加利福尼亚",
"cmiId": "124",
"endTime": 1735660799,
"ipPort": "203.0.113.20",
"lineIpPort": "203.0.113.20:8080",
"ipType": "住宅双ISP"
}
],
"message": null
}
2.5 错误码
| 错误码 | 说明 / 触发条件 |
|---|---|
| 200 | 成功 |
| 401 | 网关签名认证失败 |
| 20000001 | 缺少 X-Api-User-Id |
| 20000002 | 缺少 X-Api-App-Key |
| 20000003 | 用户中心查询失败 |
| 20000004 | 密钥与签名归属账号不一致 |
| 20001009 | ipType 为空（请求体或解析后为 null） |
| 动态/异常码 | BusinessException：内部 queryIpAllocationList 等链路抛出时，由 OpenApiExceptionAdvice 转为统一 JSON，错误码与 message 以异常为准 |
| 20000005 | 非 BusinessException 的未预期异常（message 前缀「查询静态 IP 异常: …」） |