OpenAPI 接入与对接文档

面向分销合作伙伴的标准化接口说明，覆盖接入流程、鉴权、权限、限流、 错误处理与验收清单。若需更详细字段，欢迎进入在线文档或联系对接人。

返回首页
环境与地址 BASE_URL = https://{domain}/openapi VERSION = /v1 FORMAT = JSON

接入流程

1
提交资料

提供合作主体、联系人、服务器出口 IP（白名单）。

2
开通密钥

平台下发 api_key / secret_key / permissions。

3
联调验收

完成签名、限流、错误码处理与幂等策略。

4
上线切换

确认白名单、监控告警、对账流程无误后上线。

鉴权必备

所有接口必须携带 API Key；推荐使用 v2 签名以防重放。

请求头

X-API-Key: <api_key>

v2 签名头

X-Signature-Version: v2 X-Timestamp: <unix seconds> X-Nonce: <random string> X-Signature: <hmac_sha256>

时间戳误差不超过 300s，同一 nonce 300s 内只能使用一次。

权限与限流

权限基于 METHOD + PATH 映射，permissions 内含 * 可视为全权限。

权限示例
  • order.create / order.query / order.update_status / order.cancel
  • product.query / distributor.info（规划中）

限流策略

  • 默认按 API Key 限流，429 返回 Retry-After。
  • 高频接口可配置独立限额。

接口清单

方法 路径 权限 说明
POST /openapi/v1/orders order.create 创建订单
GET /openapi/v1/orders order.query 订单列表
GET /openapi/v1/orders/{order_id} order.query 订单详情
PUT /openapi/v1/orders/{order_id}/status order.update_status 更新订单状态
DELETE /openapi/v1/orders/{order_id} order.cancel 取消订单
GET /openapi/v1/products product.query 商品查询（规划中）
GET /openapi/v1/distributor distributor.info 分销商信息（规划中）

签名算法 v2

签名串由 5 段组成， METHOD 与 PATH 均为大写与原始路径。

METHOD\nPATH\nTIMESTAMP\nNONCE\nSHA256(rawBody)

Signature = HMAC-SHA256(stringToSign, secret_key)

统一响应结构

{ "code": 0, "message": "success", "data": {}, "request_id": "...", "timestamp": 0 }

code=0 成功；非 0 为错误码。

创建订单示例

POST /openapi/v1/orders { "distributor_id": 10001, "user_id": 9981, "products": [ {"sku": "SKU-001", "qty": 2, "price": 99.0} ], "total_amount": 198.0, "shipping_address": { "name": "张三", "phone": "13800000000", "address": "上海市浦东新区..." }, "remark": "备注信息", "external_order_id": "PARTNER-20240101-001" }
字段仅作示例，请以在线文档或对接说明为准。

错误码与重试

状态码 含义 处理建议
400 参数错误 校验参数与字段格式
401 认证/签名失败 检查 key、签名与时间戳
403 无权限/IP 不在白名单 核对 permissions 与出口 IP
429 限流 按 Retry-After 退避重试
500 系统异常 记录 request_id 并联系平台

联调清单

  • 使用 /health 验证网络可达
  • v2 签名通过，nonce 不可复用
  • 订单创建/查询接口可稳定返回
  • 429 限流退避策略生效
  • 请求日志可用 request_id 追踪

常见问题

Q: 如何申请更高限流？

请联系对接人说明业务峰值与预计 TPS。

Q: bodyHash 使用哪种编码？

使用请求原始 body 的 UTF-8 字节内容。

Q: 是否支持 Webhook？

支持按需开通，需提供回调地址与共享密钥。