Skip to main content

静态代理

1. 接口概述​

静态 IP V2 API 提供了完整的静态住宅代理 IP 管理功能，包括查询可用资源、创建代理、续费等操作。

2. 获取国家列表​

请求方式： GET /v2/static-residential/listCountry

功能描述： 获取支持的国家代码列表

请求参数​

无需请求参数

响应数据格式​

字段名类型说明
dataArray<String>国家代码数组，如：["US", "UK", "CA"]

响应示例​

成功响应：

{
  "code": 200,
  "msg": "操作成功",
  "data": ["US", "UK", "CA", "AU", "DE", "FR"]
}

3. 获取城市列表​

请求方式： GET /listCity

功能描述： 根据国家代码获取支持的城市列表

请求参数​

参数名类型必填说明
country_codeString是国家代码，如：US、UK 等

响应数据格式​

字段名类型说明
dataArray<String>城市名称数组，如：["New York", "Los Angeles"]

响应示例​

成功响应：

{
  "code": 200,
  "msg": "操作成功",
  "data": ["New York", "Los Angeles", "Chicago", "Houston"]
}

4. 获取业务名称集合​

请求方式： GET /listBusiness

功能描述： 获取可用的业务名称列表

请求参数​

无需请求参数

响应数据格式​

字段名类型说明
dataArray<Object>业务名称对象数组
data[].BusinessNameString业务名称，如：general、social_media、e_commerce

响应示例​

成功响应：

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "BusinessName": "YouTube"
    },
    {
      "BusinessName": "TikTok"
    },
    {
      "BusinessName": "other"
    }
  ]
}

5. 获取空闲 IP 数​

请求方式： POST /countIdleIP

功能描述： 查询指定条件下的可用 IP 数量

请求参数​

参数名类型必填说明示例值
country_codeString是国家编码US
city_nameString否城市名称，空表示随机New York
businessString是业务名称，通过 listBusiness 接口获取general
line_typeInteger是IP 质量：1-基础，2-标准，3-高端1

请求示例​

{
  "country_code": "US",
  "city_name": "New York",
  "business": "YouTube",
  "line_type": 1
}

响应数据格式​

字段名类型说明
dataInteger可用 IP 数量

响应示例​

成功响应：

{
  "code": 200,
  "msg": "操作成功",
  "data": 1250
}

6 创建静态代理 IP​

请求方式： POST /newIP

功能描述： 创建新的静态代理 IP 订单

权限要求： 需要客户访问控制权限

请求参数​

参数名类型必填说明限制示例值
country_codeString是国家编码-US
city_nameString否城市名称，空表示随机-New York
daysInteger是购买的代理天数可选值：1、7、15、30、60、90、36530
countInteger是购买的代理数量1-50010
line_typeInteger是IP 质量：1-基础，2-标准，3-高端1-31
is_udpInteger否UDP 启用：1 启用，0 不启用0-1，默认 00
businessString是业务类型，通过 listBusiness 接口获取-general
customer_idInteger否指定下单用户，null 表示自己-null

请求示例​

{
  "country_code": "US",
  "city_name": "New York",
  "days": 30,
  "count": 10,
  "line_type": 1,
  "is_udp": 0,
  "business": "YouTube",
  "customer_id": null
}

响应数据格式​

字段名类型说明
dataObject创建结果对象
data.order_idString订单号
data.totalInteger创建的 IP 数量
data.amountDouble订单金额
data.currencyString计费货币
data.created_atDate创建时间
data.expired_atDate到期时间
data.allotsArray<Object>分配的代理信息数组
data.allots[].ipString出口 IP 地址
data.allots[].node_domainString代理服务器域名
data.allots[].node_portInteger代理端口
data.allots[].accountString代理账号
data.allots[].passwordString代理密码

响应示例​

成功响应：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "order_id": "20240521174348201395",
    "total": 2,
    "amount": 15.5,
    "currency": "USD",
    "created_at": "2024-12-19T10:30:00Z",
    "expired_at": "2025-01-18T10:30:00Z",
    "allots": [
      {
        "ip": "192.168.1.100",
        "node_domain": "proxy1.example.com",
        "node_port": 8080,
        "account": "user123",
        "password": "pass456"
      },
      {
        "ip": "192.168.1.101",
        "node_domain": "proxy2.example.com",
        "node_port": 8080,
        "account": "user124",
        "password": "pass457"
      }
    ]
  }
}

7. 静态代理续费​

请求方式： POST /renewIP

功能描述： 为现有静态代理 IP 续费

权限要求： 需要客户访问控制权限

请求参数​

