- 背景:order_storage_allocation 构造的 routeContext 不含 appKey, finalizeLocalChannelOrdersInternal 的 if(appKey) 门禁导致 API 同步链路的 deliveryorder.confirm 从未真正发出;订单表 from_key 也兜不住 (normalizeOrderFromKey 仅接受整数,字符串 app_key 被归一化为 null) - order_async.js 新增 resolveOpenApiAppByStoreInternal:口径与入库单 _sendOpenApiCallback 对齐(wms_store_warehouse auth_status=2 → wms_api_app is_enabled=1 且 callback_url 非空) - notifyApiDeliveryOrderConfirmsInternal 逐单解析 appKey:context.appKey 非空优先 (不触发反查),缺失时按 orderRow.store_id 反查并按货主缓存(同批次无 N+1); 解析不到 appKey 的订单 warn 后跳过、不发请求 - 补充回调成功 info 日志(含 appKey) - 文档:methods/openapi_callback.json 1.2.0 → 1.3.0、变更记录 methods/changes/openapi_callback.json、docs/openapi-callback-events.md、 AI_METHOD_ROUTING.md 同步 - test: order_async.openapi.callback.test.js 覆盖 context.appKey 为空时反查发送
21 KiB
OpenAPI 出站回调事件说明
状态:2026-09-13 破坏性协议变更已落代码(报文体
{ event, data, metadata }→{ request };deliveryorder.confirm改为逐单发送)。 本文档描述 WMS 主动向外部系统推送的 OpenAPI 出站回调(出站 HTTP 回调)协议。 与methods/openapi.json描述的入站 OpenAPI method(POST /openapi)方向相反;本文档不属于methods/*.json的 SSOT 范围。
1. 破坏性变更说明
1.1 2026-09-13:报文体改为奇门同层级 { request }
- 报文体由
{ event, data, metadata }改为奇门同层级的{ request: {...} };发送端不再发送数据/元数据,event仅出现在 query 的method。 - 5 个事件的
request结构与奇门对应接口的request节点同层级(字段口径见第 3 节,与注册表request模板一致)。 deliveryorder.confirm通知对象口径变化:改动前一次回调携带整批orderIds(含失败/跳过);改后仅对syncResults中status==='success'的订单逐单发送(成功 N 单 = N 次回调),详见 3.3。- 旧报文结构(
{ event, data, metadata })已全部废弃:无新旧兼容、无双发,接收方必须同步改造。
1.2 2026-09-12:事件名改为 模块.动作(历史,仍有效)
- 出站回调的
method(query 参数)原先使用 snake_case 事件名(如stockout_completed),现统一改为模块.动作(如stockout.confirm),与奇门 method 去掉taobao.qimen.前缀后对齐。 - 旧事件名已全部废弃:无新旧兼容、无双发。接收方必须同步改造;仅当接收方按
模块.动作校验 method 时,新协议可正常通过(此前会报 400「参数缺失或错误: method(需为 模块.动作,如 index.ping)」)。 - 回调事件
order.cancel更名为deliveryorder.cancel:与/openapi入站方法order.cancel(取消单据接口,见methods/openapi.json)同名,若接收方将callback_url误指向 WMS/openapi会被路由到真正的取消单据接口;不做兼容、不双发,旧名order.cancel(出站方向)已废弃。
| 旧(事件名,已废弃) | 新(method) | 触发场景 | 实现位置 |
|---|---|---|---|
entry_order_direct_inbound_completed |
entryorder.confirm |
直入入库(API 来源)完成 | app/service/systems/inbound_direct_log.js |
entry_order_receiving_matched |
entryorder.match |
入库单匹配收货单完成 | app/service/systems/receiving_entry_match.js |
order_completed |
deliveryorder.confirm |
订单同步(出库)完成(逐单发送) | app/service/systems/order_async.js |
stockout_completed |
stockout.confirm |
出库单确认完成 | app/service/systems/order_async.js |
order_cancelled |
deliveryorder.cancel |
订单取消成功(旧 method 名 order.cancel 已废弃) |
app/service/openapiMethods/order.js |
事件注册表:app/service/openapi/callbackRegistry.js#CALLBACK_EVENTS(5 条,每条含 name / label / description / request,request 为奇门同层级报文模板),回调调试页 GET /docs/api/openapi/callback-test(app/controller/openapiCallback.js)直接消费该注册表,并按注册表自动预填完整报文体 { request: {...} }(可编辑)。
2. 协议说明
2.1 出站请求与 query 参数
POST {callbackUrl}?method={模块.动作}&v=1.0×tamp={timestamp}&app_key={selfAppKey}&sign={sign}
callbackUrl 来自 api_app 表(callback_url 字段,要求 is_enabled=1 且 callback_url 非空)。
| query 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
method |
string | 是 | 回调 method,模块.动作 格式(与奇门对应接口对应;报文体不再携带 event 字段);URL 中做 encodeURIComponent |
v |
string | 是 | 协议版本,固定 1.0 |
timestamp |
string | 是 | 时间戳,秒级(10 位字符串),见第 4 节 |
app_key |
string | 是 | 应用标识(api_app.self_app_key);URL 中做 encodeURIComponent |
sign |
string | 是 | 签名,算法见 2.4 |
2.2 请求头
Content-Type: application/json
2.3 请求体结构
{
"request": { "…": "…" }
}
request为奇门同层级业务报文,结构按事件不同,口径见第 3 节(与注册表request模板一致)。event不出现在报文体内,仅拼入 query 的method。- 构造位置:
app/service/openapi/callback.js#sendWithRetry(body = { request: request || {} });sendByAppKey将request原样透传给sendWithRetry。
2.4 签名算法
实现:app/lib/api_sign.js#signRequest(与 OpenAPI 入口验签算法一致)。
canonicalQuery:query 中除sign/signature(大小写不敏感)外、值非undefined的参数,按 key 字母序升序,拼为key=value&key2=value2。值为原始字符串(不 URL 编码);对象值经stableStringify。bodySign = md5(stableStringify(body));stableStringify对对象键做字母序排序后 JSON 序列化;body即完整报文{ request: {...} }。sign = md5(canonicalQuery + selfAppSecret + bodySign),小写十六进制。
注意:
- 参与签名的是未 URL 编码的原值;实际 URL 中仅
method、app_key做了encodeURIComponent。 selfAppSecret为api_app.self_app_secret(signRequest内部会trim)。
canonicalQuery 示例(method=entryorder.confirm):
app_key=APP2024011514301234&method=entryorder.confirm×tamp=1758047400&v=1.0
2.5 重试策略
实现:app/service/openapi/callback.js#sendWithRetry。
- 最多重试
MAX_RETRY=3次(即最多共 4 次尝试)。 - 间隔:
[2000, 5000, 15000]毫秒(2s → 5s → 15s)。 - 触发条件:非 2xx 响应或网络错误(异常 catch)。
- 单次请求超时:30s(
ctx.curltimeout: 30000)。 - 每次尝试经
logCallback记录日志:[OpenapiCallback] event=… appKey=… url=… retry=N success=… response=…(成功 info、中途失败 warn、最终失败 error)。
2.6 发送途径与配置解析
| 途径 | 配置解析 | 使用的事件 |
|---|---|---|
sendByAppKey |
按 app_key 查 ApiApp(self_app_key=appKey, is_enabled=1),取 self_app_secret 与 callback_url |
deliveryorder.confirm、stockout.confirm、deliveryorder.cancel |
sendWithRetry 直调 |
按 StoreWarehouse(store_id/warehouse_id, auth_status=2)→ ApiApp(contract_id=storeWarehouse.id, is_enabled=1, callback_url 非空)定位 |
entryorder.confirm、entryorder.match |
调试/测试工具:
- 调试页:
GET /docs/api/openapi/callback-test(app/controller/openapiCallback.js,路由见app/router.js),按注册表渲染事件下拉,选中事件后自动预填与真实回调一致的完整报文体{ request: {...} }(可编辑),前端算签名后 POST。 - 模拟发送(入站):
openapiMethods/callback.js#test(method=callback.test,body 为{ event, request },event缺省deliveryorder.confirm,按app_key走真实发送链路)。
3. 事件逐个说明
说明:以下触发实现中的行号为 2026-09-12 代码快照值,行号可能漂移;定位请以方法名 grep 为准。
3.1 entryorder.confirm
- label:入库单确认完成(直入)
- description:直入入库(API 来源)完成后回传,对应奇门
taobao.qimen.entryorder.confirm - 触发实现:
app/service/systems/inbound_direct_log.js#qimenEntrySync的 API 分支(source_type=API)→_sendOpenApiCallback(event: 'entryorder.confirm');回传成功才执行本地回调,throwOnError=true - 发送途径:
sendWithRetry直调(见 2.6) request结构(注册表request模板口径;以 QM 分支为唯一基准,QM/API 共用buildEntryOrderConfirmRequest组装):
{
"entryOrder": {
"entryOrderCode": "RK20260912001",
"ownerCode": "OWNER-001",
"warehouseCode": "WH-100",
"entryOrderId": 543,
"entryOrderType": "SCRK",
"outBizCode": "DIRECT_INBOUND_1726131400000",
"confirmType": 0,
"status": "FULFILLED",
"freight": 0,
"operateTime": "2026-09-12 10:30:00",
"remark": "导入/PDA直接入库提交"
},
"orderLines": [
{
"orderLineNo": 1,
"ownerCode": "OWNER-001",
"itemCode": "SKU-1",
"itemId": "1001",
"inventoryType": "ZP",
"planQty": 2,
"actualQty": 2
}
]
}
entryOrder字段口径:outBizCode缺省自动生成DIRECT_INBOUND_时间戳;confirmType0=最终确认 / 1=部分确认;statusFULFILLED/PARTFULFILLED;freight固定 0;operateTime为app.formatDate(new Date());remark为业务备注。
3.2 entryorder.match
- label:入库单匹配收货完成
- description:入库单匹配收货单完成后回传(API 来源),对应奇门
taobao.qimen.entryorder.confirm - 触发实现:
app/service/systems/receiving_entry_match.js#matchAfterEntryCompleted:匹配成功写入绑定关系且本次确实新建绑定(bindResult.created === true)时,调用_sendCallback(entryOrder, matchedReceiving, 'auto_match');_sendCallback按source_type分流(QM→奇门,API→OpenAPI →_sendOpenApiCallback,event: 'entryorder.match')。重复触发时绑定已存在(created === false),不会重复回传;回传失败仅记录 warn,不影响绑定与入库单状态更新。 - 发送途径:
sendWithRetry直调(见 2.6) matchType:仅保留在日志中(自动/手动匹配类型标识),不塞入回传报文outBizCode/remark口径:outBizCode缺省自动生成RECEIVING_MATCH_时间戳;remark固定「匹配收货单{收货单号}自动回传」(如匹配收货单RCV20260912001自动回传);confirmType固定 0、status固定FULFILLEDrequest结构(注册表request模板口径;QM/API 共用buildEntryOrderConfirmRequest组装):
{
"entryOrder": {
"entryOrderCode": "RK20260912002",
"ownerCode": "OWNER-001",
"warehouseCode": "WH-100",
"entryOrderId": 543,
"entryOrderType": "SCRK",
"outBizCode": "RECEIVING_MATCH_1726131400000",
"confirmType": 0,
"status": "FULFILLED",
"freight": 0,
"operateTime": "2026-09-12 10:30:00",
"remark": "匹配收货单RCV20260912001自动回传"
},
"orderLines": [
{
"orderLineNo": 1,
"ownerCode": "OWNER-001",
"itemCode": "SKU-1",
"itemId": "1001",
"inventoryType": "ZP",
"planQty": 2,
"actualQty": 2
}
]
}
3.3 deliveryorder.confirm
- label:订单发货完成
- description:订单同步(出库)完成后触发,对应奇门
taobao.qimen.deliveryorder.confirm - 触发实现:
app/service/systems/order_async.js#finalizeLocalChannelOrdersInternal(syncApiOrders处理链,触发条件不变:createChannel=API且successCount>0)→notifyApiDeliveryOrderConfirmsInternal(fire-and-forget,失败仅 warn) - 发送途径:
sendByAppKey;发送用 appKey 解析优先级:调用上下文context.appKey非空时优先(不触发合约反查),缺失时按订单货主(store_id+warehouse_id)合约反查 ——wms_store_warehouse(auth_status=2)→wms_api_app(is_enabled=1 且 callback_url 非空)的self_app_key(resolveOpenApiAppByStoreInternal,口径与入库单回调inbound_direct_log.js#_sendOpenApiCallback对齐);同一批次按货主Map缓存(N 个成功单 / M 个货主 → 2M 次查询,无 N+1) - 逐单发送语义(2026-09-13 变化):
| 维度 | 改动前 | 改动后 |
|---|---|---|
| 通知对象 | 一次回调携带整批 orderIds(含失败/跳过) |
仅对 syncResults 中 status==='success' 的订单逐单发送 |
| 回调次数 | 每批次 1 次 | 成功 N 单 = N 次回调 |
| 报文内容 | 批次汇总 { orderIds, status, successCount, failedCount } |
每单独立奇门同层级 request 报文(buildQimenDeliveryOrderConfirmDataInternal 组装) |
| 失败处理 | 不阻塞主流程 | 单订单组装/发送失败仅 warn,不影响其他订单与主流程 |
- 查询开销:复用原有主表+明细查询,新增 1 次运单号批量查询(
buildOrderWaybillCodeMapInternal,强制同仓校验,无 N+1) - appKey 门禁修复(2026-09-13):此前
order_storage_allocation.js构造的routeContext不含appKey,而finalizeLocalChannelOrdersInternal内有if (appKey)门禁,导致syncOrderIds(API)链路的deliveryorder.confirm从未真正发出过请求;订单wms_order_delivery.from_key也兜不住(normalizeOrderFromKey只接受整数,字符串 app_key 被归一化为 null)。本次改为按货主合约反查 appKey 修复。解析不到 appKey(订单缺store_id/ 无授权关系 / 无「启用且 callback_url 非空」的 ApiApp)的订单 warn 后跳过、不发请求;同步失败的订单不发送 request结构(注册表request模板口径):
{
"deliveryOrder": {
"totalOrderLines": 1,
"deliveryOrderCode": "DO20260912001",
"deliveryOrderId": 123,
"warehouseCode": "WH-100",
"orderType": "JYCK",
"status": "DELIVERED",
"outBizCode": "DO20260912001",
"confirmType": 0,
"orderConfirmTime": "2026-09-12 10:30:00",
"operatorCode": "",
"operatorName": "",
"storageFee": "0",
"operateTime": "2026-09-12 10:30:00"
},
"packages": {
"package": [
{
"logisticsCode": "YTO",
"logisticsName": "圆通速递",
"expressCode": "YT1234567890",
"packageCode": "DO20260912001",
"invoiceNo": "INV20260912001",
"items": [
{
"itemCode": "SKU-1",
"itemId": 1001,
"quantity": 2
}
]
}
]
},
"orderLines": [
{
"orderLineNo": "1",
"orderSourceCode": "SO20260912001",
"subSourceCode": "",
"ownerCode": "OWNER-001",
"itemCode": "SKU-1",
"itemId": 1001,
"itemName": "测试商品1",
"extCode": "",
"planQty": 2,
"actualQty": 2,
"retailPrice": 0,
"actualPrice": 0,
"discountAmount": "0",
"inventoryType": "ZP",
"snList": [],
"qrCode": ""
}
]
}
3.4 stockout.confirm
- label:出库单确认完成
- description:出库单确认回传(API 来源),对应奇门
taobao.qimen.stockout.confirm - 触发实现:
app/service/systems/order_async.js#notifyStockoutExternalInternal的 API 分支(source_type=API,event: 'stockout.confirm');request即buildStockoutConfirmDataInternal的返回结构{ deliveryOrder, packages, orderLines }(不再有原先data.stockoutOrderCode/status薄包装,报文与奇门请求体同层级) - 发送途径:
sendByAppKey(按app_key解析) request结构(注册表request模板口径):
{
"deliveryOrder": {
"totalOrderLines": 1,
"deliveryOrderCode": "SO20260912001",
"deliveryOrderId": 5001,
"warehouseCode": "WH-100",
"orderType": "PTCK",
"status": "DELIVERED",
"outBizCode": "SO20260912001",
"confirmType": 0,
"orderConfirmTime": "2026-09-12 10:30:00",
"operatorCode": "",
"operatorName": ""
},
"packages": {
"package": [
{
"logisticsCode": "YTO",
"logisticsName": "圆通速递",
"expressCode": "YT1234567890",
"packageCode": "SO20260912001",
"items": [
{
"itemCode": "SKU-1",
"itemId": 1001,
"quantity": 2
}
]
}
]
},
"orderLines": [
{
"orderLineNo": "1",
"ownerCode": "OWNER-001",
"itemCode": "SKU-1",
"itemId": 1001,
"itemName": "测试商品1",
"planQty": 2,
"actualQty": 2,
"inventoryType": "ZP"
}
]
}
3.5 deliveryorder.cancel
- label:订单已取消
- description:订单取消成功后触发(出站事件名
deliveryorder.cancel) - 触发实现:
app/service/openapiMethods/order.js#cancel取消成功后 fire-and-forget(event: 'deliveryorder.cancel') - 改名原因:出站回调事件名与
/openapi入站方法order.cancel(取消单据接口,见methods/openapi.json)同名,若接收方将callback_url误指向 WMS/openapi会被路由到真正的取消单据接口;故改为deliveryorder.cancel,不做兼容、不双发 - 自定义约定(2026-09-13):无奇门对应接口,按
deliveryOrder节点约定自定义;status为自定义约定值CANCELED(风格与奇门deliveryOrder.status家族枚举一致);orderType为body.orderType大写归一化结果(String(body.orderType || 'JYCK').trim().toUpperCase()) - 发送途径:
sendByAppKey(按app_key解析) request结构(注册表request模板口径):
{
"deliveryOrder": {
"deliveryOrderCode": "TEST-ORDER-001",
"orderType": "JYCK",
"status": "CANCELED"
}
}
4. timestamp 规范(2026-09-12 已统一为秒)
timestamp 已统一为**秒级(10 位字符串)**规范值:String(Math.floor(Date.now() / 1000))。
| 位置 | 取值 | 单位 |
|---|---|---|
出站发送 app/service/openapi/callback.js#sendWithRetry |
String(Math.floor(Date.now() / 1000)) |
秒(10 位) |
回调调试页 app/controller/openapiCallback.js(nowTimestamp) |
Math.floor(Date.now() / 1000) |
秒(10 位) |
- 与
/openapi入站入口app/service/openapiEntry.js的时间戳时效校验一致(秒级窗口,±600 秒),可作为规范值对外承诺。 - 历史背景:此前发送端用
String(Date.now())(毫秒)与调试页(秒)口径不一致(methods/changes/openapi_callback.json版本2026.09.12-openapi-callback-init的「已知问题」备注),已在本批次修复;接收方请按秒级(10 位)实现校验,勿再按毫秒。
5. 相关文件索引
- 事件注册表:
app/service/openapi/callbackRegistry.js - 发送与重试:
app/service/openapi/callback.js - 签名算法:
app/lib/api_sign.js - 调试页控制器:
app/controller/openapiCallback.js(路由app/router.js) - 入站方法路由文档:
AI_METHOD_ROUTING.md5.6 节 - 触发实现:
app/service/systems/inbound_direct_log.js、app/service/systems/receiving_entry_match.js、app/service/systems/order_async.js、app/service/openapiMethods/order.js - 接口文档 SSOT:
methods/openapi_callback.json(5 个 method) - 变更记录:
methods/changes/openapi_callback.json - 文档站页面:
/docs/api/openapi_callback(OpenAPI 出站回调文档页) - 入口来源:
/docs/api/openapi页面头部的「→ 出站回调文档」链接
调试工具 GET /docs/api/openapi/callback-test 已在第 1 节与 2.6 节说明,此处不重复。
三份资料的定位与先后关系:
| 资料 | 定位 |
|---|---|
methods/openapi_callback.json |
出站回调接口文档 SSOT(5 个 method 的 params / response / errors),文档站 /docs/api/openapi_callback 页面消费 |
app/service/openapi/callbackRegistry.js#CALLBACK_EVENTS |
事件注册表(name / label / description / request,request 为奇门同层级报文模板),运行时数据源;回调调试页 /docs/api/openapi/callback-test 消费注册表并预填完整报文体 { request: {...} } |
docs/openapi-callback-events.md(本文) |
协议说明与背景(触发链路、签名算法、重试策略、时间戳规范),非 SSOT,仅作解释性补充 |
先后关系:事件或字段变化时,先改代码(callbackRegistry.js 注册表与发送实现)→ 再经 script/update-api-doc.cjs 更新接口文档 SSOT methods/openapi_callback.json 并追加 methods/changes/openapi_callback.json → 最后同步本文与文档站文案。调试页内容以注册表为准,文档站页面以 SSOT 为准。
6. 与 methods/*.json 的关系
- 出站回调不写入
methods/openapi.json:该文件是入站 method 的 SSOT(POST /openapi),script/update-api-doc.cjs的 spec 结构(modules→list→method→params/response/errors)不适合表达出站回调,写入会污染文档与文档 UI 语义。 - 出站回调现已独立成接口文档
methods/openapi_callback.json(module=openapi_callback,5 个 method,当前版本 1.2.0);变更记录写入methods/changes/openapi_callback.json(首条 version2026.09.12-openapi-callback-init,typeadded;本次 version2026.09.13-openapi-callback-request-protocol,typeupdated)。 - 本次无入站接口契约变更:
methods/openapi.json、methods/system.json、methods/qimen.json均未改动。 methods/changes/*.json中历史记录提及的旧事件名(stockout_completed、entry_order_direct_inbound_completed、entry_order_receiving_matched等)为追加式历史,保持原样,不回改。