API 开发者文档（四）：公共约定

API 开发文档更新于 2026-10-22 66 次阅读

公共请求参数

参数	类型	必填	说明
page	int	否	页码，从 1 开始，默认 1。仅列表类接口支持。
per_page	int	否	每页条数，默认 20，取值范围 1~50，超过 50 按 50 处理。仅列表类接口支持。

参数可放在查询字符串（Query String）、表单请求体（application/x-www-form-urlencoded）或 JSON 请求体中。服务端按「查询字符串 → 表单 → JSON」的顺序合并，同名参数以后者为准。

签名范围：只有请求体（body）参与签名，查询字符串不参与。若把参数放在 URL 上，请确保签名时的 body 与实际发送的 body 一致（通常为空字符串）。

统一返回格式

所有响应均为 UTF-8 编码的 JSON 对象，HTTP 状态码正常时为 200。

成功响应

{
  "code": 0,
  "message": "ok",
  "data": { ... }
}

失败响应

{
  "code": 403,
  "message": "This API key does not have permission to call order.create",
  "data": null,
  "error": { "code": "forbidden_scope" }
}

字段	类型	说明
code	int	成功固定为 0；失败时与 HTTP 状态码一致（401/403/404/429/500/503）。
message	string	成功为 ok；失败为可读的错误描述，可直接用于日志排查。
data	object / array / null	业务数据。成功时为对象或数组，失败时为 null。
error.code	string	仅失败时返回，机器可读的错误标识，参见错误码对照表。

公共响应参数

列表类接口在 data 中统一返回分页信息（不返回总条数）：

字段	类型	说明
list	array	当前页数据数组，无数据时为空数组 []。
page	int	当前页码。
per_page	int	当前每页条数（服务端归一化后的值）。

翻页判断：由于不返回总条数，请以「list 长度是否小于 per_page」作为最后一页的判断依据。

字符编码与时区

项目	约定
字符编码	请求与响应统一使用 UTF-8。响应头为 Content-Type: application/json; charset=utf-8。
时区	服务端统一使用 Asia/Shanghai（UTC+8）。
日期时间格式	YYYY-MM-DD HH:MM:SS，如 2026-10-21 10:12:33。
日期格式	YYYY-MM-DD，如 2026-10-28（用于 due_date）。
时间戳	Unix 秒级时间戳，仅用于鉴权请求头 X-Timestamp。

金额与数据类型

数据类型	说明
金额	数据库为 DECIMAL(12,2)，在列表与详情接口中通常以字符串返回，如 "59.00"，避免浮点精度丢失。请按十进制字符串解析，不要直接转 float 参与累计计算。
例外	order/create 返回的 total 为数值类型（如 59），用于快速展示；正式记账请以账单接口数据为准。
整数	ID、数量等整型字段以 JSON 数字返回。
空值	可为空的字段返回 null，如 parent_order_id、due_date、config_snapshot。
布尔	接口不使用布尔值，状态统一用字符串枚举表示。

这篇文章对你有帮助吗？