73 lines
2.3 KiB
Markdown
73 lines
2.3 KiB
Markdown
# 发货通知约定（速查）
|
|
|
|
> 更新日期：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` 推送请求，说明当次联调只做了查询。
|