代理商店

NexIP 代理商店的一般代理商品查询、购买、订单核对与续费，以及短效代理的套餐、国家、额度购买与按国家提取。购买与续费只传业务参数，由服务端按当前价格核算并直接扣减账户余额。

各类 ID 不能混用：购买用 /ip/products 的 productId；续费的 items 是本地代理 ID（代理列表的 id）；短效提取的 nexIpId 是短效订单 ID。业务接口的公共约定见服务与鉴权。

在本页搜索

显示 8 / 8 个接口

GET/ip/products

代理商品列表

查询当前在售的一般代理商品与周期报价，productId 用于 /ip/buy。

鉴权Bearer API Key

请求参数

无参数

注意事项

整单金额 = discountPrice × quantity × duration ÷ days，向上保留 2 位小数；/ip/buy 按此规则预检。
本接口不接受查询参数，多传字段返回 -1100。

响应字段

字段	类型	说明
`contextId`	`string`	本次请求的登录与团队上下文标识，可作为后续请求的 X-Nex-Service-Context
`data`	`object[]`	商品列表
`data[].productId`	`string`	商品 ID，购买时原样提交
`data[].type`	`string`	代理类型：native、broadcast、datacenter、mixed
`data[].name`	`string`	商品名称
`data[].countryCode`	`string`	国家码
`data[].countryName`	`string`	国家名称
`data[].locationCode`	`string`	地区码
`data[].locationName`	`string`	地区名称
`data[].days`	`number`	报价周期天数，不是购买数量
`data[].price`	`number`	上游周期报价
`data[].discountPrice`	`number`	实际售价，按 days 天计价
`data[].currency`	`string`	币种

响应示例

{
  "code": 0,
  "msg": "成功",
  "data": [
    {
      "productId": "us-native-lax",
      "type": "native",
      "name": "美国原生静态 IP",
      "countryCode": "US",
      "countryName": "美国",
      "locationCode": "LAX",
      "locationName": "洛杉矶",
      "days": 30,
      "price": 4.5,
      "discountPrice": 5.4,
      "currency": "USDT"
    }
  ],
  "contextId": "a3f5c2e1b7d94c0e8f6a1b2c3d4e5f60a3f5c2e1b7d94c0e8f6a1b2c3d4e5f6"
}

POST/ip/buy

购买代理

按商品、数量和天数购买一般代理并扣减余额；下单成功只表示已受理，代理异步交付。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
`productId`	`string`	必填	商品 ID，取自 /ip/products
`quantity`	`number`	必填	代理数量，正整数
`duration`	`number`	必填	购买天数，正整数

注意事项

业务参数校验后直接提交一次，由服务端按当前价格核算并扣费；客户端不预查价格、库存或套餐，权限与余额由服务端校验。
提交后不自动重试；超时或结果不明时先查 /ip/orders、/proxy/list 与 /billing/trades 核对，不要重复购买。
同一登录与团队下参数完全相同的购买仍在处理中时返回 -1100；未选择团队时同样返回 -1100。
交付在后台完成，交付前 resources 为空不代表失败；交付的代理会写入 /proxy/list（source=BUY）。

响应字段

字段	类型	说明
`contextId`	`string`	本次请求的登录与团队上下文标识，可作为后续请求的 X-Nex-Service-Context
`data`	`object`	新建的订单，state 通常为 PROCESSING
`data.id`	`number`	本地订单 ID；短效订单作为提取时的 nexIpId
`data.orderNo`	`string`	订单号
`data.userId`	`number`	购买用户 ID
`data.teamId`	`number`	资源所属团队 ID
`data.action`	`string`	订单动作：buy 购买、renew 续费
`data.productType`	`string`	订单类型：GENERAL 一般代理、SNAP 短效额度；历史一般订单可能为空
`data.type`	`string`	代理产品类型
`data.countryCode`	`string`	国家码
`data.locationCode`	`string`	地区码
`data.duration`	`number`	购买或续费天数
`data.quantity`	`number`	申请数量；短效订单为总额度
`data.quantitySuccess`	`number`	已交付或已提取数量
`data.amountInput`	`number`	初始扣款金额，USDT
`data.amountRefund`	`number`	已退款金额
`data.amount`	`number`	扣除退款后的金额
`data.state`	`string`	状态：PROCESSING、SUCCESS、FAILED
`data.product`	`string`	产品快照的 JSON 文本
`data.resources`	`string`	交付资源的 JSON 文本，含代理主机与明文凭据，可为 null
`data.remark`	`string`	订单说明，如活动赠送
`data.createdAt`	`string`	创建时间
`data.updatedAt`	`string`	更新时间

