# 奇门接口技术备忘 ## 1. 文档来源 - 官方来源:open.taobao.com 文档,docId=118403,页面章节为“5. 接口说明” - 适用对象:WMS 与 ERP 之间的奇门对接排障、接口回查、协议备忘 - 本文目标:把官方白皮书里的核心调用约定、接口地图和本地实现入口沉淀到仓库内,便于技术备用 ## 2. 接入总览 奇门接口的统一特征是: - 请求方式以 POST 为主 - query 中携带 app_key、method、v、format、sign_method、sign、timestamp 等标准参数 - body 使用 XML,根节点通常为 request - 响应也使用 XML,根节点通常为 response - 响应通常包含 flag、code、message 三个固定字段 官方白皮书中明确说明: - 很多接口是同步接口,返回 success 不只是“消息接收成功”,而是代表业务已处理完成 - 批量接口通常会在一个订单下承载多个 item 或 order 节点 - 非叶子节点通常允许增加 remark 和 extendProps ## 3. 通用字段与约定 ### 3.1 常见主键字段 - ownerCode:货主编码 - warehouseCode:仓库编码,统仓统配等场景常填 OTHER - itemCode:ERP 商品编码 - itemId:WMS 商品编码或仓储系统商品 ID,通常是条件必填 - orderCode:单据编码 - orderId:仓储系统单据编码 - outBizCode:外部业务编码,常作为幂等键 ### 3.2 常见状态枚举 订单类状态常见值: - NEW:未开始处理 - ACCEPT:仓库接单 - PRINT:打印 - PICK:拣货 - CHECK:复核 - PACKAGE:打包 - WEIGH:称重 - READY:待提货 - DELIVERED:已发货 - PARTDELIVERED:部分发货完成 - PARTFULFILLED:部分收货完成 - FULFILLED:收货完成 - EXCEPTION:异常 - CANCELED:取消 - CLOSED:关闭 - REJECT:拒单 - REFUSE:客户拒签 - SIGN:签收 库存类常见值: - ZP:正品 - CC:残次 - JS:机损 - XS:箱损 - FP:废品 - ZT:在途库存 - DJ:冻结 - OTHER:其他 ### 3.3 常见业务规则 - 组合商品、条码、批次、生产日期、过期日期、生产批号等字段在多个接口里复用 - 一些接口对 itemId 有条件必填要求,通常与仓库是否自定义 WMS 商品编码有关 - 多次收货、多次发货、多次确认类接口会使用 confirmType - 分批发送时,totalOrderLines 常用于说明总行数,接收方据此判断是否收齐 ## 4. 接口地图 以下为官方文档 5.x 章节的接口目录,按业务域整理。 ### 4.1 商品与商品映射 - 5.1 商品查询接口:taobao.qimen.singleitem.query / singleitem.query - 5.2 商品同步接口:taobao.qimen.singleitem.synchronize / singleitem.synchronize - 5.3 商品同步接口(批量):taobao.qimen.items.synchronize / items.synchronize - 5.4 组合商品接口:taobao.qimen.combineitem.synchronize / combineitem.synchronize - 5.5 创建前后端商品映射接口:taobao.qimen.itemmapping.create / itemmapping.create - 5.6 前后端商品映射查询接口:taobao.qimen.itemmapping.query / itemmapping.query ### 4.2 入库与退货入库 - 5.7 入库单创建接口:taobao.qimen.entryorder.create / entryorder.create - 5.8 入库单确认接口:taobao.qimen.entryorder.confirm / entryorder.confirm - 5.9 入库单查询接口:taobao.qimen.entryorder.query / entryorder.query - 5.10 退货入库单创建接口:taobao.qimen.returnorder.create / returnorder.create - 5.11 退货入库单确认接口:taobao.qimen.returnorder.confirm / returnorder.confirm - 5.12 退货入库单查询接口:taobao.qimen.returnorder.query / returnorder.query ### 4.3 出库、发货与确认 - 5.13 出库单创建接口:taobao.qimen.stockout.create / stockout.create - 5.14 出库单确认接口:taobao.qimen.stockout.confirm / stockout.confirm - 5.15 出库单查询接口:taobao.qimen.stockout.query / stockout.query - 5.16 发货单创建接口:taobao.qimen.deliveryorder.create / deliveryorder.create - 5.17 发货单创建接口(批量):taobao.qimen.deliveryorder.batchcreate / deliveryorder.batchcreate - 5.18 发货单创建结果通知接口(批量):taobao.qimen.deliveryorder.batchcreate.answer / deliveryorder.batchcreate.answer - 5.19 发货单确认接口:taobao.qimen.deliveryorder.confirm / deliveryorder.confirm - 5.20 发货单确认接口(批量):taobao.qimen.deliveryorder.batchconfirm / deliveryorder.batchconfirm - 5.21 发货单查询接口:taobao.qimen.deliveryorder.query / deliveryorder.query ### 4.4 SN 与订单流水 - 5.22 订单SN通知接口:taobao.qimen.order.sn.report / order.sn.report - 5.23 发货单SN通知接口:taobao.qimen.sn.report / sn.report - 5.24 订单流水查询接口:taobao.qimen.orderprocess.query / orderprocess.query - 5.25 订单状态查询接口(批量):taobao.qimen.orderstatus.batchquery / orderstatus.batchquery - 5.26 订单流水通知接口:taobao.qimen.orderprocess.report / orderprocess.report - 5.27 订单异常通知接口:taobao.qimen.orderexception.report / orderexception.report ### 4.5 异常、退货、缺货与挂起 - 5.28 退货异常包裹单通知接口:taobao.qimen.returnapply.report / returnapply.report - 5.29 退货包裹状态通知接口:taobao.qimen.returnpackage.report / returnpackage.report - 5.30 发货单缺货通知接口:taobao.qimen.itemlack.report / itemlack.report - 5.31 发货单缺货查询接口:taobao.qimen.itemlack.query / itemlack.query - 5.32 单据取消接口:taobao.qimen.order.cancel / order.cancel - 5.33 单据挂起(恢复)接口:taobao.qimen.order.pending / order.pending ### 4.6 库存、仓库、加工与异动 - 5.34 库存查询接口(多商品):taobao.qimen.inventory.query / inventory.query - 5.35 库存查询接口(多条件):taobao.qimen.stock.query / stock.query - 5.36 仓库查询接口:taobao.qimen.warehouseinfo.query / warehouseinfo.query - 5.37 仓库同步接口:taobao.qimen.warehouseinfo.synchronize / warehouseinfo.synchronize - 5.38 库存盘点通知接口:taobao.qimen.inventory.report / inventory.report - 5.39 库存盘点查询接口:taobao.qimen.inventorycheck.query / inventorycheck.query - 5.40 仓内加工单创建接口:taobao.qimen.storeprocess.create / storeprocess.create - 5.41 仓内加工单确认接口:taobao.qimen.storeprocess.confirm / storeprocess.confirm - 5.42 库存异动通知接口:taobao.qimen.stockchange.report / stockchange.report ### 4.7 店铺、波次、调拨、规则与统计 - 5.43 店铺同步接口:taobao.qimen.shop.synchronize / shop.synchronize - 5.44 发货单波次通知接口:taobao.qimen.wavenum.report / wavenum.report - 5.45 调拨单创建接口:taobao.qimen.transferorder.create / transferorder.create - 5.46 调拨单查询接口:taobao.qimen.transferorder.query / transferorder.query - 5.47 调拨单通知接口:taobao.qimen.transferorder.report / transferorder.report - 5.48 渠道间库存规则设置接口:taobao.qimen.inventoryrule.create / inventoryrule.create - 5.49 库存汇总报表查询接口:taobao.qimen.inventorysum.query / inventorysum.query - 5.50 订单出库统计查询接口:taobao.qimen.deliveryordersum.query / deliveryordersum.query ### 4.8 基础能力 - 5.51 心跳接口:taobao.qimen.service.heartbeat / service.heartbeat - 5.52 供应商信息同步接口:taobao.qimen.supplier.synchronize / supplier.synchronize - 5.53 配送公司信息查询:taobao.qimen.expressinfo.query / expressinfo.query ## 5. 官方白皮书里的关键细节 ### 5.1 商品接口 - 单品查询与单品同步字段高度一致,itemCode、itemName、barCode、itemType、brand、重量、尺寸、批次、保质期相关字段都会复用 - 批量商品同步使用 items 节点包裹 item 列表 - 组合商品接口的核心是 itemCode、ownerCode、warehouseCode 与子商品清单 ### 5.2 入库与退货入库 - entryorder.create 与 returnorder.create 都是同步创建 - confirm 接口用于最终状态回告,不只是接收消息 - 订单行内常包含 itemCode、itemId、planQty、actualQty、inventoryType、batchCode、productDate、expireDate、produceCode - 入库场景支持 relatedOrders 关联单据信息 ### 5.3 出库与发货 - stockout 更偏普通出库,不强调订单履约语义 - deliveryorder 更偏订单驱动发货 - 批量版 create/confirm 接口支持 orders 与 order 节点 - 发货单确认会带包裹、发票、物流、重量、体积、SN、批次等信息 ### 5.4 库存与盘点 - inventory.query 与 stock.query 都是库存查询,但入参组织方式不同 - inventory.report 与 inventorycheck.query 用于盘点回传和盘点查询 - stockchange.report 用于把引起库存变动的单据和库存变化同步给 ERP ### 5.5 组织与基础资料 - warehouseinfo.query / synchronize 处理仓库基础资料 - shop.synchronize 处理店铺基础资料 - supplier.synchronize 处理供应商基础资料 - expressinfo.query 处理配送公司信息 ## 6. 本地实现落点 当前仓库里与奇门相关的本地实现入口主要是: - app/service/qimen.js:统一 XML 解析、method 路由与 XML 响应封装 - app/service/qimenMethods/:具体奇门业务方法实现目录 - typings/app/service/index.d.ts:qimenMethods 的类型入口 - methods/qimen.json:当前奇门方法定义与参数结构的主索引 - methods/changes/qimen.json:奇门文档变更记录副本 从代码层看,qimen.js 会先解析 XML,再根据 method 对应到 qimenMethods 下的具体模块调用。 ## 7. 排障时的实用检查点 1. 先确认 method 名是否与官方文档一致,尤其是 singleitem、deliveryorder、entryorder、returnorder、stockout、inventory 这些主模块 2. 再确认 XML 根节点和字段名是否和官方定义一致,奇门对字段名大小写和层级通常比较敏感 3. 关注 itemId 是否被误传为空,很多接口里它是条件必填 4. 关注 warehouseCode 是否在统仓统配场景下正确使用 OTHER 5. 批量接口要核对 totalOrderLines、currentPage、pageSize 和明细数量是否一致 6. 发生返回 success 但业务未落库时,要继续检查本地实现是否只是接收成功而不是业务处理成功 ## 8. 结论 这份奇门白皮书覆盖了 WMS 与 ERP 对接的完整主干能力,核心可以归纳为: - 商品主数据 - 入库、退货入库、出库、发货 - SN、流水、状态、异常 - 库存、盘点、加工、异动 - 仓库、店铺、供应商、配送公司基础资料 - 调拨、波次、缺货、规则、统计与心跳 在本仓库中,奇门的本地实现已经有统一入口和方法分层,适合把本文作为日常联调与故障排查的快速备忘。