- storeWarehouse.store.saveApiConfig:新增 resolveContractApiInterfaceType, interface_type_id=3(OPEN_API_WAREHOUSE 仓库开放接口)自动映射为 2(OPEN_API 货主开放接口)落库, 不再要求当前主体为仓库(货主可维护自身签约关系下的接口配置) - callback_url 不再取入参(含 callbackUrl 别名),统一写入 config.openapi.defaultCallbackUrl(新增配置项,默认空) - storeWarehouse.store.listApiConfig:interface_type_id 过滤同步映射(传 3 按 2 查询) - 文档:methods/system.json 升级 0.3.350、methods/changes/system.json 变更记录、docs/openapi-callback-events.md 回调地址来源说明 - 测试:saveApiConfig 新增 4 条用例(3→2 落库、忽略入参回调地址、默认值未配置、货主主体可保存、缺失类型 404),listApiConfig 新增 1 条过滤映射用例 同时提交工作区其余在制品改动: - waybill:移除 wms_order_express_trace 模型并新增 drop 迁移,轨迹查询/取号/打印链路调整 - order:订单 SN 编码(order_item_sn / order_item_sn_log / sn_code_rule、has_sn_item 回填迁移),pendingOrder/recheckOrder/wave/base 调整 - express_platform、order_async、order_export、order_storage_allocation、storage.report、stock_store 配套修复 - lib:新增 jd_client,调整 qimen_client、callback_functions 及配套测试 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
28 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 非空)。
签约关系级接口配置(
storeWarehouse.store.saveApiConfig)不再接收callback_url入参:保存时统一写入config.openapi.defaultCallbackUrl(未配置时写null),因此上表取值实际由该配置项决定,修改回调地址需调整环境配置后重新保存接口配置。
| 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 个运单号(外部接口上限),超出自动切批并逐批更新任务进度
- 运单号后缀:运单在该仓库的
wms_order_express命中、且其logistics_interface_id关联的wms_express_interface.sender_tel至少 4 位数字时,出站统一发送运单号|寄件电话后四位(如776447927635244|8000,非数字字符先剔除),供外部接口校验收寄件人手机号;未命中运单、未关联接口或电话不足四位时按纯运单号发送。回写仍按纯运单号匹配,外部响应里带|后缀也能正确回写 - 签名口径(与 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|8000" ]
}
}
无寄件电话后四位可补时,
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:按运单号查询物流轨迹;消费外部响应并直接返回给调用方(**不落库**)
- 注册位置:`app/lib/callback_functions.js#CALLBACK_FUNCTIONS`
- 实现:`app/service/systems/waybill.js#fetchTracesByWaybill`;业务入口 `waybill.warehouse.getTrace`(单运单、实时回源)
- 入参:`{ request: { waybill_codes: ["770358128188071"] } }`(单运单),运单号同样按 3.6 的规则补寄件电话后四位(`运单号|后四位`);签名同样为 `MD5(appSecret + timestamp + bodyJson)`
- 响应:
```json
[{
"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: [...] }包装、单个对象返回;响应行waybillNo带|后四位后缀时按纯运单号匹配 trace: [](暂无轨迹):属正常业务状态(如刚下单未揽收),接口返回success+total=0weight:可能返回字符串小数(如"0.99"),WMS 统一转数字保留 3 位小数- 不落库:轨迹表
wms_order_express_trace已删除(迁移20261111205500),每次查询都实时回源 - 揽收联动:命中轨迹(非空)时把该运单
wms_order_express.is_galaxy_receive置为Y(只升不降),计数见返回的received_updated - 失败识别:与 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等)为追加式历史,保持原样,不回改。