响应示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "id": 9001,
    "orderNo": "NIP20261023000001",
    "userId": 1001,
    "teamId": 2001,
    "action": "buy",
    "productType": "GENERAL",
    "type": "native",
    "countryCode": "US",
    "locationCode": "LAX",
    "duration": 30,
    "quantity": 2,
    "quantitySuccess": 0,
    "amountInput": 10.8,
    "amountRefund": 0,
    "amount": 10.8,
    "state": "PROCESSING",
    "product": "{\"productId\":\"us-native-lax\",\"days\":30,\"discountPrice\":5.4}",
    "resources": null,
    "remark": null,
    "createdAt": "2026-10-23 10:00:00",
    "updatedAt": "2026-10-23 10:00:00"
  },
  "contextId": "a3f5c2e1b7d94c0e8f6a1b2c3d4e5f60a3f5c2e1b7d94c0e8f6a1b2c3d4e5f6"
}

GET/ip/orders

代理订单列表

分页查询一般代理订单与短效额度记录，用于核对交付、续费与剩余额度。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
`page`	`number`	可选	页码，默认 1
`size`	`number`	可选	每页数量，默认 20，上限 1000

注意事项

GENERAL 的 PROCESSING 表示等待交付；SNAP 的 PROCESSING 表示仍有可提取额度，剩余额度为 quantity - quantitySuccess。
没有 PARTIAL_SUCCESS 状态，部分交付请结合 quantitySuccess、amountRefund 与 resources 判断。
本接口不接受 keyword；resources 含明文代理凭据，请勿转发给不受信任的调用方。

响应字段

字段	类型	说明
`contextId`	`string`	本次请求的登录与团队上下文标识，可作为后续请求的 X-Nex-Service-Context
`data.count`	`number`	匹配到的总条数
`data.size`	`number`	每页数量，回显请求值
`data.page`	`number`	当前页码，回显请求值
`data.total`	`number`	总页数
`data.data`	`object[]`	当前页记录
`data.data[].id`	`number`	本地订单 ID；短效订单作为提取时的 nexIpId
`data.data[].orderNo`	`string`	订单号
`data.data[].userId`	`number`	购买用户 ID
`data.data[].teamId`	`number`	资源所属团队 ID
`data.data[].action`	`string`	订单动作：buy 购买、renew 续费
`data.data[].productType`	`string`	订单类型：GENERAL 一般代理、SNAP 短效额度；历史一般订单可能为空
`data.data[].type`	`string`	代理产品类型
`data.data[].countryCode`	`string`	国家码
`data.data[].locationCode`	`string`	地区码
`data.data[].duration`	`number`	购买或续费天数
`data.data[].quantity`	`number`	申请数量；短效订单为总额度
`data.data[].quantitySuccess`	`number`	已交付或已提取数量
`data.data[].amountInput`	`number`	初始扣款金额，USDT
`data.data[].amountRefund`	`number`	已退款金额
`data.data[].amount`	`number`	扣除退款后的金额
`data.data[].state`	`string`	状态：PROCESSING、SUCCESS、FAILED
`data.data[].product`	`string`	产品快照的 JSON 文本
`data.data[].resources`	`string`	交付资源的 JSON 文本，含代理主机与明文凭据，可为 null
`data.data[].remark`	`string`	订单说明，如活动赠送
`data.data[].createdAt`	`string`	创建时间
`data.data[].updatedAt`	`string`	更新时间

响应示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "count": 1,
    "size": 20,
    "page": 1,
    "total": 1,
    "data": [
      {
        "id": 9001,
        "orderNo": "NIP20261023000001",
        "userId": 1001,
        "teamId": 2001,
        "action": "buy",
        "productType": "GENERAL",
        "type": "native",
        "countryCode": "US",
        "locationCode": "LAX",
        "duration": 30,
        "quantity": 2,
        "quantitySuccess": 2,
        "amountInput": 10.8,
        "amountRefund": 0,
        "amount": 10.8,
        "state": "SUCCESS",
        "product": "{\"productId\":\"us-native-lax\",\"days\":30,\"discountPrice\":5.4}",
        "resources": "[{\"type\":\"native\",\"status\":\"SUCCESS\",\"proxyId\":\"up-3001\",\"countryCode\":\"US\",\"proxy\":{\"host\":\"198.51.100.30\",\"port\":\"1080\",\"username\":\"proxy-user\",\"password\":\"proxy-password\",\"protocol\":\"SOCKS5\",\"expireAt\":\"2026-11-22 10:00:00\"}}]",
        "remark": null,
        "createdAt": "2026-10-23 10:00:00",
        "updatedAt": "2026-10-23 10:00:00"
      }
    ]
  },
  "contextId": "a3f5c2e1b7d94c0e8f6a1b2c3d4e5f60a3f5c2e1b7d94c0e8f6a1b2c3d4e5f6"
}

