优化发货接口对接流程

README.md

@@ -107,7 +107,14 @@ make docker-down    # 停止并移除
 
 ## 开放接口（皮肤源头对接）
 
-上游皮肤源头系统通过以下接口对接，需携带签名头 `X-Api-Key`、`X-Timestamp`、`X-Nonce`、`X-Sign`。
+项目有两套外部 API，请先区分调用方：
+
+- 商户侧 `/api/client/v1`：商户系统创建订单、查询订单和钱包，使用商户专属 `X-App-Key`。
+- 源头侧 `/api/open/v1`：上游发货平台查询订单并回传发货结果，使用平台配置的 `X-Api-Key`。
+
+源头侧 `ship_notify` 当前只使用 `success` / `failed`，速查见 [`docs/发货通知约定.md`](docs/发货通知约定.md)，完整关系图见 [`docs/API对接关系.md`](docs/API对接关系.md)。两套 API 的签名算法不同，不能混用鉴权头或签名串。
+
+上游皮肤源头系统调用源头侧接口时，需携带签名头 `X-Api-Key`、`X-Timestamp`、`X-Nonce`、`X-Sign`。
 
 ### 1. 查询订单（发货前置）
 
@@ -142,10 +149,10 @@ POST /api/open/v1/orders/ship-notify
 | 字段 | 必填 | 说明 |
 |------|------|------|
 | `order_no` | 是 | 系统订单号 |
-| `ship_status` | 是 | `success` / `failed` / `processing` |
+| `ship_status` | 是 | 仅 `success` / `failed` |
 | `provider_order_no` | 否 | 上游单号 |
 | `shipped_at` | 否 | 发货时间，RFC3339 格式 |
-| `fail_reason` | 否 | 失败原因 |
+| `fail_reason` | 失败时是 | `failed` 时必填，填写详细失败原因 |
 | `game_channel` | 否 | 账号区服（安卓/IOS-微信/QQ） |
 | `game_uid` | 否 | 游戏角色 UUID |
 | `role_name` | 否 | 角色名 |