- warehouseNotify: 按固定群订阅经 wms_api_app 回调推送(MD5 验签),消息表登记+失败重试 - notice: 货主群缺失时降级发仓库异常群(前缀标记失败),合约停用/已解除货主不发货主群也不降级 - order_async: 订单同步通知 3 分钟去抖合并,Redis 队列+定时冲刷+失败重试 - receiving: 收货完成/驳回/审核通知走仓库通道,仓库/货主侧文案分离 - storage/inventory: 移除移库完成群通知(事件码保留,库存余量提醒仍复用) - 新增 debug:warehouse:push-receiver 调试接收服务与文档/变更记录
182 lines
6.4 KiB
JSON
182 lines
6.4 KiB
JSON
{
|
||
"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×tamp=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×tamp=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
|
||
}
|
||
}
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
} |