{ "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 做幂等去重,网络波动可能重推" ], "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 } } } ] } ] } }