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

226 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

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

# 奇门接口技术备忘
## 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、流水、状态、异常
- 库存、盘点、加工、异动
- 仓库、店铺、供应商、配送公司基础资料
- 调拨、波次、缺货、规则、统计与心跳
在本仓库中,奇门的本地实现已经有统一入口和方法分层,适合把本文作为日常联调与故障排查的快速备忘。