优化发货接口对接流程

2026-07-30 23:44:50 +08:00
parent a16e518b6c
commit ee956e2e01
14 changed files with 428 additions and 141 deletions
@@ -0,0 +1,72 @@
+# 发货通知约定（速查）
+
+> 更新日期：2026-07-30  
+> 适用对象：上游发货系统、联调排查、后续快速检索
+
+本文是 `ship_notify` 的当前对接口径速查版。完整鉴权与接口说明见：[开放接口-皮肤源头对接.md](开放接口-皮肤源头对接.md)
+
+## 1. 当前口径
+
+- `ship_notify` 只推送两种状态：`success` / `failed`
+- `success` 表示发货成功
+- `failed` 表示发货失败
+- `failed` 时，`fail_reason` 必填，且要写详细失败原因
+- `processing` 是旧口径里曾出现过的中间状态，当前 `ship_notify` 不再接受
+
+## 2. 推荐推送格式
+
+### 发货成功
+
+```json
+{
+  "order_no": "O202607240733306742",
+  "ship_status": "success",
+  "provider_order_no": "6a6322a81b3b421994137260",
+  "shipped_at": "2026-07-24T08:30:33.000Z",
+  "fail_reason": "",
+  "game_uid": "4808146277",
+  "role_name": "巫师哈丁12",
+  "game_channel": "安卓-QQ",
+  "pay_score": 360
+}
+```
+
+### 发货失败
+
+```json
+{
+  "order_no": "O202607240733306742",
+  "ship_status": "failed",
+  "provider_order_no": "6a6322a81b3b421994137260",
+  "shipped_at": "2026-07-24T08:30:33.000Z",
+  "fail_reason": "角色名不存在，渠道服校验失败",
+  "game_uid": "4808146277",
+  "role_name": "巫师哈丁12",
+  "game_channel": "安卓-QQ",
+  "pay_score": 360
+}
+```
+
+## 3. 字段要求
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `order_no` | 是 | 店铺订单号 |
+| `ship_status` | 是 | 仅使用 `success` / `failed` |
+| `provider_order_no` | 否 | 上游发货单号 |
+| `shipped_at` | 否 | RFC3339 时间；`success` 未传时可由服务端补时间 |
+| `fail_reason` | 失败时是 | `failed` 时必须填详细原因 |
+| `game_channel` | 否 | 账号区服 |
+| `game_uid` | 否 | 游戏角色 UUID |
+| `role_name` | 否 | 角色名 |
+| `pay_score` | 否 | 消耗积分 |
+
+## 4. 快速排查
+
+- 只有订单查询日志，没有 `ship_notify` 日志，通常表示上游只查了单，没有回调发货结果
+- `failed` 但 `fail_reason` 为空，不符合当前约定
+- `success` 后订单应进入已交付状态，重复 `success` 一般按幂等处理
+
+## 5. 备注
+
+2026-07-30 的测试环境日志里，只看到 `/api/open/v1/orders/{order_no}` 的查询请求，没有看到 `ship_notify` 推送请求，说明当次联调只做了查询。