WMS_MAIN/methods/openapi_callback.json
liufumingren a15c877f04 fix(order): API 渠道订单同步改为先回传确认、成功后再扣减库存
- 删除 notifyApiDeliveryOrderConfirmsInternal(原「同步完成后 fire-and-forget
  逐单回调、失败仅 warn」),新增 processApiOrderInternal 在同一个分发循环内逐单
  处理:组装 deliveryorder.confirm 报文 → 解析发送用 appKey → sendByAppKey
  (最多 4 次尝试)→ 回调成功才扣减库存并置 sync_status='fin'
- 新增 markApiSyncFailedInternal:回调失败/异常、报文组装配不上货主编码、
  解析不到 appKey 等一律置 sync_status='error' + 待处理异常,不扣减库存、不置
  fin,订单可重新派发(分发前过滤仅跳过 fin)
- 解析不到 appKey 的订单不再静默跳过,改为按失败处理
- 同步 docs/openapi-callback-events.md、methods/openapi_callback.json 与
  methods/changes/openapi_callback.json
2026-09-15 16:18:32 +08:00

1347 lines
67 KiB
JSON
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

{
"module": "openapi_callback",
"description": "开放 API 出站回调定义(出站方向:WMS → 外部)。WMS 在业务完成后按 ApiApp 配置的 callback_url 主动推送事件通知:query 携带 method/v/timestamp/app_key/sign,报文体统一为奇门同层级的 { request: {...} }(event 仅出现在 query 的 method),使用 MD5 签名鉴权。入站接口请参阅 openapi.json。",
"version": "1.4.0",
"updatedAt": "2026-09-13",
"http": {
"path": "{ApiApp.callback_url}",
"method": "POST"
},
"headers": [
{
"name": "Content-Type",
"type": "string",
"required": true,
"description": "application/json"
}
],
"methods": {
"groups": [
{
"groupName": "出站回调事件",
"module": "callback",
"list": [
{
"method": "entryorder.confirm",
"description": "入库单确认完成(直入)出站回调。直入入库(API 来源,source_type=API)完成后,WMS 向外部回传入库完成信息(对应奇门 taobao.qimen.entryorder.confirm)。触发实现:app/service/systems/inbound_direct_log.js#qimenEntrySync 的 API 分支 → _sendOpenApiCallback(throwOnError=true,回传成功才执行本地回调)。request 报文由 buildEntryOrderConfirmRequest 组装,奇门(QM)与 OpenAPI(API)共用。",
"isNeedAuth": true,
"isNeedLogin": false,
"headers": [],
"params": [
{
"name": "method",
"type": "string",
"required": true,
"source": "query",
"description": "回调 method(模块.动作,如 entryorder.confirm),由 WMS 计算后发出(不是接收方入参);event 仅出现在 query 的 method,报文体不再携带 event 字段;URL 中做 encodeURIComponent"
},
{
"name": "v",
"type": "string",
"required": true,
"source": "query",
"description": "协议版本,由 WMS 发出,固定 1.0"
},
{
"name": "timestamp",
"type": "string",
"required": true,
"source": "query",
"description": "时间戳,由 WMS 发出,统一为秒级(10 位字符串,String(Math.floor(Date.now()/1000)));与 /openapi 入站时效校验(±600 秒窗口,Math.floor(Date.now()/1000))及回调调试页(nowTimestamp)口径一致,可作为规范值对外承诺"
},
{
"name": "app_key",
"type": "string",
"required": true,
"source": "query",
"description": "应用标识(api_app.self_app_key),由 WMS 发出;URL 中做 encodeURIComponent"
},
{
"name": "sign",
"type": "string",
"required": true,
"source": "query",
"description": "MD5 签名,由 WMS 计算后发出;sign = md5(canonicalQuery + selfAppSecret + md5(stableStringify(body))),小写十六进制"
},
{
"name": "request",
"type": "object",
"required": true,
"source": "body",
"description": "奇门同层级业务报文 { entryOrder, orderLines }(不含外层 request 包装,发送端统一包装为 body = { request });口径与 callbackRegistry.js 的 request 模板一致,结构见下方 request.* 子字段"
},
{
"name": "request.entryOrder",
"type": "object",
"required": true,
"source": "body",
"description": "入库单头信息"
},
{
"name": "request.entryOrder.entryOrderCode",
"type": "string",
"required": true,
"source": "body",
"description": "入库单编码(wms_entry_order.entry_order_code)"
},
{
"name": "request.entryOrder.ownerCode",
"type": "string",
"required": true,
"source": "body",
"description": "奇门货主编码(wms_entry_order.qimen_owner_code)"
},
{
"name": "request.entryOrder.warehouseCode",
"type": "string",
"required": true,
"source": "body",
"description": "奇门仓库编码(wms_entry_order.qimen_warehouse_code)"
},
{
"name": "request.entryOrder.entryOrderId",
"type": "number",
"required": true,
"source": "body",
"description": "入库单 ID(wms_entry_order.id)"
},
{
"name": "request.entryOrder.entryOrderType",
"type": "string",
"required": true,
"source": "body",
"description": "入库单类型(wms_entry_order.order_type,如 SCRK)"
},
{
"name": "request.entryOrder.outBizCode",
"type": "string",
"required": true,
"source": "body",
"description": "外部业务编码,缺省自动生成 DIRECT_INBOUND_时间戳(毫秒)"
},
{
"name": "request.entryOrder.confirmType",
"type": "number",
"required": true,
"source": "body",
"description": "确认类型:0=最终确认 / 1=部分确认(isFin)"
},
{
"name": "request.entryOrder.status",
"type": "string",
"required": true,
"source": "body",
"description": "FULFILLED(最终确认)/ PARTFULFILLED(部分确认)"
},
{
"name": "request.entryOrder.freight",
"type": "number",
"required": true,
"source": "body",
"description": "运费,固定 0"
},
{
"name": "request.entryOrder.operateTime",
"type": "string",
"required": true,
"source": "body",
"description": "操作时间(app.formatDate(new Date()))"
},
{
"name": "request.entryOrder.remark",
"type": "string",
"required": true,
"source": "body",
"description": "备注(如「导入/PDA直接入库提交」)"
},
{
"name": "request.orderLines",
"type": "array",
"required": true,
"source": "body",
"description": "入库明细行数组:[ { orderLineNo, ownerCode, itemCode, itemId, inventoryType, planQty, actualQty } ]"
},
{
"name": "request.orderLines[].orderLineNo",
"type": "number",
"required": true,
"source": "body",
"description": "行号(从 1 递增)"
},
{
"name": "request.orderLines[].ownerCode",
"type": "string",
"required": true,
"source": "body",
"description": "货主编码"
},
{
"name": "request.orderLines[].itemCode",
"type": "string",
"required": true,
"source": "body",
"description": "商品编码"
},
{
"name": "request.orderLines[].itemId",
"type": "string",
"required": true,
"source": "body",
"description": "商品 ID"
},
{
"name": "request.orderLines[].inventoryType",
"type": "string",
"required": true,
"source": "body",
"description": "库存类型(如 ZP)"
},
{
"name": "request.orderLines[].planQty",
"type": "number",
"required": true,
"source": "body",
"description": "计划数量"
},
{
"name": "request.orderLines[].actualQty",
"type": "number",
"required": true,
"source": "body",
"description": "实际入库数量"
}
],
"response": [
{
"name": "http_status",
"type": "number",
"required": true,
"description": "接收方应返回任意 2xx 状态码(200 ≤ status < 300,如 200/201/204);WMS 仅按 HTTP 状态码判定成功,响应体内容不参与判定"
},
{
"name": "response_body",
"type": "object",
"required": false,
"description": "响应体无约定格式;WMS 不校验业务码,返回 2xx 即视为成功,非 2xx 或网络错误进入重试(至多 3 次,间隔 2s→5s→15s)"
}
],
"errors": [
{
"code": 400,
"message": "接收方返回 400(如参数/验签不通过):WMS 视为回调失败,进入重试,至多 3 次(间隔 2s→5s→15s),全部失败后判定最终失败"
},
{
"code": 401,
"message": "接收方返回 401(鉴权失败):处理同 400,重试至多 3 次后判定最终失败"
},
{
"code": 403,
"message": "接收方返回 403(拒绝访问):处理同 400,重试至多 3 次后判定最终失败"
},
{
"code": "5xx",
"message": "接收方返回 5xx(服务端错误):处理同 400,重试至多 3 次后判定最终失败"
},
{
"code": "NETWORK_ERROR",
"message": "网络错误或单次请求超时(30s):处理同非 2xx,重试至多 3 次后判定最终失败"
}
],
"notes": [
"本文件描述出站方向(WMS → 外部)回调;入站接口请参阅 methods/openapi.json",
"签名算法:sign = md5(canonicalQuery + selfAppSecret + md5(stableStringify(body))),小写十六进制;canonicalQuery 为 query 中除 sign/signature 外、值非 undefined 的参数按 key 升序拼成的 key=value&… 串(值为原始字符串,不 URL 编码),selfAppSecret 为 api_app.self_app_secret",
"重试策略:非 2xx 响应或网络错误触发重试,至多重试 3 次(即最多 4 次尝试),间隔 2s→5s→15s,单次请求超时 30s;全部失败后判定回调失败",
"报文体统一为奇门同层级的 { request: {...} }(发送端统一包装 body = { request: request || {} }),event 仅出现在 query 的 method",
"事件注册表:app/service/openapi/callbackRegistry.js#CALLBACK_EVENTS;调试页:GET /docs/api/openapi/callback-test(app/controller/openapiCallback.js 按注册表自动预填完整报文体 { request: {...} },可编辑后发送)",
"发送途径:sendWithRetry 直调(按 StoreWarehouse auth_status=2 → ApiApp contract_id/is_enabled=1/callback_url 非空 定位)",
"回传成功才执行本地回调(throwOnError=true,失败抛出并写 QUICK_INBOUND_FAILED 操作日志)"
]
},
{
"method": "entryorder.match",
"description": "入库单匹配收货完成出站回调。入库单匹配收货单完成后(API 来源,source_type=API),WMS 向外部回传匹配完成信息(对应奇门 taobao.qimen.entryorder.confirm)。触发实现:app/service/systems/receiving_entry_match.js#matchAfterEntryCompleted 在绑定成功且本次确实新建绑定(bindResult.created === true)时调用 _sendCallback(entryOrder, matchedReceiving, 'auto_match') 的 API 分支 → _sendOpenApiCallback(event=entryorder.match);重复触发时绑定已存在(created=false)不会重复回传;回传失败仅记录 warn,不影响绑定与入库单状态更新。request 报文由 buildEntryOrderConfirmRequest 组装,奇门(QM)与 OpenAPI(API)共用。",
"isNeedAuth": true,
"isNeedLogin": false,
"headers": [],
"params": [
{
"name": "method",
"type": "string",
"required": true,
"source": "query",
"description": "回调 method(模块.动作,如 entryorder.match),由 WMS 计算后发出(不是接收方入参);event 仅出现在 query 的 method,报文体不再携带 event 字段;URL 中做 encodeURIComponent"
},
{
"name": "v",
"type": "string",
"required": true,
"source": "query",
"description": "协议版本,由 WMS 发出,固定 1.0"
},
{
"name": "timestamp",
"type": "string",
"required": true,
"source": "query",
"description": "时间戳,由 WMS 发出,统一为秒级(10 位字符串,String(Math.floor(Date.now()/1000)));与 /openapi 入站时效校验(±600 秒窗口,Math.floor(Date.now()/1000))及回调调试页(nowTimestamp)口径一致,可作为规范值对外承诺"
},
{
"name": "app_key",
"type": "string",
"required": true,
"source": "query",
"description": "应用标识(api_app.self_app_key),由 WMS 发出;URL 中做 encodeURIComponent"
},
{
"name": "sign",
"type": "string",
"required": true,
"source": "query",
"description": "MD5 签名,由 WMS 计算后发出;sign = md5(canonicalQuery + selfAppSecret + md5(stableStringify(body))),小写十六进制"
},
{
"name": "request",
"type": "object",
"required": true,
"source": "body",
"description": "奇门同层级业务报文 { entryOrder, orderLines }(不含外层 request 包装,发送端统一包装为 body = { request });口径与 callbackRegistry.js 的 request 模板一致,结构见下方 request.* 子字段"
},
{
"name": "request.entryOrder",
"type": "object",
"required": true,
"source": "body",
"description": "入库单头信息"
},
{
"name": "request.entryOrder.entryOrderCode",
"type": "string",
"required": true,
"source": "body",
"description": "入库单编码(wms_entry_order.entry_order_code)"
},
{
"name": "request.entryOrder.ownerCode",
"type": "string",
"required": true,
"source": "body",
"description": "奇门货主编码(wms_entry_order.qimen_owner_code)"
},
{
"name": "request.entryOrder.warehouseCode",
"type": "string",
"required": true,
"source": "body",
"description": "奇门仓库编码(wms_entry_order.qimen_warehouse_code)"
},
{
"name": "request.entryOrder.entryOrderId",
"type": "number",
"required": true,
"source": "body",
"description": "入库单 ID(wms_entry_order.id)"
},
{
"name": "request.entryOrder.entryOrderType",
"type": "string",
"required": true,
"source": "body",
"description": "入库单类型(wms_entry_order.order_type,如 SCRK)"
},
{
"name": "request.entryOrder.outBizCode",
"type": "string",
"required": true,
"source": "body",
"description": "外部业务编码,缺省自动生成 RECEIVING_MATCH_时间戳(毫秒)"
},
{
"name": "request.entryOrder.confirmType",
"type": "number",
"required": true,
"source": "body",
"description": "确认类型,固定 0(最终确认)"
},
{
"name": "request.entryOrder.status",
"type": "string",
"required": true,
"source": "body",
"description": "固定 FULFILLED"
},
{
"name": "request.entryOrder.freight",
"type": "number",
"required": true,
"source": "body",
"description": "运费,固定 0"
},
{
"name": "request.entryOrder.operateTime",
"type": "string",
"required": true,
"source": "body",
"description": "操作时间(app.formatDate(new Date()))"
},
{
"name": "request.entryOrder.remark",
"type": "string",
"required": true,
"source": "body",
"description": "备注,固定「匹配收货单{收货单号}自动回传」(如 匹配收货单RCV20260912001自动回传)"
},
{
"name": "request.orderLines",
"type": "array",
"required": true,
"source": "body",
"description": "入库明细行数组:[ { orderLineNo, ownerCode, itemCode, itemId, inventoryType, planQty, actualQty } ]"
},
{
"name": "request.orderLines[].orderLineNo",
"type": "number",
"required": true,
"source": "body",
"description": "行号(从 1 递增)"
},
{
"name": "request.orderLines[].ownerCode",
"type": "string",
"required": true,
"source": "body",
"description": "货主编码"
},
{
"name": "request.orderLines[].itemCode",
"type": "string",
"required": true,
"source": "body",
"description": "商品编码"
},
{
"name": "request.orderLines[].itemId",
"type": "string",
"required": true,
"source": "body",
"description": "商品 ID"
},
{
"name": "request.orderLines[].inventoryType",
"type": "string",
"required": true,
"source": "body",
"description": "库存类型,缺省 ZP"
},
{
"name": "request.orderLines[].planQty",
"type": "number",
"required": true,
"source": "body",
"description": "计划数量(wms_entry_items.count)"
},
{
"name": "request.orderLines[].actualQty",
"type": "number",
"required": true,
"source": "body",
"description": "实际入库数量(wms_entry_items.received_quantity)"
}
],
"response": [
{
"name": "http_status",
"type": "number",
"required": true,
"description": "接收方应返回任意 2xx 状态码(200 ≤ status < 300,如 200/201/204);WMS 仅按 HTTP 状态码判定成功,响应体内容不参与判定"
},
{
"name": "response_body",
"type": "object",
"required": false,
"description": "响应体无约定格式;WMS 不校验业务码,返回 2xx 即视为成功,非 2xx 或网络错误进入重试(至多 3 次,间隔 2s→5s→15s)"
}
],
"errors": [
{
"code": 400,
"message": "接收方返回 400(如参数/验签不通过):WMS 视为回调失败,进入重试,至多 3 次(间隔 2s→5s→15s),全部失败后判定最终失败"
},
{
"code": 401,
"message": "接收方返回 401(鉴权失败):处理同 400,重试至多 3 次后判定最终失败"
},
{
"code": 403,
"message": "接收方返回 403(拒绝访问):处理同 400,重试至多 3 次后判定最终失败"
},
{
"code": "5xx",
"message": "接收方返回 5xx(服务端错误):处理同 400,重试至多 3 次后判定最终失败"
},
{
"code": "NETWORK_ERROR",
"message": "网络错误或单次请求超时(30s):处理同非 2xx,重试至多 3 次后判定最终失败"
}
],
"notes": [
"本文件描述出站方向(WMS → 外部)回调;入站接口请参阅 methods/openapi.json",
"签名算法:sign = md5(canonicalQuery + selfAppSecret + md5(stableStringify(body))),小写十六进制;canonicalQuery 为 query 中除 sign/signature 外、值非 undefined 的参数按 key 升序拼成的 key=value&… 串(值为原始字符串,不 URL 编码),selfAppSecret 为 api_app.self_app_secret",
"重试策略:非 2xx 响应或网络错误触发重试,至多重试 3 次(即最多 4 次尝试),间隔 2s→5s→15s,单次请求超时 30s;全部失败后判定回调失败",
"报文体统一为奇门同层级的 { request: {...} }(发送端统一包装 body = { request: request || {} }),event 仅出现在 query 的 method",
"事件注册表:app/service/openapi/callbackRegistry.js#CALLBACK_EVENTS;调试页:GET /docs/api/openapi/callback-test(app/controller/openapiCallback.js 按注册表自动预填完整报文体 { request: {...} },可编辑后发送)",
"发送途径:sendWithRetry 直调(按 StoreWarehouse auth_status=2 → ApiApp contract_id/is_enabled=1/callback_url 非空 定位)",
"已接入:matchAfterEntryCompleted 在绑定成功且本次新建绑定(bindResult.created === true)时调用 _sendCallback(entryOrder, matchedReceiving, 'auto_match');重复触发不重复回传;回传失败仅 warn 不影响绑定"
]
},
{
"method": "deliveryorder.confirm",
"description": "订单发货完成出站回调(逐单「先回调、成功再扣减」)。触发前提:createChannel=API,逐单在 finalizeLocalChannelOrdersInternal 分发循环(DISPATCH_BATCH_SIZE=20 批内并行)内直接发送,不再要求本批先出现同步成功订单。每单流程:① buildQimenDeliveryOrderConfirmDataInternal 组装报文(缺 ownerCode → 失败「发货单缺少奇门货主编码」)→② 解析发送用 appKey(context.appKey 优先,缺失时按订单货主 store_id + warehouse_id 合约反查 wms_store_warehouse(auth_status=2) → wms_api_app(is_enabled=1 且 callback_url 非空) 的 self_app_key;同批次按货主 Map 缓存,无 N+1)→③ sendByAppKey 发送 deliveryorder.confirm(最多 4 次尝试)→④ 回调成功才调用 processLocalChannelOrderInternal 扣减库存并置 sync_status='fin';失败统一走 markApiSyncFailedInternal:回写 sync_status='error' + markPendingException(写库失败仅记录 error 日志),不扣减库存、不置 fin,订单可重新派发(分发前过滤只跳过 fin)。触发实现:app/service/systems/order_async.js#finalizeLocalChannelOrdersInternal → processApiOrderInternal(复用 buildQimenDeliveryOrderConfirmDataInternal 组装与奇门 taobao.qimen.deliveryorder.confirm 完全一致的 request 报文;运单号由 buildOrderWaybillCodeMapInternal 批量取、仅 API 渠道构建,无 N+1)。",
"isNeedAuth": true,
"isNeedLogin": false,
"headers": [],
"params": [
{
"name": "method",
"type": "string",
"required": true,
"source": "query",
"description": "回调 method(模块.动作,如 deliveryorder.confirm),由 WMS 计算后发出(不是接收方入参);event 仅出现在 query 的 method,报文体不再携带 event 字段;URL 中做 encodeURIComponent"
},
{
"name": "v",
"type": "string",
"required": true,
"source": "query",
"description": "协议版本,由 WMS 发出,固定 1.0"
},
{
"name": "timestamp",
"type": "string",
"required": true,
"source": "query",
"description": "时间戳,由 WMS 发出,统一为秒级(10 位字符串,String(Math.floor(Date.now()/1000)));与 /openapi 入站时效校验(±600 秒窗口,Math.floor(Date.now()/1000))及回调调试页(nowTimestamp)口径一致,可作为规范值对外承诺"
},
{
"name": "app_key",
"type": "string",
"required": true,
"source": "query",
"description": "应用标识(api_app.self_app_key),由 WMS 发出;URL 中做 encodeURIComponent"
},
{
"name": "sign",
"type": "string",
"required": true,
"source": "query",
"description": "MD5 签名,由 WMS 计算后发出;sign = md5(canonicalQuery + selfAppSecret + md5(stableStringify(body))),小写十六进制"
},
{
"name": "request",
"type": "object",
"required": true,
"source": "body",
"description": "奇门同层级业务报文 { deliveryOrder, packages, orderLines }(不含外层 request 包装,发送端统一包装为 body = { request });口径与 callbackRegistry.js 的 request 模板一致,结构见下方 request.* 子字段"
},
{
"name": "request.deliveryOrder",
"type": "object",
"required": true,
"source": "body",
"description": "发货单头信息"
},
{
"name": "request.deliveryOrder.totalOrderLines",
"type": "number",
"required": true,
"source": "body",
"description": "明细行数(orderLines.length)"
},
{
"name": "request.deliveryOrder.deliveryOrderCode",
"type": "string",
"required": true,
"source": "body",
"description": "发货单编码(wms_order.delivery_order_code)"
},
{
"name": "request.deliveryOrder.deliveryOrderId",
"type": "number",
"required": true,
"source": "body",
"description": "订单 ID(wms_order.id)"
},
{
"name": "request.deliveryOrder.warehouseCode",
"type": "string",
"required": true,
"source": "body",
"description": "仓库编码"
},
{
"name": "request.deliveryOrder.orderType",
"type": "string",
"required": true,
"source": "body",
"description": "单据类型(wms_order.order_type,如 JYCK)"
},
{
"name": "request.deliveryOrder.status",
"type": "string",
"required": true,
"source": "body",
"description": "固定 DELIVERED"
},
{
"name": "request.deliveryOrder.outBizCode",
"type": "string",
"required": true,
"source": "body",
"description": "外部业务编码,同 deliveryOrderCode"
},
{
"name": "request.deliveryOrder.confirmType",
"type": "number",
"required": true,
"source": "body",
"description": "固定 0(最终确认)"
},
{
"name": "request.deliveryOrder.orderConfirmTime",
"type": "string",
"required": true,
"source": "body",
"description": "确认时间(app.formatDate(new Date()))"
},
{
"name": "request.deliveryOrder.operatorCode",
"type": "string",
"required": true,
"source": "body",
"description": "操作员编码,固定空字符串"
},
{
"name": "request.deliveryOrder.operatorName",
"type": "string",
"required": true,
"source": "body",
"description": "操作员名称,固定空字符串"
},
{
"name": "request.deliveryOrder.storageFee",
"type": "string",
"required": true,
"source": "body",
"description": "仓储费(wms_order.storage_fee,字符串)"
},
{
"name": "request.deliveryOrder.operateTime",
"type": "string",
"required": true,
"source": "body",
"description": "操作时间(app.formatDate(new Date()))"
},
{
"name": "request.packages",
"type": "object",
"required": true,
"source": "body",
"description": "包裹信息对象 { package: [...] }"
},
{
"name": "request.packages.package",
"type": "array",
"required": true,
"source": "body",
"description": "包裹数组(每个运单号一条)"
},
{
"name": "request.packages.package[].logisticsCode",
"type": "string",
"required": true,
"source": "body",
"description": "物流公司编码(wms_order.logistics_code)"
},
{
"name": "request.packages.package[].logisticsName",
"type": "string",
"required": true,
"source": "body",
"description": "物流公司名称(wms_order.logistics_name)"
},
{
"name": "request.packages.package[].expressCode",
"type": "string",
"required": true,
"source": "body",
"description": "运单号(wms_order_express 批量查询,同仓校验)"
},
{
"name": "request.packages.package[].packageCode",
"type": "string",
"required": true,
"source": "body",
"description": "包裹编码(package_code 缺省同 deliveryOrderCode)"
},
{
"name": "request.packages.package[].invoiceNo",
"type": "string",
"required": true,
"source": "body",
"description": "发票号(wms_order.invoice_no)"
},
{
"name": "request.packages.package[].items",
"type": "array",
"required": true,
"source": "body",
"description": "包裹内商品行:[ { itemCode, itemId, quantity } ]"
},
{
"name": "request.packages.package[].items[].itemCode",
"type": "string",
"required": true,
"source": "body",
"description": "商品编码"
},
{
"name": "request.packages.package[].items[].itemId",
"type": "string",
"required": true,
"source": "body",
"description": "商品 ID"
},
{
"name": "request.packages.package[].items[].quantity",
"type": "number",
"required": true,
"source": "body",
"description": "数量"
},
{
"name": "request.orderLines",
"type": "array",
"required": true,
"source": "body",
"description": "发货明细行数组"
},
{
"name": "request.orderLines[].orderLineNo",
"type": "string",
"required": true,
"source": "body",
"description": "行号(字符串)"
},
{
"name": "request.orderLines[].orderSourceCode",
"type": "string",
"required": true,
"source": "body",
"description": "订单来源编码(source_order_code)"
},
{
"name": "request.orderLines[].subSourceCode",
"type": "string",
"required": true,
"source": "body",
"description": "子来源编码(sub_source_order_code)"
},
{
"name": "request.orderLines[].ownerCode",
"type": "string",
"required": true,
"source": "body",
"description": "货主编码"
},
{
"name": "request.orderLines[].itemCode",
"type": "string",
"required": true,
"source": "body",
"description": "商品编码"
},
{
"name": "request.orderLines[].itemId",
"type": "string",
"required": true,
"source": "body",
"description": "商品 ID"
},
{
"name": "request.orderLines[].itemName",
"type": "string",
"required": true,
"source": "body",
"description": "商品名称"
},
{
"name": "request.orderLines[].extCode",
"type": "string",
"required": true,
"source": "body",
"description": "扩展编码(ext_code)"
},
{
"name": "request.orderLines[].planQty",
"type": "number",
"required": true,
"source": "body",
"description": "计划数量"
},
{
"name": "request.orderLines[].actualQty",
"type": "number",
"required": true,
"source": "body",
"description": "实际发货数量"
},
{
"name": "request.orderLines[].retailPrice",
"type": "number",
"required": true,
"source": "body",
"description": "零售价"
},
{
"name": "request.orderLines[].actualPrice",
"type": "number",
"required": true,
"source": "body",
"description": "实际价"
},
{
"name": "request.orderLines[].discountAmount",
"type": "string",
"required": true,
"source": "body",
"description": "优惠金额(字符串)"
},
{
"name": "request.orderLines[].inventoryType",
"type": "string",
"required": true,
"source": "body",
"description": "库存类型(如 ZP)"
},
{
"name": "request.orderLines[].snList",
"type": "array",
"required": true,
"source": "body",
"description": "序列号列表(无序列号时为空数组 [])"
},
{
"name": "request.orderLines[].qrCode",
"type": "string",
"required": true,
"source": "body",
"description": "二维码(qr_code)"
}
],
"response": [
{
"name": "http_status",
"type": "number",
"required": true,
"description": "接收方应返回任意 2xx 状态码(200 ≤ status < 300,如 200/201/204);WMS 仅按 HTTP 状态码判定成功,响应体内容不参与判定"
},
{
"name": "response_body",
"type": "object",
"required": false,
"description": "响应体无约定格式;WMS 不校验业务码,返回 2xx 即视为成功,非 2xx 或网络错误进入重试(至多 3 次,间隔 2s→5s→15s)"
}
],
"errors": [
{
"code": 400,
"message": "接收方返回 400(如参数/验签不通过):WMS 视为回调失败,进入重试,至多 3 次(间隔 2s→5s→15s),4 次尝试全部失败后该订单同步判定失败(sync_status='error' + 待处理异常,不扣减库存,可重新派发);订单结果 message 形如「OpenAPI 回调确认失败: 回调返回非 2xx 状态码: 400」并附 callback_retry_count"
},
{
"code": 401,
"message": "接收方返回 401(鉴权失败):处理同 400,4 次尝试后该订单同步判定失败(sync_status='error' + 待处理异常,不扣减库存)"
},
{
"code": 403,
"message": "接收方返回 403(拒绝访问):处理同 400,4 次尝试后该订单同步判定失败(sync_status='error' + 待处理异常,不扣减库存)"
},
{
"code": "5xx",
"message": "接收方返回 5xx(服务端错误):处理同 400,4 次尝试后该订单同步判定失败(sync_status='error' + 待处理异常,不扣减库存)"
},
{
"code": "NETWORK_ERROR",
"message": "网络错误或单次请求超时(30s):处理同非 2xx,4 次尝试后该订单同步判定失败(sync_status='error' + 待处理异常,不扣减库存)"
},
{
"code": "CALLBACK_EXCEPTION",
"message": "发送过程抛异常:订单结果 message 形如「OpenAPI 回调确认异常: {error}」,处理同回调失败(sync_status='error' + 待处理异常,不扣减库存,可重新派发)"
},
{
"code": "OWNER_CODE_MISSING",
"message": "报文组装失败:发货单缺少奇门货主编码(ownerCode 缺失),该订单同步失败(sync_status='error' + 待处理异常,不扣减库存),订单结果 message 为「发货单缺少奇门货主编码」"
},
{
"code": "STORE_ID_MISSING",
"message": "发货单缺少货主 store_id,无法解析回传用 appKey:该订单同步失败(sync_status='error' + 待处理异常,不扣减库存),订单结果 message 为「发货单缺少货主 store_id,无法解析回传用 appKey」"
},
{
"code": "NO_API_APP_CONFIG",
"message": "货主未配置可用的 OpenAPI 回调(wms_api_app 启用且 callback_url 非空):该订单同步失败(sync_status='error' + 待处理异常,不扣减库存),订单结果 message 为「货主未配置可用的 OpenAPI 回调(wms_api_app 启用且 callback_url 非空)」"
}
],
"notes": [
"本文件描述出站方向(WMS → 外部)回调;入站接口请参阅 methods/openapi.json",
"签名算法:sign = md5(canonicalQuery + selfAppSecret + md5(stableStringify(body))),小写十六进制;canonicalQuery 为 query 中除 sign/signature 外、值非 undefined 的参数按 key 升序拼成的 key=value&… 串(值为原始字符串,不 URL 编码),selfAppSecret 为 api_app.self_app_secret",
"重试策略:非 2xx 响应或网络错误触发重试,至多重试 3 次(即最多 4 次尝试),间隔 2s→5s→15s,单次请求超时 30s;4 次尝试后仍失败 ⇒ 该订单同步判定失败(sync_status='error' + 待处理异常,不扣减库存,可重新派发)",
"报文体统一为奇门同层级的 { request: {...} }(发送端统一包装 body = { request: request || {} }),event 仅出现在 query 的 method",
"事件注册表:app/service/openapi/callbackRegistry.js#CALLBACK_EVENTS;调试页:GET /docs/api/openapi/callback-test(app/controller/openapiCallback.js 按注册表自动预填完整报文体 { request: {...} },可编辑后发送)",
"发送途径:sendByAppKey;appKey 解析优先级:context.appKey 非空时优先(不触发合约反查),缺失时按订单货主(store_id + warehouse_id)合约反查 resolveOpenApiAppByStoreInternal —— wms_store_warehouse(auth_status=2) → wms_api_app(contract_id 且 is_enabled=1 且 callback_url 非空) 的 self_app_key;同一批次按货主 Map 缓存(N 单 / M 货主 → 2M 次查询,无 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(订单缺 store_id / 无授权关系 / 无可用 ApiApp 配置)不再静默跳过:按失败处理(sync_status='error' + 待处理异常,不扣减库存,可重新派发)",
"逐单先回调后扣减(2026-09-13 破坏性变更):触发前提不再是「本批存在同步成功订单」,改为逐单在 finalizeLocalChannelOrdersInternal 分发循环(DISPATCH_BATCH_SIZE=20 批内并行)内直接处理;processApiOrderInternal 流程 ① 组装报文(缺 ownerCode → 失败)→ ② 解析 appKey → ③ sendByAppKey 发送(最多 4 次尝试)→ ④ 回调成功才调用 processLocalChannelOrderInternal 扣减库存并置 sync_status='fin';成功 N 单 = N 次回调(每单先回调、成功再扣减,不再是先扣减、后异步回调)",
"失败处理(2026-09-13):回调失败/异常、报文组装失败、appKey 解析失败统一走 markApiSyncFailedInternal(sync_status='error' + markPendingException,写库失败仅记录 error 日志),不扣减库存、不置 fin,订单可重新派发(分发前过滤只跳过 fin)。失败文案:OpenAPI 回调确认失败: {error}(如「OpenAPI 回调确认失败: 回调返回非 2xx 状态码: 400」,附 callback_retry_count)/ OpenAPI 回调确认异常: ... / 发货单缺少奇门货主编码 / 发货单缺少货主 store_id,无法解析回传用 appKey / 货主未配置可用的 OpenAPI 回调(wms_api_app 启用且 callback_url 非空)"
]
},
{
"method": "stockout.confirm",
"description": "出库单确认完成出站回调。出库单确认(API 来源,source_type=API)后,WMS 向外部回传出库确认信息(对应奇门 taobao.qimen.stockout.confirm)。触发实现:app/service/systems/order_async.js#notifyStockoutExternalInternal 的 API 分支(event=stockout.confirm);request 即 buildStockoutConfirmDataInternal 的返回结构 { deliveryOrder, packages, orderLines },与奇门请求体同层级。",
"isNeedAuth": true,
"isNeedLogin": false,
"headers": [],
"params": [
{
"name": "method",
"type": "string",
"required": true,
"source": "query",
"description": "回调 method(模块.动作,如 stockout.confirm),由 WMS 计算后发出(不是接收方入参);event 仅出现在 query 的 method,报文体不再携带 event 字段;URL 中做 encodeURIComponent"
},
{
"name": "v",
"type": "string",
"required": true,
"source": "query",
"description": "协议版本,由 WMS 发出,固定 1.0"
},
{
"name": "timestamp",
"type": "string",
"required": true,
"source": "query",
"description": "时间戳,由 WMS 发出,统一为秒级(10 位字符串,String(Math.floor(Date.now()/1000)));与 /openapi 入站时效校验(±600 秒窗口,Math.floor(Date.now()/1000))及回调调试页(nowTimestamp)口径一致,可作为规范值对外承诺"
},
{
"name": "app_key",
"type": "string",
"required": true,
"source": "query",
"description": "应用标识(api_app.self_app_key),由 WMS 发出;URL 中做 encodeURIComponent"
},
{
"name": "sign",
"type": "string",
"required": true,
"source": "query",
"description": "MD5 签名,由 WMS 计算后发出;sign = md5(canonicalQuery + selfAppSecret + md5(stableStringify(body))),小写十六进制"
},
{
"name": "request",
"type": "object",
"required": true,
"source": "body",
"description": "奇门同层级业务报文 { deliveryOrder, packages, orderLines }(即 buildStockoutConfirmDataInternal 的返回结构,不含外层 request 包装,发送端统一包装为 body = { request });口径与 callbackRegistry.js 的 request 模板一致,结构见下方 request.* 子字段"
},
{
"name": "request.deliveryOrder",
"type": "object",
"required": true,
"source": "body",
"description": "出库单头信息"
},
{
"name": "request.deliveryOrder.totalOrderLines",
"type": "number",
"required": true,
"source": "body",
"description": "明细行数(wms_order_stockout.total_order_lines 或 orderLines.length)"
},
{
"name": "request.deliveryOrder.deliveryOrderCode",
"type": "string",
"required": true,
"source": "body",
"description": "出库单号(wms_order_stockout.stockout_order_code)"
},
{
"name": "request.deliveryOrder.deliveryOrderId",
"type": "number",
"required": true,
"source": "body",
"description": "出库单 ID(wms_order_stockout.id)"
},
{
"name": "request.deliveryOrder.warehouseCode",
"type": "string",
"required": true,
"source": "body",
"description": "奇门仓库编码(wms_order_stockout.qimen_warehouse_code)"
},
{
"name": "request.deliveryOrder.orderType",
"type": "string",
"required": true,
"source": "body",
"description": "单据类型(如 PTCK)"
},
{
"name": "request.deliveryOrder.status",
"type": "string",
"required": true,
"source": "body",
"description": "固定 DELIVERED"
},
{
"name": "request.deliveryOrder.outBizCode",
"type": "string",
"required": true,
"source": "body",
"description": "外部业务编码,同出库单号"
},
{
"name": "request.deliveryOrder.confirmType",
"type": "number",
"required": true,
"source": "body",
"description": "固定 0(最终确认)"
},
{
"name": "request.deliveryOrder.orderConfirmTime",
"type": "string",
"required": true,
"source": "body",
"description": "确认时间(app.formatDate(new Date()))"
},
{
"name": "request.deliveryOrder.operatorCode",
"type": "string",
"required": true,
"source": "body",
"description": "操作员编码,固定空字符串"
},
{
"name": "request.deliveryOrder.operatorName",
"type": "string",
"required": true,
"source": "body",
"description": "操作员名称,固定空字符串"
},
{
"name": "request.packages",
"type": "object",
"required": true,
"source": "body",
"description": "包裹信息对象 { package: [...] }"
},
{
"name": "request.packages.package",
"type": "array",
"required": true,
"source": "body",
"description": "包裹数组(每个运单号一条;STOCKOUT 渠道运单号只认 wms_order_express 表)"
},
{
"name": "request.packages.package[].logisticsCode",
"type": "string",
"required": true,
"source": "body",
"description": "物流公司编码(订单 sys_logistics_code → logistics_code → 出库单 express_code,缺省 OTHER)"
},
{
"name": "request.packages.package[].logisticsName",
"type": "string",
"required": true,
"source": "body",
"description": "物流公司名称(订单 sys_logistics_name → logistics_name → 出库单 express_name,缺省 OTHER)"
},
{
"name": "request.packages.package[].expressCode",
"type": "string",
"required": true,
"source": "body",
"description": "运单号(wms_order_express 表)"
},
{
"name": "request.packages.package[].packageCode",
"type": "string",
"required": true,
"source": "body",
"description": "包裹编码(package_code 缺省同出库单号)"
},
{
"name": "request.packages.package[].items",
"type": "array",
"required": true,
"source": "body",
"description": "包裹内商品行:[ { itemCode, itemId, quantity } ]"
},
{
"name": "request.packages.package[].items[].itemCode",
"type": "string",
"required": true,
"source": "body",
"description": "商品编码"
},
{
"name": "request.packages.package[].items[].itemId",
"type": "string",
"required": true,
"source": "body",
"description": "商品 ID"
},
{
"name": "request.packages.package[].items[].quantity",
"type": "number",
"required": true,
"source": "body",
"description": "数量(actualQty)"
},
{
"name": "request.orderLines",
"type": "array",
"required": true,
"source": "body",
"description": "出库明细行数组:[ { orderLineNo, ownerCode, itemCode, itemId, itemName, planQty, actualQty, inventoryType } ]"
},
{
"name": "request.orderLines[].orderLineNo",
"type": "string",
"required": true,
"source": "body",
"description": "行号(字符串)"
},
{
"name": "request.orderLines[].ownerCode",
"type": "string",
"required": true,
"source": "body",
"description": "货主编码(item.owner_code 或出库单 qimen_owner_code)"
},
{
"name": "request.orderLines[].itemCode",
"type": "string",
"required": true,
"source": "body",
"description": "商品编码"
},
{
"name": "request.orderLines[].itemId",
"type": "string",
"required": true,
"source": "body",
"description": "商品 ID"
},
{
"name": "request.orderLines[].itemName",
"type": "string",
"required": true,
"source": "body",
"description": "商品名称"
},
{
"name": "request.orderLines[].planQty",
"type": "number",
"required": true,
"source": "body",
"description": "计划数量"
},
{
"name": "request.orderLines[].actualQty",
"type": "number",
"required": true,
"source": "body",
"description": "实际数量(缺省同 planQty)"
},
{
"name": "request.orderLines[].inventoryType",
"type": "string",
"required": true,
"source": "body",
"description": "库存类型,缺省 ZP"
}
],
"response": [
{
"name": "http_status",
"type": "number",
"required": true,
"description": "接收方应返回任意 2xx 状态码(200 ≤ status < 300,如 200/201/204);WMS 仅按 HTTP 状态码判定成功,响应体内容不参与判定"
},
{
"name": "response_body",
"type": "object",
"required": false,
"description": "响应体无约定格式;WMS 不校验业务码,返回 2xx 即视为成功,非 2xx 或网络错误进入重试(至多 3 次,间隔 2s→5s→15s)"
}
],
"errors": [
{
"code": 400,
"message": "接收方返回 400(如参数/验签不通过):WMS 视为回调失败,进入重试,至多 3 次(间隔 2s→5s→15s),全部失败后判定最终失败"
},
{
"code": 401,
"message": "接收方返回 401(鉴权失败):处理同 400,重试至多 3 次后判定最终失败"
},
{
"code": 403,
"message": "接收方返回 403(拒绝访问):处理同 400,重试至多 3 次后判定最终失败"
},
{
"code": "5xx",
"message": "接收方返回 5xx(服务端错误):处理同 400,重试至多 3 次后判定最终失败"
},
{
"code": "NETWORK_ERROR",
"message": "网络错误或单次请求超时(30s):处理同非 2xx,重试至多 3 次后判定最终失败"
}
],
"notes": [
"本文件描述出站方向(WMS → 外部)回调;入站接口请参阅 methods/openapi.json",
"签名算法:sign = md5(canonicalQuery + selfAppSecret + md5(stableStringify(body))),小写十六进制;canonicalQuery 为 query 中除 sign/signature 外、值非 undefined 的参数按 key 升序拼成的 key=value&… 串(值为原始字符串,不 URL 编码),selfAppSecret 为 api_app.self_app_secret",
"重试策略:非 2xx 响应或网络错误触发重试,至多重试 3 次(即最多 4 次尝试),间隔 2s→5s→15s,单次请求超时 30s;全部失败后判定回调失败",
"报文体统一为奇门同层级的 { request: {...} }(发送端统一包装 body = { request: request || {} }),event 仅出现在 query 的 method",
"事件注册表:app/service/openapi/callbackRegistry.js#CALLBACK_EVENTS;调试页:GET /docs/api/openapi/callback-test(app/controller/openapiCallback.js 按注册表自动预填完整报文体 { request: {...} },可编辑后发送)",
"发送途径:sendByAppKey(按 app_key 查 ApiApp,is_enabled=1,取 self_app_secret 与 callback_url)",
"仅 API 来源(source_type=API)出库单回传;QM 来源走奇门 taobao.qimen.stockout.confirm"
]
},
{
"method": "deliveryorder.cancel",
"description": "订单取消出站回调(出站事件名 deliveryorder.cancel,与 /openapi 入站方法 order.cancel 区分,避免 callback_url 误指向 WMS /openapi 时被路由到真正的取消单据接口;不做兼容、不双发)。订单取消成功后,WMS 向外部回传取消结果(fire-and-forget,不阻塞主流程)。触发实现:app/service/openapiMethods/order.js#cancel(event=deliveryorder.cancel)。无奇门对应接口,按 deliveryOrder 节点约定自定义报文。",
"isNeedAuth": true,
"isNeedLogin": false,
"headers": [],
"params": [
{
"name": "method",
"type": "string",
"required": true,
"source": "query",
"description": "回调 method(模块.动作,如 deliveryorder.cancel),由 WMS 计算后发出(不是接收方入参);event 仅出现在 query 的 method,报文体不再携带 event 字段;URL 中做 encodeURIComponent"
},
{
"name": "v",
"type": "string",
"required": true,
"source": "query",
"description": "协议版本,由 WMS 发出,固定 1.0"
},
{
"name": "timestamp",
"type": "string",
"required": true,
"source": "query",
"description": "时间戳,由 WMS 发出,统一为秒级(10 位字符串,String(Math.floor(Date.now()/1000)));与 /openapi 入站时效校验(±600 秒窗口,Math.floor(Date.now()/1000))及回调调试页(nowTimestamp)口径一致,可作为规范值对外承诺"
},
{
"name": "app_key",
"type": "string",
"required": true,
"source": "query",
"description": "应用标识(api_app.self_app_key),由 WMS 发出;URL 中做 encodeURIComponent"
},
{
"name": "sign",
"type": "string",
"required": true,
"source": "query",
"description": "MD5 签名,由 WMS 计算后发出;sign = md5(canonicalQuery + selfAppSecret + md5(stableStringify(body))),小写十六进制"
},
{
"name": "request",
"type": "object",
"required": true,
"source": "body",
"description": "奇门同层级业务报文 { deliveryOrder }(不含外层 request 包装,发送端统一包装为 body = { request });口径与 callbackRegistry.js 的 request 模板一致,结构见下方 request.* 子字段"
},
{
"name": "request.deliveryOrder",
"type": "object",
"required": true,
"source": "body",
"description": "被取消订单信息(自定义约定,无奇门对应接口)"
},
{
"name": "request.deliveryOrder.deliveryOrderCode",
"type": "string",
"required": true,
"source": "body",
"description": "被取消的订单编码(normalizedOrderCode)"
},
{
"name": "request.deliveryOrder.orderType",
"type": "string",
"required": true,
"source": "body",
"description": "单据类型,取 body.orderType 大写归一化结果(String(body.orderType || 'JYCK').trim().toUpperCase())"
},
{
"name": "request.deliveryOrder.status",
"type": "string",
"required": true,
"source": "body",
"description": "固定 CANCELED(自定义约定值;无奇门对应接口,风格与奇门 deliveryOrder.status 家族枚举一致)"
}
],
"response": [
{
"name": "http_status",
"type": "number",
"required": true,
"description": "接收方应返回任意 2xx 状态码(200 ≤ status < 300,如 200/201/204);WMS 仅按 HTTP 状态码判定成功,响应体内容不参与判定"
},
{
"name": "response_body",
"type": "object",
"required": false,
"description": "响应体无约定格式;WMS 不校验业务码,返回 2xx 即视为成功,非 2xx 或网络错误进入重试(至多 3 次,间隔 2s→5s→15s)"
}
],
"errors": [
{
"code": 400,
"message": "接收方返回 400(如参数/验签不通过):WMS 视为回调失败,进入重试,至多 3 次(间隔 2s→5s→15s),全部失败后判定最终失败"
},
{
"code": 401,
"message": "接收方返回 401(鉴权失败):处理同 400,重试至多 3 次后判定最终失败"
},
{
"code": 403,
"message": "接收方返回 403(拒绝访问):处理同 400,重试至多 3 次后判定最终失败"
},
{
"code": "5xx",
"message": "接收方返回 5xx(服务端错误):处理同 400,重试至多 3 次后判定最终失败"
},
{
"code": "NETWORK_ERROR",
"message": "网络错误或单次请求超时(30s):处理同非 2xx,重试至多 3 次后判定最终失败"
}
],
"notes": [
"本文件描述出站方向(WMS → 外部)回调;入站接口请参阅 methods/openapi.json",
"签名算法:sign = md5(canonicalQuery + selfAppSecret + md5(stableStringify(body))),小写十六进制;canonicalQuery 为 query 中除 sign/signature 外、值非 undefined 的参数按 key 升序拼成的 key=value&… 串(值为原始字符串,不 URL 编码),selfAppSecret 为 api_app.self_app_secret",
"重试策略:非 2xx 响应或网络错误触发重试,至多重试 3 次(即最多 4 次尝试),间隔 2s→5s→15s,单次请求超时 30s;全部失败后判定回调失败",
"报文体统一为奇门同层级的 { request: {...} }(发送端统一包装 body = { request: request || {} }),event 仅出现在 query 的 method",
"事件注册表:app/service/openapi/callbackRegistry.js#CALLBACK_EVENTS;调试页:GET /docs/api/openapi/callback-test(app/controller/openapiCallback.js 按注册表自动预填完整报文体 { request: {...} },可编辑后发送)",
"发送途径:sendByAppKey(按 app_key 查 ApiApp,is_enabled=1,取 self_app_secret 与 callback_url)",
"fire-and-forget 触发:回调结果不影响订单取消主流程",
"改名说明:出站回调事件名由 order.cancel 改为 deliveryorder.cancel(不做兼容、不双发),与 /openapi 入站方法 order.cancel(取消单据接口)区分,避免 callback_url 误指向 /openapi 时被路由到取消单据接口"
]
}
]
}
]
}
}