参数名类型必填说明限制示例值
ipString是要续费的 IP 地址-192.168.1.100
daysInteger是续费天数可选值：1、7、15、30、60、90、36530

请求示例​

{
  "ip": "192.168.1.100",
  "days": 30
}

响应数据格式​

字段名类型说明
dataObject续费结果对象
data.order_idString续费订单号
data.totalInteger续费的 IP 数量
data.amountDouble续费金额
data.currencyString计费货币
data.created_atDate续费时间
data.expired_atDate新的到期时间
data.allotsArray<Object>续费的代理信息数组
data.allots[].ipString续费的 IP 地址
data.allots[].node_domainString代理服务器域名
data.allots[].node_portInteger代理端口
data.allots[].accountString代理账号
data.allots[].passwordString代理密码

响应示例​

成功响应：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "order_id": "20240521174348201395",
    "total": 1,
    "amount": 7.75,
    "currency": "USD",
    "created_at": "2024-12-19T10:30:00Z",
    "expired_at": "2025-02-18T10:30:00Z",
    "allots": [
      {
        "ip": "192.168.1.100",
        "node_domain": "proxy1.example.com",
        "node_port": 8080,
        "account": "user123",
        "password": "pass456"
      }
    ]
  }
}

8. 调试测试​

您可以使用以下工具测试 API 接口：

获取国家列表​

curl -X GET "http://user.ipweb.cc/prod-api/v2/static-residential/listCountry" \
     -H "Token: your_access_token_here"

获取城市列表​

curl -X GET "http://user.ipweb.cc/prod-api/v2/static-residential/listCity?country_code=US" \
     -H "Token: your_access_token_here"

获取业务名称集合​

curl -X GET "http://user.ipweb.cc/prod-api/v2/static-residential/listBusiness" \
     -H "Token: your_access_token_here"

获取空闲 IP 数​

curl -X POST "http://user.ipweb.cc/prod-api/v2/static-residential/countIdleIP" \
     -H "Token: your_access_token_here" \
     -H "Content-Type: application/json" \
     -d '{
       "country_code": "US",
       "city_name": "New York",
       "business": "YouTube",
       "line_type": 1
     }'

创建静态代理 IP​

curl -X POST "http://user.ipweb.cc/prod-api/v2/static-residential/newIP" \
     -H "Token: your_access_token_here" \
     -H "Content-Type: application/json" \
     -d '{
       "country_code": "US",
       "city_name": "New York",
       "days": 30,
       "count": 1,
       "line_type": 1,
       "is_udp": 0,
       "business": "YouTube",
       "customer_id": null
     }'

静态代理续费​

curl -X POST "http://user.ipweb.cc/prod-api/v2/static-residential/renewIP" \
     -H "Token: your_access_token_here" \
     -H "Content-Type: application/json" \
     -d '{
       "ip": "192.168.1.100",
       "days": 30
     }'

注意： 请将 your_access_token_here 替换为您的实际 Token。建议使用 Postman 或其他专业的 API 测试工具进行测试。

9. 错误码说明​

以下是静态 IP 相关 API 接口可能返回的错误码及其说明：

静态 IP 业务相关错误码​

错误码说明解决方案
2000静态 IP 不属于客户账号下检查 IP 是否属于当前账户
2001静态 IP 库存不足当前选择的地区暂无可用 IP，请选择其他地区或稍后重试
2002静态 IP 已被占用选择其他可用的 IP 地址
2003静态 IP 配置失败检查配置参数，稍后重试
2004静态 IP 续费失败检查账户余额和续费参数
2005静态 IP 已过期重新购买或续费 IP
2006静态 IP 不存在指定的 IP 地址不存在或已被释放
2100可选天数: 1、7、15、30、60、90、365 天天数参数必须为：1、7、15、30、60、90、365 中的一个
2101当前 IP 仅支持: 30、60、90、365 天当前 IP 的续费天数仅支持：30、60、90、365 天

10. 错误响应示例​

静态 IP 库存不足示例​

{
  "code": 2001,
  "msg": "静态IP库存不足",
  "data": null
}

静态 IP 不存在示例​

{
  "code": 2006,
  "msg": "静态IP不存在",
  "data": null
}

天数参数错误示例​

{
  "code": 2100,
  "msg": "可选天数: 1、7、15、30、60、90、365天",
  "data": null
}

续费天数限制示例​

{
  "code": 2101,
  "msg": "当前IP仅支持: 30、60、90、365天",
  "data": null
}

© 2024 静态 IP V2 API 接口文档 - 版本 1.9.0

最后更新时间： 2024 年 12 月 19 日