接口规范定义

以下是您需要为我们提供的接口，我们将调用这些接口来管理用户余额和消费。

接口通用要求

• 协议：HTTPS

• 数据格式：JSON

• 字符编码：UTF-8

• 超时时间：建议5秒

所有接口通用响应格式

{
  "code": 10200,
  "success": true,
  "message": "OK",
  "data": {},
  "timestamp": 1760582574528
}

字段名	类型	说明
code	number	业务状态码。
success	boolean	是否成功。方便前端直接判断逻辑。
message	string	响应提示信息（例如 "OK"）
data	object	实际业务数据。
timestamp	number	服务器响应时间戳（毫秒）。

状态码对照表

状态码	含义	说明
10200	成功	请求处理成功
10400	参数错误	请求参数格式不正确
10401	签名验证失败	签名校验不通过
10402	余额不足	用户余额不足
10429	请求过于频繁	请稍后重试
10500	系统内部异常	服务器错误
10900	重复请求	相同的请求ID已处理

通用请求头

Header 名称	是否必填	示例值	说明
Authorization	是	Bearer apiKey	API 认证凭据
X-Signature	是	sha256Hex(sort(params)+apiSecret)	请求签名

签名算法

签名用于验证请求合法性。

计算公式：

计算公式

signature = sha256Hex(sort(params) + apiSecret)

计算步骤：

1. 对请求体参数（不包括空值）按参数名升序排序；

2. 拼接为字符串：

key1=value1&key2=value2&...

3. 在末尾拼接你的 apiSecret；

4. 对整个字符串计算 SHA256 Hex 哈希。

参数示例：

{
  "account": "680857435",
  "name": "sona",
  "avatar": "https://xxx.png",
  "gender": "male",
  "age": 18
}

计算字符串：

account=680857435&age=18&avatar=https://xxx.png&gender=male&name=sona

结果：

X-Signature: 8e2a0d7a9c0a55d92f123ab1d8913a2d12cd1b6b6a7c17b3bb6ef9a9b1a0e421