IPMAXAPI V1

本文档描述了 LZ 代理服务的完整 API 接口，包括账户管理、位置查询、订单管理和实例操作等功能。

认证方式

所有开放 API 请求都需要在 Header 中携带以下参数：

Header	必填	说明
`app-id`	是	API 应用 ID，对应 `key_manage_info.app_id`
`app-secret`	是	API 应用密钥，对应 `key_manage_info.app_secret`
`language`	否	当前项目语言，`zh` 或 `en`
`Content-Type`	POST/PUT 必填	固定使用 `application/json`

统一返回结构

除远程回调外，开放 API 的响应都会使用统一结构。

{
  "code": 200,
  "data": {},
  "msg": "请求成功"
}

字段	类型	说明
`code`	integer	状态码，`200` 表示成功，`401` 表示认证失败，`500` 表示业务失败
`data`	any	实际业务数据，不同接口结构不同
`msg`	string	返回消息

静态代理接口

以下接口对应静态代理业务，文档路径统一以 /api/v1 为前缀。

2.1 获取产品列表

GET /api/v1/product/list?type=®ion=

参数	类型	必填	说明
`type`	integer	否	产品类型，空表示全部
`region`	integer	否	区域 ID，空表示全部

{
  "code": 200,
  "msg": "请求成功",
  "data": [
    {
      "id": 1,
      "name": "US ISP",
      "type": 1,
      "regionId": 10,
      "price": 100.0,
      "stock": 100,
      "createTime": "2026-06-24 12:00:00"
    }
  ]
}

2.2 计算订单价格

POST /api/v1/order/calc

字段	类型	必填	说明
`productId`	integer	是	产品 ID
`nums`	integer	是	购买数量
`period`	integer	是	周期，见下方枚举
`couponStr`	string	否	优惠券码

{
  "code": 200,
  "msg": "请求成功",
  "data": {
    "oldAmount": 100.00,
    "payAmount": 90.00,
    "discountAmount": 10.00,
    "couponAmount": 0.00
  }
}

2.3 购买 IP

POST /api/v1/ip/make

字段	类型	必填	说明
`productId`	integer	是	产品 ID
`nums`	integer	是	购买数量，必须大于 0
`period`	integer	是	周期，见下方枚举
`subOrderId`	string	否	客户侧订单 ID，会在远程回调中原样返回
`keyId`	integer	否	API Key 配置 ID；为空不回调

购买成功后返回 支付成功，IP 部署完成后系统会通过远程回调发送 MAKE 事件。

2.4 续费 IP

POST /api/v1/ip/renewal

字段	类型	必填	说明
`ipId`	integer	是	系统 IP ID
`period`	integer	是	续费周期，见下方枚举
`subOrderId`	string	否	客户侧续费订单 ID，会在远程回调中原样返回
`keyId`	integer	否	API Key 配置 ID；为空不回调

续费完成后会发送 RENEWAL 事件。

2.5 查询 IP 列表

GET /api/v1/ip/list?ip=&productType=&status=

参数	类型	必填	说明
`ip`	string	否	IP 模糊查询
`productType`	integer	否	产品类型
`status`	integer	否	IP 状态：0 不可用，1 可用，2 即将到期，3 已过期

2.6 查询订单列表

GET /api/v1/order/list?id=&type=&status=

参数	类型	必填	说明
`id`	integer	否	系统订单 ID
`type`	integer	否	订单类型：1 购买，2 续费
`status`	integer	否	订单状态：0 待处理，1 已支付/待部署，2 部署完成

2.7 更新自动续费状态

PUT /api/v1/ip/autoRenewal

字段	类型	必填	说明
`id`	integer	是	系统 IP ID
`autoRenewal`	boolean	是	是否开启自动续费

回调通知机制

如果传入 keyId，系统会在订单状态变化时向 retUrl 发起回调。

远程回调说明

说明	内容
回调地址	`key_manage_info.ret_url`
请求方式	`POST {retUrl}`
成功判定	HTTP 状态码返回 200 即视为成功
重试规则	失败回调最多重试 10 次，按失败次数递增，最长约 60 分钟间隔

回调事件

type	说明	触发场景
`MAKE`	IP 部署完成	购买 IP 后，上游部署完成并生成 IP
`RENEWAL`	IP 续费成功	续费成功并更新过期时间
`IP_CHANGE`	IP 发生变更	上游 IP 变更
`EXPIRING_SOON`	IP 即将到期	IP 即将到期，开启自动续费时不发送
`EXPIRED`	IP 已过期	IP 到期

{
  "type": "MAKE",
  "orderId": 123,
  "subOrderId": "client-order-001",
  "ipId": 456,
  "ip": "1.2.3.4",
  "status": 1,
  "expiredTime": "2026-07-24",
  "data": {
    "productId": 1,
    "productName": "US ISP",
    "period": 1,
    "nums": 1,
    "orderType": 1
  }
}

接收方处理建议

建议	说明
幂等处理	建议使用 `type + orderId + ipId` 作为幂等键
正确响应	接收成功后返回 HTTP 200 即可，系统只判断状态码
查询兜底	若没有收到回调，可以通过查询 IP 接口获取结果

错误码

代码	消息
加载中...

动态代理

动态代理接口正在整理中，后续会按同一风格补充到这里。