{ "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 时被路由到取消单据接口" ] } ] } ] } }