WMS_MAIN/methods/warehouse_notify.json
liufumingren 7ad08e488d feat(notice): 统一通知仓库接口通道与订单同步通知去抖
- warehouseNotify: 按固定群订阅经 wms_api_app 回调推送(MD5 验签),消息表登记+失败重试
- notice: 货主群缺失时降级发仓库异常群(前缀标记失败),合约停用/已解除货主不发货主群也不降级
- order_async: 订单同步通知 3 分钟去抖合并,Redis 队列+定时冲刷+失败重试
- receiving: 收货完成/驳回/审核通知走仓库通道,仓库/货主侧文案分离
- storage/inventory: 移除移库完成群通知(事件码保留,库存余量提醒仍复用)
- 新增 debug:warehouse:push-receiver 调试接收服务与文档/变更记录
2026-08-17 02:03:34 +08:00

182 lines
6.4 KiB
JSON
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

{
"module": "warehouse_notify",
"description": "仓库开放通知 API 定义(出站方向:WMS → 外部系统)。WMS 处理消息后,通过 HTTP POST 主动推送到外部系统配置的 notify_url,使用 MD5 签名鉴权。method 通过 query 参数传递,body 为 { code, data }。外部系统返回 {\"code\":200} 或 HTTP 非 200 视为推送失败。",
"version": "1.0.0",
"updatedAt": "2026-08-07",
"http": {
"path": "{wms_api_app.callback_url}",
"method": "POST"
},
"auth": {
"type": "MD5",
"description": "签名算法:sign = MD5(app_secret + timestamp + body_json)。外部系统用预先分配的 AppSecret 验证。method / app_key / timestamp / sign 通过 query 参数传递。",
"params": [
{
"name": "app_key",
"type": "string",
"required": true,
"source": "query",
"description": "WMS 的 AppKey"
},
{
"name": "method",
"type": "string",
"required": true,
"source": "query",
"description": "notify.ping / notify.reply"
},
{
"name": "timestamp",
"type": "number",
"required": true,
"source": "query",
"description": "Unix 时间戳(秒),±10分钟有效"
},
{
"name": "sign",
"type": "string",
"required": true,
"source": "query",
"description": "MD5(appSecret + timestamp + bodyJson)"
}
]
},
"headers": [
{
"name": "Content-Type",
"type": "string",
"required": true,
"description": "application/json"
}
],
"methods": {
"groups": [
{
"groupName": "心跳",
"module": "ping",
"list": [
{
"method": "notify.ping",
"description": "连通性测试。WMS 配置 notify_url 后可发送 ping 通知验证外部系统可达。",
"isNeedAuth": true,
"isNeedLogin": false,
"example": {
"query": "?app_key=AK20260807001&timestamp=1786100000&sign=abc123",
"method": "notify.ping",
"code": 200,
"data": {
"content": "ping",
"timestamp": 1786100000
}
}
}
]
},
{
"groupName": "消息回复",
"module": "reply",
"list": [
{
"method": "notify.reply",
"description": "消息回复通知。WMS 处理入站消息后,将 AI 回复/绑群结果/面单余额等内容推送到外部系统。外部系统根据 data.type 区分消息类别。",
"isNeedAuth": true,
"isNeedLogin": false,
"params": [
{
"name": "data.type",
"type": "string",
"required": true,
"source": "body",
"description": "ai=AI回复 / bind=绑群结果 / balance=面单余额 / error=异常兜底"
},
{
"name": "data.content",
"type": "string",
"required": true,
"source": "body",
"description": "回复正文(纯文本)"
},
{
"name": "data.ext_id",
"type": "string",
"required": true,
"source": "body",
"description": "通知唯一 ID(wms_inbox_message.id 主键),用于幂等判断。网络波动时可能重推,接收方应据此去重"
},
{
"name": "data.ext_data",
"type": "object",
"required": false,
"source": "body",
"description": "入站透传数据,原路带回"
},
{
"name": "data.group_id",
"type": "string",
"required": true,
"source": "body",
"description": "群ID"
},
{
"name": "data.user_id",
"type": "string",
"required": true,
"source": "body",
"description": "用户ID"
},
{
"name": "data.group_name",
"type": "string",
"required": true,
"source": "body",
"description": "群名称"
},
{
"name": "data.user_name",
"type": "string",
"required": true,
"source": "body",
"description": "用户名称"
},
{
"name": "data.timestamp",
"type": "number",
"required": true,
"source": "body",
"description": "Unix 秒"
}
],
"notes": [
"对应入站:/warehouse inbox.push",
"type=ai:用户消息触发 AI 推理回复",
"type=bind:用户发送「授权:CODE」绑群",
"type=balance:绑群成功后自动推送面单余额",
"type=error:AI 无法处理时的兜底回复",
"AI silent(无需回复)时不推送",
"ext_id 为 wms_inbox_message.id 主键,接收方应以 ext_id 做幂等去重,网络波动可能重推",
"type=system:系统级业务事件通知(收货完成/驳回/审核等,不要求 user_id/user_name),data 仅携带 content(通知正文,接收方只处理该字段)与 ext_id(业务单号,用于幂等去重),其余协议字段为 group_id / group_name / timestamp"
],
"example": {
"query": "?app_key=AK001&timestamp=1786100000&sign=abc",
"method": "notify.reply",
"code": 200,
"data": {
"type": "ai",
"content": "条码6900000000016查到2款商品:\n1. 披肩-消退 可用0\n2. 披肩 可用0(总量95已锁定)",
"ext_id": "188",
"ext_data": {
"request_id": "req-123"
},
"group_id": "wrchat-xxx",
"user_id": "user-001",
"group_name": "售后沟通群",
"user_name": "张三",
"timestamp": 1786100000
}
}
}
]
}
]
}
}