- 新增出站回调 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>
420 lines
26 KiB
Markdown
420 lines
26 KiB
Markdown
# 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 请求体结构
|
||
|
||
```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)。
|
||
- `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` 组装):
|
||
|
||
```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: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` 模板口径):
|
||
|
||
```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"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 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: {...} }`):
|
||
|
||
```json
|
||
{
|
||
"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` 等)为追加式历史,保持原样,不回改。
|