affiliate_dash/docs/发货通知约定.md

发货通知约定（速查）

更新日期：2026-07-30
适用对象：上游发货系统、联调排查、后续快速检索

本文是 ship_notify 的当前对接口径速查版。完整鉴权与接口说明见：开放接口-皮肤源头对接.md

1. 当前口径

• ship_notify 只推送两种状态：success / failed
• success 表示发货成功
• failed 表示发货失败
• failed 时，fail_reason 必填，且要写详细失败原因
• ship_notify 不接受中间态，提交发货时由平台内部将订单置为 delivering

2. 推荐推送格式

发货成功

{
  "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
}

发货失败

{
  "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 推送请求，说明当次联调只做了查询。