WMS_MAIN/docs/openapi-callback-events.md
liufumingren e3eff20aaa feat(waybill): 批量更新运单揽收状态(waybill.getreceive)与 Y/N 标记列治理
- 新增出站回调 waybill.getreceive(注册到 callback_functions,管理端可勾选):
  请求 { request: { waybill_codes: [...] } },响应裸数组/包装体均兼容,
  1/0 与 Y/N 归一后回写 wms_order_express.is_galaxy_receive(按 warehouse_id 隔离)
- 回调签名新增 signMode=simple(MD5(appSecret+timestamp+bodyJson)),
  waybill.getreceive 使用该口径,与仓库通知协议一致;其它事件默认口径不变
- 新增 waybill.warehouse.updateReceive / updateReceiveTaskProgress:
  复用导出的异步任务ID与进度模式(前缀 waybill_receive_),单批 10 单自动切批;
  支持 waybillCodes 或与 waybill.warehouse.list 一致的 where 条件圈选(上限 5000);
  仓库未配置外部接口时直接失败,不创建任务
- 抽出 buildListQueryWhere / resolveWaybillCodesByWhere,列表与批量更新共用筛选口径
- order_express:is_back / is_intercept / is_galaxy_receive 补默认值 N
- 迁移:存量 NULL 回填为 N(Y 不动);三列分别建立单列索引(INPLACE + LOCK=NONE)
- 文档:methods/system.json(0.3.324)、变更记录、设计文档与出站回调说明同步

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-11 04:22:30 +08:00

26 KiB
Raw Blame History

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&timestamp={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 入口验签算法一致)。

  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&timestamp=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)。
  • 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_时间戳;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 组装):
{
  "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),跨仓不串写

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
  • 查询型回调实现: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(首条 version 2026.09.12-openapi-callback-init,type added;最新 version 2026.09.13-openapi-callback-confirm-before-deduct,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 等)为追加式历史,保持原样,不回改。