yml2213
eac025c92f
- 发货提交记录阶段推进与失败分类，失败不再清空 result_data - 超时巡检区分已提交上游与提交中断两类卡单，避免误判 - 已提交上游的失败订单禁止自动重发，防止重复发货 - ship_attempts 仅在 claim 时计数，失败阶段只记录分类信息 - CanFulfill 对已提交上游的失败单返回不可发货 - 删除预留的 pending 订单状态，统一订单状态模型 - 契约改名：order.fulfillment.updated -> order.shipping.updated，fulfillment:read -> shipping:read - 文档修正 scope 为或关系
74 lines
3.1 KiB
Markdown
74 lines
3.1 KiB
Markdown
# 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. 订单流
|
|
|
|
```text
|
|
商户系统
|
|
↓ 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` 任务表；订单事实以订单表里的 `order_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. 状态语言
|
|
|
|
平台内部、商户侧开放 API、源头侧查询和商户回调统一使用 `order_status`。
|
|
|
|
| order_status | 含义 | 是否可发货 |
|
|
|--------------|------|------------|
|
|
| `paid` | 已支付/已扣款，待发货 | 是 |
|
|
| `delivering` | 发货中 | 否 |
|
|
| `delivered` | 已交付 | 否 |
|
|
| `ship_failed` | 发货失败，可重试 | 是 |
|
|
| `cancelled` | 已取消 / 已退款 | 否 |
|
|
|
|
## 5. ship_notify 当前契约
|
|
|
|
- 路径：`POST /api/open/v1/orders/ship-notify`
|
|
- `ship_status` 只接受 `success` / `failed`
|
|
- `failed` 时 `fail_reason` 必填，必须写详细原因
|
|
- `success` 会清空订单失败原因，并清掉结果 JSON 中历史 `fail_reason`
|
|
- 已交付订单重复推 `success` 按幂等成功处理
|
|
- 已交付订单再推 `failed` 会被拒绝，并保留审计记录
|
|
|
|
详细请求体见：[发货通知约定.md](发货通知约定.md)
|