4.8 KiB
4.8 KiB
消息通知事件 API 文档(独立于 system)
1. 文档说明
本文档描述 WMS 对外消息通知能力 的事件 API 约定。
特点:
- 独立于
/system接口 - 不走
method=xxx的 system 调用方式 - 由内部业务在关键节点触发
event - 通过 WebHook 向外部系统推送标准 JSON 消息
当前第一批落地事件:
receiving_completed:收货完成通知
2. 触发方式
内部业务在以下位置触发:
- 文件:
app/service/systems/storage/receiving.js - 方法:
completeReceiving() - 通知方法:
sendCompletionNotice()
触发时机:
- 收货单状态更新为
completed - 收货完成 Excel 报表上传成功或已生成完成结果
- 调用:
await ctx.service.systems.notice.send({
businessName: 'receiving',
event: 'receiving_completed',
...
})
3. 事件命名规则
本能力中,事件名本身就是通知方法标识。
示例:
| event | 含义 |
|---|---|
receiving_completed |
收货单完成通知 |
当前正式注册的业务事件仅保留
receiving_completed。
对于外部订阅方来说,判断消息类型时,优先看:
eventbusinessNamemessage.type
命名约束:
- 仅允许小写字母、数字、下划线
- 首字符不能为数字
- 禁止使用
.
4. 当前已落地事件:receiving_completed
4.1 业务含义
当仓库完成一张收货单时,系统会向绑定的 WebHook 推送一条 receiving_completed 通知。
4.2 推送目标
由 wms_notification_webhook 决定:
- 先匹配仓库
warehouseId绑定的接口 - 若传了
storeId / ownerId,再匹配货主绑定的接口 events命中以下任一规则即可推送:all*receiving_completed
5. 请求方式
对外固定使用:
POST
Content-Type: application/json
6. 收货完成通知 payload
6.1 字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
traceId |
string |
通知追踪 ID |
event |
string |
固定为 receiving_completed |
businessName |
string |
固定为 receiving |
warehouseId |
number |
仓库 ID |
storeId |
number | null |
货主 ID,可为空 |
businessId |
number |
收货单 ID |
occurredAt |
string |
发生时间,ISO 格式 |
subject |
object |
当前主体(仓库) |
store |
object |
货主信息 |
sender |
object |
操作人信息 |
receivers |
array |
接收者占位 |
message |
object |
消息主体 |
metadata |
object |
业务扩展信息 |
6.2 示例(带完成报表)
{
"traceId": "notice_1775368780099_c6fb8643",
"event": "receiving_completed",
"businessName": "receiving",
"warehouseId": 100000,
"storeId": 200000,
"businessId": 12345,
"occurredAt": "2026-04-05T12:00:00.000Z",
"subject": {
"id": 100000,
"type": "warehouse",
"name": "广州仓",
"code": "",
"config": {
"max_notice_webhook_count": 5
}
},
"store": {
"id": 200000,
"name": "某货主",
"businessLicense": "9144XXXXXXXXXXXX",
"storeRemask": "华南货主"
},
"sender": {
"id": 10001,
"name": "张三"
},
"receivers": [],
"message": {
"type": "file",
"title": "收货单RCV202604050001已完成",
"content": "收货单RCV202604050001已完成,匹配商品10件,未匹配商品0件,总数量120,完成人张三。",
"url": "https://cdn.example.com/收货完成_RCV202604050001.xlsx",
"fileName": "收货完成_RCV202604050001.xlsx",
"mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
"body": "收货单RCV202604050001已完成,匹配商品10件,未匹配商品0件,总数量120,完成人张三。"
},
"metadata": {
"receivingId": 12345,
"receivingNumber": "RCV202604050001",
"warehouseId": 100000,
"storeId": 200000,
"stats": {
"total_details": 10,
"matched_details": 10,
"unmatched_details": 0,
"total_quantity": 120
},
"completionReport": {
"fileKey": "收货完成_RCV202604050001.xlsx",
"url": "https://cdn.example.com/收货完成_RCV202604050001.xlsx"
}
}
}
7. 返回值约定
针对当前旧回调接口的约定:
- 返回
1= 成功 - 返回
0= 失败
8. 当前可信结论
已验证:
GET调用旧接口地址可返回1POST {}可返回1- 手工最小 probe JSON 可返回
1
因此:
若
receiving_completed的统一通知实际推送触发远端错误,优先判断为 payload 字段结构差异导致的远端解析异常。
9. 后续事件扩展建议
下一步可继续补充:
receiving_cancelledstock_lowstock_changedentry_order_createdentry_order_completed
保持原则:
一个业务事件 = 一个对外通知 event