通用规范
请求规范
基础信息
| 项目 | 说明 |
|---|---|
| 协议 | HTTPS |
| 编码 | UTF-8 |
| 数据格式 | JSON |
| HTTP 方法 | GET / POST / PUT / DELETE |
公共请求头
所有 API 请求必须携带以下请求头：
| Header | 必填 | 说明 |
|---|---|---|
X-App-Key | 是 | 应用的 AppKey |
X-Timestamp | 是 | 请求时间戳（秒级），有效期 ±5分钟 |
X-Nonce | 是 | 随机字符串（8-32位），防重放 |
X-Sign | 是 | 请求签名，参见 签名算法 |
Content-Type | 是（POST/PUT） | application/json |
请求示例
http
GET /v1/merchants?page=1&size=10 HTTP/1.1
Host: openapi.example.com
X-App-Key: ak_1234567890abcdef
X-Timestamp: 1709280000
X-Nonce: a1b2c3d4e5f6
X-Sign: 7d2f8a9b1c3e4d5f6a7b8c9d0e1f2a3b响应规范
响应结构
所有接口返回统一的 JSON 结构：
json
{
"code": 0,
"msg": "success",
"data": {}
}| 字段 | 类型 | 说明 |
|---|---|---|
code | int | 状态码，0表示成功，非0表示失败 |
msg | string | 状态描述 |
data | object | 业务数据，失败时可能为null |
分页响应
列表查询接口返回分页结构：
json
{
"code": 0,
"msg": "success",
"data": {
"list": [],
"total": 100,
"page": 1,
"size": 10
}
}分页参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
page | int | 1 | 页码，从1开始 |
size | int | 10 | 每页条数，最大100 |
数据类型
| 类型 | 格式 | 示例 |
|---|---|---|
| 时间 | ISO 8601 | 2026-03-10T14:30:00+08:00 |
| 金额 | 分（整数） | 9900 表示 99.00 元 |
| 布尔 | boolean | true / false |
| ID | long | 1234567890 |
HTTP 状态码
| 状态码 | 说明 |
|---|---|
| 200 | 请求成功 |
| 400 | 请求参数错误 |
| 401 | 签名验证失败 / AppKey 无效 |
| 403 | 无权限访问该接口或数据 |
| 404 | 请求的资源不存在 |
| 429 | 请求频率超限 |
| 500 | 服务器内部错误 |