76 lines
3.5 KiB
Markdown
76 lines
3.5 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` 任务表；履约事实以订单表里的 `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](发货通知约定.md)
|