# 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 请求体结构 ```json { "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 入口验签算法一致)。 1. `canonicalQuery`:query 中除 `sign` / `signature`(大小写不敏感)外、值非 `undefined` 的参数,按 key 字母序升序,拼为 `key=value&key2=value2`。值为原始字符串(**不 URL 编码**);对象值经 `stableStringify`。 2. `bodySign = md5(stableStringify(body))`;`stableStringify` 对对象键做字母序排序后 JSON 序列化;`body` 即完整报文 `{ request: {...} }`。 3. `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.curl` `timeout: 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` 组装): ```json { "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_时间戳`;`confirmType` 0=最终确认 / 1=部分确认;`status` `FULFILLED` / `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` 固定 `FULFILLED` - `request` 结构(注册表 `request` 模板口径;QM/API 共用 `buildEntryOrderConfirmRequest` 组装): ```json { "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`(按 `app_key` 解析) - **逐单发送语义(2026-09-13 变化)**: | 维度 | 改动前 | 改动后 | |---|---|---| | 通知对象 | 一次回调携带整批 `orderIds`(含失败/跳过) | 仅对 `syncResults` 中 `status==='success'` 的订单逐单发送 | | 回调次数 | 每批次 1 次 | 成功 N 单 = N 次回调 | | 报文内容 | 批次汇总 `{ orderIds, status, successCount, failedCount }` | 每单独立奇门同层级 `request` 报文(`buildQimenDeliveryOrderConfirmDataInternal` 组装) | | 失败处理 | 不阻塞主流程 | 单订单组装/发送失败仅 warn,不影响其他订单与主流程 | - 查询开销:复用原有主表+明细查询,新增 1 次运单号批量查询(`buildOrderWaybillCodeMapInternal`,强制同仓校验,无 N+1) - `request` 结构(注册表 `request` 模板口径): ```json { "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` 模板口径): ```json { "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` 模板口径): ```json { "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.md` 5.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`(首条 version `2026.09.12-openapi-callback-init`,type `added`;本次 version `2026.09.13-openapi-callback-request-protocol`,type `updated`)。 - 本次无入站接口契约变更:`methods/openapi.json`、`methods/system.json`、`methods/qimen.json` 均未改动。 - `methods/changes/*.json` 中历史记录提及的旧事件名(`stockout_completed`、`entry_order_direct_inbound_completed`、`entry_order_receiving_matched` 等)为追加式历史,保持原样,不回改。