认证与调用约定

Base URL：https://api.ipxss.com 业务接口统一 POST，请求体支持 application/json 或 application/x-www-form-urlencoded。

---

认证方式

公共 API 使用两段式认证：

步骤	做法
1	用注册邮箱 + API Key 调用令牌接口
2	使用返回的 Bearer Token 调用业务接口

项目	约定
Basic Auth 用户名	注册邮箱
Basic Auth 密码	API Key 原文
Token 默认有效期	7 天

---

获取访问令牌

POST /v1/oauth2/token
Authorization: Basic base64(email:api_key)

curl -X POST "https://api.ipxss.com/v1/oauth2/token" \
  -u "[email protected]:your_api_key"

成功响应：

{
  "code": 0,
  "data": {
    "access_token": "your_bearer_token",
    "expires_in": 604800,
    "token_type": "bearer"
  },
  "msg": "success",
  "timestamp": 1747036799
}

失败示例：

{
  "code": 40102,
  "data": null,
  "msg": "invalid username or api key",
  "timestamp": 1747036799
}

---

业务接口调用方式

除令牌接口外，其余接口统一使用 Bearer Token：

curl -X POST "https://api.ipxss.com/v1/wallet/balance" \
  -H "Authorization: Bearer your_bearer_token" \
  -H "Content-Type: application/json" \
  -d '{}'

成功响应示例：

{
  "code": 0,
  "data": {
    "balance": 125.5
  },
  "msg": "success",
  "timestamp": 1747037000
}

---

公共字段约定

字段	静态产品	说明
product	static-isp / static-dc	静态接口必填建议显式传递；不传时 static_house 默认 static-isp
ip_type	静态仅 normal	动态产品仍可能出现 premium；静态 ISP 传 premium 会被拒绝
duration	week / month	约 7 天 / 30 天
region	hk:1|us:2	地区码:数量，多项用 | 分隔
num	整数	必须等于 region 中数量之和

静态产品完整约定见 静态产品 API。

---

时间字段约定

涉及消耗日志和白名单筛选时，时间字段使用：

YYYY-MM-DD HH:MM:SS

示例：2026-04-08 00:00:00。如果结束时间早于开始时间，接口会直接返回参数错误。

---

返回结构

{
  "code": 0,
  "data": {},
  "msg": "success",
  "timestamp": 1747036799
}

字段	含义
code	0 表示成功
data	业务数据
msg	状态说明
timestamp	服务端时间戳

常见错误：

code	含义
40101	缺少认证信息或缺少 Bearer Token
40102	Token 非法、已过期，或 API Key 凭证错误
40103	API Key 已失效、已撤销或不可用
40001	请求参数格式错误或缺少必填字段
40002	业务校验未通过，例如余额不足、资源不存在
50201	上游开通失败
50001	服务端处理失败，请稍后重试

---

使用建议

1. 服务端集成时请缓存 Token，避免每次请求都重新获取。
2. 在批量调用前先检查余额与配额，减少失败请求。
3. 静态 ISP / 独享 DC 开通或续费时，在业务侧保留订单与资源映射。
4. 多产品线建议统一封装 API Client，复用 Token、错误处理和时间格式化。