接口总约定

基本约定

项目	约定
Base URL	/api/v1
鉴权方式	Authorization: Bearer <token>
幂等头	需要幂等的接口传 X-Idempotency-Key
链路追踪	客户端生成 X-Request-Id，服务端原样回传
通用响应	code、message、data、requestId、serverTime

通用响应结构

所有接口统一返回以下字段：

• code：响应码
• message：响应信息
• data：业务数据
• requestId：请求唯一标识，用于链路追踪
• serverTime：服务端时间

响应示例

{ "code": "0", "message": "ok", "data": {}, "requestId": "req_123", "serverTime": "2026-04-10T10:00:00+08:00" }

通用错误码

错误码	含义
A0001	未登录或 token 失效
A0002	无权限访问
A0003	参数校验失败
A0004	请求过于频繁
B1001	商品不存在或已下架
B1002	库存不足
B1003	积分不足
B1004	订单状态不允许当前操作
B1005	打卡标签无效
B1006	徽章不可解锁
B1007	核销码无效
B1008	支付结果确认中
B1009	当前设备不支持 NFC
B1010	当前订单不支持该客服处理入口
B1011	客服二维码暂不可用

说明

• 所有接口均基于统一的 Base URL：/api/v1
• 需要登录态的接口使用 Bearer Token 鉴权
• 涉及重复提交风险的接口应传递 X-Idempotency-Key 以保证幂等性
• 客户端需生成 X-Request-Id，服务端应在响应中原样回传，便于问题排查与链路追踪