IPMAXAPI V2

URL: https://www.ipmax.cc/api/v2

IPMAXAPI V2

本文档描述当前系统字段版本的开放 API。v1 继续兼容字段和返回语义；v2 使用当前项目的数据字段，不再做 v1 的字段转换。

认证方式

所有 v2 接口都需要在 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`

响应格式

接口响应会被统一包装。

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

v2 和 v1 的主要区别

项目	v1	v2
产品流量字段	`trafficLimit`	`traffic`
产品返回	兼容 VO	当前 `ProductPublicVO`
订单返回	兼容 VO，状态会转换	当前 `OrderInfo` 字段，状态不转换
IP 返回	兼容 VO	当前 `IpInfo` 字段
下单/续费返回	余额支付成功字符串	当前 `PayVO`
下单通知	依赖传入 `keyId`	不传 `keyId` 时自动绑定当前 `app-id` 对应秘钥

字段字典

产品类型	值
ISP	1
IPV4	2
动态流量	3

订单类型	值
购买	1
续费	2
自动续费	3

订单状态	值
待支付	1
已支付/处理中	2
已完成	3

IP 状态	值
正在分配	0
正常	1
即将到期	2
过期	3

支付方式 payType	值
余额支付	0
在线支付渠道	1-9

1. 产品列表

GET /api/v2/product/list?regionId=5&type=1

参数	类型	必填	说明
`type`	number	否	产品类型：1 ISP，2 IPV4，3 动态流量
`regionId`	number	否	区域 ID
`region`	number	否	`regionId` 的兼容别名；同时传入时优先使用 `regionId`

[
  {
    "id": 1,
    "name": "美国",
    "nameEn": "United States",
    "type": 1,
    "regionId": 5,
    "price": 10.0,
    "img": "https://flagcdn.com/us.svg",
    "hot": true,
    "traffic": 1000000000,
    "sort": 100
  }
]

2. 订单价格预览

POST /api/v2/order/calc

字段	类型	必填	说明
`type`	number	否	订单类型；不传默认 `1`
`productId`	number	是	产品 ID
`nums`	number	否	数量；不传默认 `1`
`period`	number	否	周期；不传默认 `1`
`cidr`	string	否	购买静态 IP 时的号段
`couponId`	number	否	优惠券 ID
`couponStr`	string	否	优惠券 code

{
  "oldAmount": 100.0,
  "payAmount": 80.0,
  "discountAmount": 10.0,
  "couponAmount": 10.0
}

3. 创建订单并发起支付

POST /api/v2/order/submit?payType=0

也兼容 POST /api/v2/ip/make?payType=0。

字段	类型	必填	说明
`payType`	number	是	可放在 query，也可放请求体；query 优先
`type`	number	否	不传默认 `1`
`productId`	number	是	产品 ID
`nums`	number	否	数量；不传默认 `1`
`period`	number	否	周期；不传默认 `1`
`cidr`	string	否	号段，后端会校验是否属于产品可用号段
`purposeId`	number	否	产品用途 ID
`couponId`	number	否	优惠券 ID
`couponStr`	string	否	优惠券 code
`subOrderId`	string	否	调用方自己的订单号
`keyId`	number	否	秘钥 ID；不传时后端自动绑定当前 `app-id` 对应秘钥
`path`	string	否	在线支付完成跳转地址
`remarks`	string	否	备注

{
  "payRecordId": 123
}

{
  "payRecordId": 123,
  "url": "https://pay.example.com/..."
}

4. 续费

POST /api/v2/ip/renewal

字段	类型	必填	说明
`ipId`	number	是	IP ID，`id` 也可作为别名
`payType`	number	是	支付方式
`period`	number	是	续费周期
`subOrderId`	string	否	客户端续费订单 ID
`path`	string	否	支付完成跳转地址
`remarks`	string	否	备注

也支持路径方式 POST /api/v2/ip/renew/{id}/{payType}。

{
  "payRecordId": 124
}

5. IP 列表

GET /api/v2/ip/list?type=1&status=1

参数	类型	必填	说明
`ip`	string	否	IP 模糊搜索
`type`	number	否	IP 产品类型
`productType`	number	否	`type` 的兼容别名；同时传入时优先使用 `type`
`productId`	number	否	产品 ID
`vendorId`	number	否	供应商 ID
`status`	number	否	IP 状态
`autoRenewal`	boolean	否	是否自动续费

[
  {
    "id": 10,
    "userId": 1,
    "userInfo": "user@example.com",
    "orderId": 100,
    "type": 1,
    "productId": 1,
    "productName": "美国",
    "vendorId": 1,
    "ip": "1.1.1.1",
    "httpPort": 8080,
    "socketsPort": 1080,
    "userName": "username",
    "password": "password",
    "status": 1,
    "createTime": "2026-08-18 10:00:00",
    "expiredTime": "2026-09-18 10:00:00",
    "autoRenewal": true,
    "remarks": "备注"
  }
]

v2 的 IP 返回不会暴露 packageKey、vendorIpId、saleId、orderNumber。

6. IP 分页

POST /api/v2/ip/page/1/10

字段	类型	必填	说明
`type`	number	否	IP 产品类型
`productId`	number	否	产品 ID
`vendorId`	number	否	供应商 ID
`status`	number	否	IP 状态
`autoRenewal`	boolean	否	是否自动续费
`ip`	string	否	IP 信息
`productName`	string	否	产品名称
`remarks`	string	否	备注

{
  "records": [],
  "total": 0,
  "size": 10,
  "current": 1,
  "pages": 0
}

7. 订单列表

GET /api/v2/order/list?type=1&status=2

参数	类型	必填	说明
`id`	number	否	订单 ID
`type`	number	否	订单类型
`status`	number	否	当前系统订单状态，不做 v1 状态转换
`productType`	number	否	产品类型
`productId`	string	否	产品 ID，支持模糊查询
`productName`	string	否	产品名称，支持模糊查询
`ip`	string	否	IP 信息，支持模糊查询

[
  {
    "id": 100,
    "userId": 1,
    "saleId": 4,
    "userInfo": "user@example.com",
    "type": 1,
    "amount": 80.0,
    "subOrderId": "client-order-001",
    "keyId": 1,
    "couponId": 10,
    "productId": "1",
    "productType": 1,
    "productName": "美国",
    "nums": 1,
    "period": 1,
    "cidr": "1.1.1.0/24",
    "ip": "1.1.1.1",
    "ipIds": "10",
    "status": 2,
    "createTime": "2026-08-18 10:00:00",
    "doneTime": null,
    "appId": null
  }
]

8. 订单分页

POST /api/v2/order/page/1/10

字段	类型	必填	说明
`id`	number	否	订单 ID
`type`	number	否	订单类型
`productType`	number	否	产品类型
`status`	number	否	订单状态
`productId`	string	否	产品 ID
`productName`	string	否	产品名称
`ip`	string	否	IP 信息
`subOrderId`	string	否	客户端订单号

{
  "records": [],
  "total": 0,
  "size": 10,
  "current": 1,
  "pages": 0
}

9. 自动续费开关

PUT /api/v2/ip/autoRenewal

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

也支持 PUT /api/v2/ip/autoRenewal/10/true 和 POST /api/v2/ip/autoRenewal/10/1。

true

异步通知

下单和续费时会保存 keyId。如果请求体传了 keyId，后端校验该秘钥必须属于当前 API 用户；如果没有传，v2 会自动使用当前 app-id 对应的秘钥 ID。

通知体

{
  "type": "MAKE",
  "orderId": 100,
  "subOrderId": "client-order-001",
  "ipId": 10,
  "ip": "1.1.1.1",
  "status": 1,
  "expiredTime": "2026-09-18T02:00:00.000+00:00",
  "data": {
    "productId": 1,
    "productName": "美国",
    "period": 1,
    "nums": 1,
    "orderType": 1
  }
}

事件类型

type	说明
`MAKE`	购买成功
`RENEWAL`	续费成功
`IP_CHANGE`	IP 变更
`EXPIRING_SOON`	即将到期
`EXPIRED`	已过期

接收方处理建议

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

错误码

code	msg	说明
400	PARAM_ERROR	参数错误
400	BALANCE_NOT_ENOUGH	余额不足
400	ORDER_STATUS_INVALID	订单状态不允许操作
401	app not found	`app-id` 不存在或未传
401	secret error	`app-secret` 错误
403	ip not allowed	请求 IP 不在白名单
403	PERMISSIONS	无权限或数据不属于当前用户
404	NOT_FOUND	数据不存在