- 背景:order_storage_allocation 构造的 routeContext 不含 appKey, finalizeLocalChannelOrdersInternal 的 if(appKey) 门禁导致 API 同步链路的 deliveryorder.confirm 从未真正发出;订单表 from_key 也兜不住 (normalizeOrderFromKey 仅接受整数,字符串 app_key 被归一化为 null) - order_async.js 新增 resolveOpenApiAppByStoreInternal:口径与入库单 _sendOpenApiCallback 对齐(wms_store_warehouse auth_status=2 → wms_api_app is_enabled=1 且 callback_url 非空) - notifyApiDeliveryOrderConfirmsInternal 逐单解析 appKey:context.appKey 非空优先 (不触发反查),缺失时按 orderRow.store_id 反查并按货主缓存(同批次无 N+1); 解析不到 appKey 的订单 warn 后跳过、不发请求 - 补充回调成功 info 日志(含 appKey) - 文档:methods/openapi_callback.json 1.2.0 → 1.3.0、变更记录 methods/changes/openapi_callback.json、docs/openapi-callback-events.md、 AI_METHOD_ROUTING.md 同步 - test: order_async.openapi.callback.test.js 覆盖 context.appKey 为空时反查发送
1331 lines
63 KiB
JSON
1331 lines
63 KiB
JSON
{
|
||
"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.3.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 且本批存在同步成功订单(仅对 syncResults 中 status==='success' 的订单发送,成功 N 单 = N 次回调;fire-and-forget,失败仅 warn,不阻塞主流程)。发送用 appKey 优先取调用上下文 context.appKey,缺失时按订单货主(store_id + warehouse_id)合约反查 —— wms_store_warehouse(auth_status=2) → wms_api_app(is_enabled=1 且 callback_url 非空) 的 self_app_key;同一批次按货主缓存,无 N+1。解析不到 appKey(订单缺 store_id / 无授权关系 / 无可用 ApiApp 配置)时跳过该订单并告警,不发送请求;同步失败的订单不发送。触发实现:app/service/systems/order_async.js#finalizeLocalChannelOrdersInternal → notifyApiDeliveryOrderConfirmsInternal(复用 buildQimenDeliveryOrderConfirmDataInternal 组装与奇门 taobao.qimen.deliveryorder.confirm 完全一致的 request 报文;复用原有主表+明细查询,新增 1 次运单号批量查询,无 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),全部失败后判定最终失败"
|
||
},
|
||
{
|
||
"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;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 配置)的订单 warn 后跳过,不发请求",
|
||
"逐单发送语义(破坏性变更):改动前一次回调携带整批 orderIds(含失败/跳过);改后仅对 syncResults 中 status==='success' 的订单逐单发送,成功 N 单 = N 次回调;组装/发送失败仅 warn,不影响其他订单与主流程",
|
||
"fire-and-forget 触发:回调结果不影响订单同步主流程"
|
||
]
|
||
},
|
||
{
|
||
"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 时被路由到取消单据接口"
|
||
]
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|