${escapeHtml(docData.module || docName)} API 文档
说明: ${escapeHtml(docData.description || '无')}
版本: ${escapeHtml(docData.version || 'N/A')}
更新: ${escapeHtml(docData.updatedAt || 'N/A')}
方法数: ${methodsCount}
统一入口: ${escapeHtml(entryPath)}
${renderSeeAlsoLinks(docData.seeAlso)}
${isExternalApi ? '' : `
全局 Authorization
设置后会自动注入所有“在线调试”请求头,保存在浏览器本地。
全局业务 Header
${globalHeadersControls}
来自 JSON 的 headers 定义;带 * 的字段为必填,支持下拉 list 选择。
`}
${isExternalApi ? '' : ``}
${isOpenapi || isWarehouse ? (docData.module === 'warehouse_notify' ? `
请求方式
POST {notify_url}?app_key={app_key}&method={方法名}×tamp={时间戳}&sign={签名}
Content-Type: application/json
{
"code": 200,
"data": { ... }
}
签名算法(MD5)
sign = MD5(self_app_secret + timestamp + bodyJson).toLowerCase()
其中:
self_app_secret = 平台分配的密钥
timestamp = Unix 秒级时间戳
bodyJson = JSON.stringify(请求体)
示例(假设 self_app_secret=abc123,请求体={"code":200,"data":{...}}):
bodyJson = {"code":200,"data":{...}}
timestamp = 1700000000
signText = abc1231700000000{"code":200,"data":{...}}
sign = md5(signText).toLowerCase() = ...
注意事项(外部系统接收方)
- 通知由 WMS 主动推送到您配置的 notify_url,外部系统接收并返回 HTTP 200即可
- 根据 query 中的
method 字段路由到不同处理逻辑(notify.ping / notify.reply)
- 根据
data.type 区分消息类别(ai / bind / balance / error)
- 验签时从 query 取
sign,本地计算 MD5(self_app_secret + timestamp + bodyJson) 比对
- 时间戳 timestamp 为 Unix 秒级时间戳,校验 ±10 分钟时效
- 签名结果为 32 位小写十六进制字符串
- 接收成功返回
{"code":200},非 200 或 HTTP 状态码非 200 视为推送失败
- WMS 推送超时 10 秒,失败不重试,仅记录日志
` : `
请求方式
POST ${isOpenapi ? '/openapi' : '/warehouse'}?method={方法名}&v=1.0×tamp={时间戳}&app_key={app_key}&sign={签名}
Content-Type: application/json
{请求体 JSON}
签名算法(MD5)
参与签名字符串 = canonicalQuery + self_app_secret + bodySign
最终签名 sign = md5(参与签名字符串).toLowerCase()
其中:
canonicalQuery = 将 query 参数(排除 sign/signature)按 key 字母序升序排列,
拼接为 key1=value1&key2=value2 格式。
参数值序列化规则:undefined/null → 空字符串,
对象类型 → stableStringify 序列化,其他 → String(value)。
bodySign = md5(stableStringify(请求体))
stableStringify = 递归排序对象 key 的稳定序列化:
- 对普通对象,按 key 字母序递归序列化每个字段
- 对数组,按顺序递归序列化每个元素
- 对非普通对象(Date 等),使用 JSON.stringify
- undefined 返回空字符串,null 返回 "null"
self_app_secret = 平台分配的密钥
示例(假设 self_app_secret=abc123,请求体={"id":1}):
query: app_key=myapp&method=index.ping×tamp=1700000000&v=1.0
canonicalQuery = app_key=myapp&method=index.ping×tamp=1700000000&v=1.0
stableStringify({"id":1}) = {"id":1}
bodySign = md5({"id":1}) = 0a5b3e...
signText = app_key=myapp&method=index.ping×tamp=1700000000&v=1.0abc1230a5b3e...
sign = md5(signText) = ...
注意事项
- method 格式为
模块.方法,如 index.ping
- app_key / self_app_secret 由仓库申请配置,请联系仓库管理员获取
- 请求体必须为合法 JSON,空 body 传
{}
- 时间戳 timestamp 为 Unix 秒级时间戳(数字类型)
- 时间戳 timestamp 时效校验:与服务器时间差不得超过 ±10 分钟(600 秒),超时返回 400
- 签名结果为 32 位小写十六进制字符串
${isOpenapi ? `
→ 回调测试工具
(模拟接收回调通知,验证回调链路)
→ 出站回调文档
(WMS → 外部的回调事件定义,共 5 个)
` : ''}
`) : ''}