POST/ip/renew

续费代理

直接续费指定的本地代理并扣减余额；资源归属、可续费状态和实际费用由服务端校验。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
`items`	`number[]`	必填	本地代理 ID（/proxy/list 的 id），1 到 1000 个且不能重复；不是订单 ID
`duration`	`number`	必填	续费天数，正整数

注意事项

业务参数校验后直接提交一次，由服务端按当前价格核算并扣费；客户端不预查价格、库存或套餐，权限与余额由服务端校验。
提交后不自动重试；超时或结果不明时先查 /ip/orders、/proxy/list 与 /billing/trades 核对，不要重复购买。
同一登录与团队下参数完全相同的购买仍在处理中时返回 -1100；未选择团队时同样返回 -1100。
不再执行本地续费询价；服务端对资源和续费范围进行校验，业务错误原样透传。
多个原订单分组不保证同成同败；失败或超时的批次不要整批重提。

响应字段

字段	类型	说明
`contextId`	`string`	本次请求的登录与团队上下文标识，可作为后续请求的 X-Nex-Service-Context
`data`	`object[]`	续费订单，每个原订单分组一笔，字段同 /ip/orders 条目
`data[].id`	`number`	续费订单 ID
`data[].action`	`string`	固定为 renew
`data[].state`	`string`	订单状态
`data[].amount`	`number`	该组扣款金额

响应示例

{
  "code": 0,
  "msg": "成功",
  "data": [
    {
      "id": 9003,
      "orderNo": "NIP20261023000003",
      "userId": 1001,
      "teamId": 2001,
      "action": "renew",
      "productType": "GENERAL",
      "type": "native",
      "countryCode": "US",
      "locationCode": "LAX",
      "duration": 30,
      "quantity": 1,
      "quantitySuccess": 0,
      "amountInput": 5.4,
      "amountRefund": 0,
      "amount": 5.4,
      "state": "PROCESSING",
      "product": "{\"productId\":\"us-native-lax\",\"days\":30,\"discountPrice\":5.4}",
      "resources": null,
      "remark": null,
      "createdAt": "2026-10-23 10:00:00",
      "updatedAt": "2026-10-23 10:00:00"
    }
  ],
  "contextId": "a3f5c2e1b7d94c0e8f6a1b2c3d4e5f60a3f5c2e1b7d94c0e8f6a1b2c3d4e5f6"
}

GET/ip/snap/plans

短效代理套餐

读取当前短效代理额度套餐，购买时 num 必须等于其中某个 ipNum。

鉴权Bearer API Key

请求参数

无参数

注意事项

价格以每次读取的配置为准，不要缓存示例价格。

响应字段

字段	类型	说明
`contextId`	`string`	本次请求的登录与团队上下文标识，可作为后续请求的 X-Nex-Service-Context
`data`	`object[]`	套餐列表，来自应用配置 NEX_SNAP_IP_COMBO
`data[].ipNum`	`number`	套餐包含的提取额度
`data[].price`	`number \| string`	套餐总价，USDT

响应示例

{
  "code": 0,
  "msg": "成功",
  "data": [
    {
      "ipNum": 100,
      "price": "21.600"
    },
    {
      "ipNum": 500,
      "price": "98.000"
    }
  ],
  "contextId": "a3f5c2e1b7d94c0e8f6a1b2c3d4e5f60a3f5c2e1b7d94c0e8f6a1b2c3d4e5f6"
}

GET/ip/snap/products

短效代理国家

列出短效代理支持提取的国家，code 在提取时原样使用。

鉴权Bearer API Key

请求参数

无参数

注意事项

列表只表示支持的国家，不代表实时库存。

响应字段

