- 新增 wms_order_express_trace(1 运单 : N 轨迹):express_id 关联主表,
冗余 waybill_code / order_id,warehouse_id 隔离,raw_data 存原始报文;
uk_express_op_scan(express_id, op_time, scan_type) 幂等;字符集与主表一致
- 新增出站回调 waybill.getTrace(注册到 callback_functions,管理端可勾选):
入参与 waybill.getreceive 一致({ request: { waybill_codes: [...] } },单批 10 单,
signMode=simple);响应 [{ waybillNo, trace: {...} }],兼容 trace 数组与 {code,data} 包装
- 新增 waybill.warehouse.updateTrace / updateTraceTaskProgress:
复用导出任务的异步任务ID与进度模式(前缀 waybill_trace_),
支持 waybillCodes 或与 waybill.warehouse.list 一致的 where 条件圈选(上限 5000);
轨迹按 (express_id, op_time, scan_type) upsert,未匹配运单计入 not_found
- 文档:methods/system.json(0.3.325)、变更记录、设计文档 2.2.1/3.9、出站回调说明 3.7
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
27 KiB
OpenAPI 出站回调事件说明
状态:2026-09-13 破坏性协议变更已落代码(报文体
{ event, data, metadata }→{ request };deliveryorder.confirm改为逐单「先回调、成功再扣减库存并置已同步」,失败置error+ 待处理异常)。 本文档描述 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(含失败/跳过);改后 API 渠道逐单在同步时发送(同一个分发循环,成功 N 单 = N 次回调),且回调成功才扣减库存并置sync_status='fin';回调失败/异常、报文组装或 appKey 解析失败 → 该单同步失败(sync_status='error'+ 待处理异常,不扣减库存,可重新派发),详见 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 |
API 渠道订单同步时逐单发送(回调成功才扣减库存并置已同步) | 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)。 deliveryorder.confirm单订单发送 4 次尝试后仍失败 ⇒ 该订单同步判定失败:sync_status='error'+ 待处理异常,不扣减库存、不置fin,订单可重新派发。
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:API 渠道订单同步(出库)时逐单触发,对应奇门
taobao.qimen.deliveryorder.confirm - 触发实现:
app/service/systems/order_async.js#finalizeLocalChannelOrdersInternal(syncApiOrders处理链,createChannel=API;触发条件已变:不再等本批出现同步成功订单,而是逐单在同一个分发循环内直接处理,DISPATCH_BATCH_SIZE=20批内并行)→processApiOrderInternal(① 组装报文,缺 ownerCode → 失败「发货单缺少奇门货主编码」→ ② 解析发送用 appKey → ③sendByAppKey发送deliveryorder.confirm(最多 4 次尝试)→ ④ 回调成功才调用processLocalChannelOrderInternal扣减库存并置sync_status='fin';任何失败统一走markApiSyncFailedInternal:sync_status='error'+ 待处理异常,不扣减、可重新派发) - 发送途径:
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(含失败/跳过) |
API 渠道逐单在同步时发送(同一个 finalizeLocalChannelOrdersInternal 分发循环,DISPATCH_BATCH_SIZE=20 批内并行) |
| 回调次数 | 每批次 1 次 | 成功 N 单 = N 次回调(每单先回调、成功再扣减) |
| 报文内容 | 批次汇总 { orderIds, status, successCount, failedCount } |
每单独立奇门同层级 request 报文(buildQimenDeliveryOrderConfirmDataInternal 组装) |
| 失败处理 | 不阻塞主流程 | 回调成功才扣减库存并置 sync_status='fin';回调失败/异常/组装失败 → sync_status='error' + 待处理异常(markPendingException,写库失败仅记录 error 日志),不扣减库存,订单可重新派发(分发前过滤只跳过 fin) |
- 查询开销:复用原有主表+明细查询;运单号仍由
buildOrderWaybillCodeMapInternal批量取(强制同仓校验,无 N+1,现在在finalizeLocalChannelOrdersInternal内、仅 API 渠道构建);appKey 反查按货主Map批内缓存(无 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)的订单按失败处理(置sync_status='error'+ 待处理异常、不扣减库存,可重新派发) - 失败文案(2026-09-13):
- 回调失败:
OpenAPI 回调确认失败: {error},例如OpenAPI 回调确认失败: 回调返回非 2xx 状态码: 400;订单结果新增返回字段callback_retry_count(回调实际重试次数) - 回调抛异常:
OpenAPI 回调确认异常: ... - 报文组装缺货主编码:
发货单缺少奇门货主编码 - 缺 store_id:
发货单缺少货主 store_id,无法解析回传用 appKey - 无可用 ApiApp(无授权关系 / 无「启用且 callback_url 非空」配置):
货主未配置可用的 OpenAPI 回调(wms_api_app 启用且 callback_url 非空)
- 回调失败:
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"
}
}
3.6 waybill.getreceive(查询型回调)
- label:运单揽收状态查询
- description:按运单号批量查询是否已揽收;与 3.1~3.5 的推送型事件不同,本事件消费外部响应并回写
wms_order_express.is_galaxy_receive - 注册位置:
app/lib/callback_functions.js#CALLBACK_FUNCTIONS(管理端应用可勾选承接该方法) - 实现:
app/service/systems/waybill.js#queryReceiveStatus(底层方法);业务入口waybill.warehouse.updateReceive(异步任务模式,进度走waybill.warehouse.updateReceiveTaskProgress) - 运单号来源:显式
waybillCodes,或where(与waybill.warehouse.list同一套筛选口径,不含分页/排序;匹配数上限 5000,超限要求缩小范围) - 目标应用解析:未显式传
appKey时,取该仓库callback_functions勾选了waybill.getreceive的首个应用(按id升序) - 批量上限:单次回调最多 10 个运单号(外部接口上限),超出自动切批并逐批更新任务进度
- 签名口径(与 3.1~3.5 不同):
sign = MD5(appSecret + timestamp + bodyJson),即methods/warehouse_notify.json描述的仓库通知协议,而非 2.4 节的MD5(canonicalQuery + appSecret + MD5(body));实现为openapi/callback.js#signCallback({ signMode: 'simple' })。query 仍携带method/v/timestamp/app_key/sign - 失败识别:HTTP 200 但响应体
code非0/1/200(如验签失败返回{"code":401,"msg":"签名验证失败"})时整批判失败,不写入揽收状态 request结构(经sendByAppKey统一包装,线路报文为{ request: {...} }):
{
"request": {
"waybill_codes": [ "YT1234567890" ]
}
}
- 外部响应:裸数组
[{ "waybill_code": "YT1234567890", "is_galaxy_receive": 1 }];同时兼容{ "code": 200, "data": [...] }包装 is_galaxy_receive兼容取值:1/0、'Y'/'N'(大小写不敏感)、布尔值;非法取值计入failed,不写库- 回写口径:按
waybill_code+warehouse_id更新wms_order_express.is_galaxy_receive(1→Y、0→N),跨仓不串写
3.7 waybill.getTrace(查询型回调:物流轨迹)
- label:运单物流轨迹查询
- description:按运单号批量查询物流轨迹;消费外部响应并落库
wms_order_express_trace - 注册位置:
app/lib/callback_functions.js#CALLBACK_FUNCTIONS - 实现:
app/service/systems/waybill.js#queryTraces+#saveTraces;业务入口waybill.warehouse.updateTrace(进度走waybill.warehouse.updateTraceTaskProgress) - 入参:与
waybill.getreceive一致({ request: { waybill_codes: [...] } },单批最多 10 单);签名同样为MD5(appSecret + timestamp + bodyJson) - 响应:
[{
"waybillNo": "770358128188071",
"trace": {
"opTime": "2026-11-10 06:15:53",
"outBizCode": "770358128188071_510180_1794262553000_210",
"memo": "【广州市】快件已发往 山东济南转运中心",
"opOrgCityName": "广州市",
"weight": 0,
"scanType": "发件"
}
}]
- 兼容:
trace可为数组(一个运单多条轨迹)、traces/traceList数组、{ code, data: [...] }包装 - 落库:
wms_order_express_trace,唯一键(express_id, op_time, scan_type)幂等,命中时更新memo/op_org_city_name/weight/raw_data - 失败识别:与 3.6 相同(HTTP 200 但
code非0/1/200整批判失败)
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 - 查询型回调实现:
app/service/systems/waybill.js#queryReceiveStatus(waybill.getreceive);同类的deliveryorder.getwaybill/deliveryorder.getprintdata分别见app/service/systems/express_platform.js、app/service/systems/order_print.js - 回调 method 注册表(管理端可勾选):
app/lib/callback_functions.js#CALLBACK_FUNCTIONS - 接口文档 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.4.0);变更记录写入methods/changes/openapi_callback.json(首条 version2026.09.12-openapi-callback-init,typeadded;最新 version2026.09.13-openapi-callback-confirm-before-deduct,typeupdated)。 - 本次无入站接口契约变更:
methods/openapi.json、methods/system.json、methods/qimen.json均未改动。 methods/changes/*.json中历史记录提及的旧事件名(stockout_completed、entry_order_direct_inbound_completed、entry_order_receiving_matched等)为追加式历史,保持原样,不回改。