# 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 | 含义 | 是否可发货 |
|--------------|------|------------|
| `pending` | 待支付（当前无真实支付流程，仅预留） | 否 |
| `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)