字段	类型	说明
`contextId`	`string`	本次请求的登录与团队上下文标识，可作为后续请求的 X-Nex-Service-Context
`data`	`object[]`	国家列表
`data[].code`	`string`	两位国家码，作为 /ip/snap/pull 的 countryCode
`data[].name`	`string`	国家英文名
`data[].zhName`	`string`	国家中文名
`data[].flag`	`string`	国旗图标

响应示例

{
  "code": 0,
  "msg": "成功",
  "data": [
    {
      "code": "US",
      "name": "United States",
      "zhName": "美国",
      "flag": "🇺🇸"
    }
  ],
  "contextId": "a3f5c2e1b7d94c0e8f6a1b2c3d4e5f60a3f5c2e1b7d94c0e8f6a1b2c3d4e5f6"
}

POST/ip/snap/buy

购买短效代理额度

按套餐购买短效代理额度并扣减余额；购买后不会立即生成代理，需按国家分批提取。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
`num`	`number`	必填	套餐额度，必须等于 /ip/snap/plans 某项的 ipNum

注意事项

业务参数校验后直接提交一次，由服务端按当前价格核算并扣费；客户端不预查价格、库存或套餐，权限与余额由服务端校验。
提交后不自动重试；超时或结果不明时先查 /ip/orders 与 /billing/trades 核对，不要重复购买。
同一登录与团队下参数完全相同的购买仍在处理中时返回 -1100；未选择团队时同样返回 -1100。
套餐是否可用由服务端校验，服务端业务错误原样透传。

响应字段

字段	类型	说明
`contextId`	`string`	本次请求的登录与团队上下文标识，可作为后续请求的 X-Nex-Service-Context
`data`	`object`	新建的短效订单，productType 为 SNAP
`data.id`	`number`	本地订单 ID，提取时作为 nexIpId
`data.quantity`	`number`	总额度
`data.quantitySuccess`	`number`	已提取数量，初始为 0
`data.state`	`string`	订单状态，初始为 PROCESSING

响应示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "id": 9002,
    "orderNo": "NIP20261023000002",
    "userId": 1001,
    "teamId": 2001,
    "action": "buy",
    "productType": "SNAP",
    "type": null,
    "countryCode": null,
    "locationCode": null,
    "duration": null,
    "quantity": 100,
    "quantitySuccess": 0,
    "amountInput": 21.6,
    "amountRefund": 0,
    "amount": 21.6,
    "state": "PROCESSING",
    "product": null,
    "resources": null,
    "remark": null,
    "createdAt": "2026-10-23 10:00:00",
    "updatedAt": "2026-10-23 10:00:00"
  },
  "contextId": "a3f5c2e1b7d94c0e8f6a1b2c3d4e5f60a3f5c2e1b7d94c0e8f6a1b2c3d4e5f6"
}

POST/ip/snap/pull

提取短效代理

从已购短效额度中按国家提取代理；消耗额度，不是只读查询。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
`nexIpId`	`number`	必填	短效订单的本地 ID，取自 /ip/snap/buy 或 /ip/orders
`countryCode`	`string`	必填	两位大写国家码，取自 /ip/snap/products 的 code
`num`	`number`	必填	本次提取数量，正整数且不超过剩余额度

注意事项

提取的代理由服务端写入代理列表并累计到订单 resources，可在 /proxy/list 中按 ID 选用。
提取消耗额度且不自动重试；超时或结果不明时先刷新 /ip/orders 核对 quantitySuccess，不要再次提取。
额度不足时服务端返回 -1208；响应包含明文代理凭据。

响应字段

字段	类型	说明
`contextId`	`string`	本次请求的登录与团队上下文标识，可作为后续请求的 X-Nex-Service-Context
`data`	`object[]`	本次提取的代理
`data[].host`	`string`	代理主机
`data[].port`	`string \| number`	代理端口
`data[].username`	`string`	代理认证用户名
`data[].password`	`string`	代理认证密码（明文）
`data[].protocol`	`string`	代理协议
`data[].expireAt`	`string`	到期时间

响应示例

{
  "code": 0,
  "msg": "成功",
  "data": [
    {
      "host": "us.snap.example.net",
      "port": 20001,
      "username": "snap-user",
      "password": "snap-password",
      "protocol": "SOCKS5",
      "expireAt": "2026-10-23 10:30:00"
    }
  ],
  "contextId": "a3f5c2e1b7d94c0e8f6a1b2c3d4e5f60a3f5c2e1b7d94c0e8f6a1b2c3d4e5f6"
}