# 发货通知约定（速查）

> 更新日期：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-24T16:30:33+08:00",
  "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-24T16:30:33+08:00",
  "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` 推送请求，说明当次联调只做了查询。