10 KiB
10 KiB
奇门接口技术备忘
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. 排障时的实用检查点
- 先确认 method 名是否与官方文档一致,尤其是 singleitem、deliveryorder、entryorder、returnorder、stockout、inventory 这些主模块
- 再确认 XML 根节点和字段名是否和官方定义一致,奇门对字段名大小写和层级通常比较敏感
- 关注 itemId 是否被误传为空,很多接口里它是条件必填
- 关注 warehouseCode 是否在统仓统配场景下正确使用 OTHER
- 批量接口要核对 totalOrderLines、currentPage、pageSize 和明细数量是否一致
- 发生返回 success 但业务未落库时,要继续检查本地实现是否只是接收成功而不是业务处理成功
8. 结论
这份奇门白皮书覆盖了 WMS 与 ERP 对接的完整主干能力,核心可以归纳为:
- 商品主数据
- 入库、退货入库、出库、发货
- SN、流水、状态、异常
- 库存、盘点、加工、异动
- 仓库、店铺、供应商、配送公司基础资料
- 调拨、波次、缺货、规则、统计与心跳
在本仓库中,奇门的本地实现已经有统一入口和方法分层,适合把本文作为日常联调与故障排查的快速备忘。