WMS_MAIN/docs/qimen-interface-reference.md
2026-04-09 15:45:14 +08:00

10 KiB
Raw Blame History

奇门接口技术备忘

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、流水、状态、异常
  • 库存、盘点、加工、异动
  • 仓库、店铺、供应商、配送公司基础资料
  • 调拨、波次、缺货、规则、统计与心跳

在本仓库中,奇门的本地实现已经有统一入口和方法分层,适合把本文作为日常联调与故障排查的快速备忘。