API 对接关系总览

更新日期：2026-07-30
用途：快速判断接口调用方、鉴权方式、状态流和回调方向

项目里有三条外部通信链路，容易混在一起。排查问题时先判断请求属于哪一条。

1. 三条链路

链路	调用方	接收方	路径 / 入口	鉴权	作用
商户侧开放 API	商户自己的商城 / 系统	本平台	`/api/client/v1`	`X-App-Key` + HMAC	查商品、创建订单、查订单、取消订单、查钱包
源头侧发货 API	上游发货平台	本平台	`/api/open/v1`	`X-Api-Key` + HMAC	按订单号查可发货信息，回传发货成功 / 失败
商户回调	本平台	商户自己的回调 URL	商户后台配置 URL	`X-Event-ID` + `X-Timestamp` + `X-Sign`	把订单创建、履约变化、取消等事件推给商户

2. 订单流

商户系统
  ↓ POST /api/client/v1/orders
本平台创建订单、扣商户钱包、生成 order_no
  ↓
上游发货平台
  ↓ GET /api/open/v1/orders/{order_no}
查询商品 sku、买家信息、can_ship
  ↓
上游完成发货
  ↓ POST /api/open/v1/orders/ship-notify
只回传 success 或 failed
  ↓
本平台更新履约状态
  ↓
商户回调 / 商户查询订单

当前流程不再维护独立的 fulfillment_jobs 任务表；履约事实以订单表里的 fulfillment_status、上游单号、发货时间和失败原因等字段为准。

3. 鉴权不要混用

项	商户侧 `/api/client/v1`	源头侧 `/api/open/v1`
Key Header	`X-App-Key`	`X-Api-Key`
Secret 来源	商户后台创建 API 客户端后展示一次	服务端环境变量 `OPEN_API_SECRET`
body 参与签名	`body_sha256`	原始 body 字符串
nonce 防重	数据库持久化	数据库持久化
多租户	按 API 客户端绑定商户	全局源头 Key，按 `order_no` 找订单

两套签名串不同，即使 Header 名相似也不能互相套用。

所有对外返回和回调里的时间字段统一使用 RFC3339 秒级北京时间，例如 2026-07-30T17:53:58+08:00；请求侧仍接受合法 RFC3339 时间。

4. 状态语言

内部订单使用 payment_status + fulfillment_status 两组状态；源头侧为了兼容对接，返回的是更贴近发货系统的旧状态名。

内部 payment_status	内部 fulfillment_status	源头侧 `status`	含义	是否可发货
`paid`	`pending`	`paid`	已付款，等待发货	是
`paid`	`processing`	`delivering`	履约中	否
`paid`	`succeeded`	`delivered`	已交付	否
`paid`	`failed`	`ship_failed`	发货失败，可重试	是
`refunded`	`cancelled`	`cancelled`	已取消 / 已退款	否

注意：源头侧返回的 status=paid 不是单独的支付状态，而是“这个订单已支付且处于待发货履约状态”的兼容表达。

5. ship_notify 当前契约

路径：POST /api/open/v1/orders/ship-notify
ship_status 只接受 success / failed
failed 时 fail_reason 必填，必须写详细原因
success 会清空订单失败原因，并清掉结果 JSON 中历史 fail_reason
已交付订单重复推 success 按幂等成功处理
已交付订单再推 failed 会被拒绝，并保留审计记录

详细请求体见：发货通知约定.md

3.5 KiB Raw Blame History