奇门白皮书.docx

奇门白皮书.docx

《奇门白皮书.docx》由会员分享，可在线阅读，更多相关《奇门白皮书.docx（128页珍藏版）》请在冰豆网上搜索。

奇门白皮书

奇门标准化协议白皮书

V2.4

阿里巴巴集团商家业务事业部

2015

1版本记录

Date

Version

Description

2015.03.27

1.0

1、奇门标准化协议v1.0发布

2015.03.31

1.2

1、增加入库单更新，出库单更新，库存异动更新等3个接口

2、API名称区分了erp和wms

3、优化部分字段命名

2015.04.07

1.3

1、将auditor相关的字段统一成operator

2015.04.09

1.4

1、更新接口规范，新增“奇门与wms的通信协议”等相关内容

2、新增入库单，去掉一个重复的入库单编码

2015.04.14

1.5

1、加入奇门项目服务商解决方案章节

2、增加通信协议里的反向协议标准

3、更新个别字段名，如Quantity更新为Qty，stockSelectedQty等字段名中将stock去掉，变为selectedQty。

2015.5.6

2.0

1、加入菜鸟仓业务接口支持

2、接口整体改动较大，主要增加业务接口和原有接口内增加字段

2015.5.7

2.1

1、出入库单据增加ERP行号的概念

2、出库单流水接口升级为订单流水接口

3、仓内加工单更名为storeprocess

4、发货单确认接口的生产日期produceDate变更为productDate

5、退货入库单创建接口orderLine节点中增加ownerCode字段；入库单创建接口中ownerCode移到orderLine节点中

2015.5.20

2.1

1、取消订单，订单类型变为非必填

2、发货单创建，付款时间变为非必填

3、所有地址中的区域改为非必填

4、退货入库单确认接口，物流公司编码改为非必填

2015.6.5

2.2

1、增加“出库单创建”，“出库单确认”接口

2015.6.10

2.2

1、“出库单创建”增加货主编码字段

2、增加“订单状态查询”和“库存查询”两个接口

3、规范“冻结库存”的使用范围

2015.6.11

2.2

1、增加“组合商品接口”

2、入库单的收件人，发件人，物流公司信息为非必填

3、新增入库单类型：

生产入库、领用入库、残次品入库。

4、入库单新增字段，采购单号

5、盘点单新增字段，盘点时间

6、新增“库存异动接口”

7、“订单状态查询”不仅查当前状态，历史状态也可以

8、“普通出库单”增加发件人信息

2015.6.12

2.2

1、“组合商品创建接口”和“订单流水查询接口“，去掉warehouseCode编码

2、“订单流水查询接口”和“库存查询接口”response增加的flag，code，message这三个标准的应答。

2015.6.25

2.2

1、增加发货单查询接口

2015.7.2

2.2

1、订单状态查询增加两个入库状态（PARTFULFILLED-部分收货完成,FULFILLED-收货完成。

）

2、库存查询接口增加货主编码ownerCode

2015.7.3

2.2

1、退货入库创建接口：

商品增加批次等信息

2、发货单创建接口，发票增加普通发票的类型

3、订单流水查询接口，删除NEW状态

4、订单流水通知接口，删除NEW，CANCELEDFAIL状态

5、发货单创建和发货单缺货通知接口，在item节点下增加inventoryType等字段

2015.7.6

2.2

1、商品同步接口的barcode可以填多个

2、发货单创建增加字段“deliveryType”

3、发货单创建返回值支持统仓统配的拆单

4、发票内容格式化

5、增加B2B出库的出库类型

6、入库单确认接口的entryOrderId改为条件必填

7、extendProps和remark统一定义了

8、退货单创建和确认接口增加批次信息

9、订单流水查询删除CANCELFAILED状态

10、订单流水通知接口删除NEW,CANCELFAILED状态

11、发货单缺货通知接口item节点下增加inventoryType和批次信息

2015.7.9

2.2

1、B2B入库和B2B出库单据状态多接口修订

2、发货单SN通知借口，加上分页，并且将sns的节点去掉

2015.7.14

2.2

1、增加库存异动接口，单据类型增加ZZTZ=状态调整单

2015.7.16

2.2

1、发货单invoices下面的detail增加item节点

2、发货单发货类型的枚举值CWPS（常温配送）改为PTPS（普通配送）

3、商品同步barcode的分隔符改为；

4、部分warehouseCode重新定义约束和说明

5、库存异动接口更名为库存异动通知接口

2015.7.17

2.2

1、发货单创建的出参，response节点下增加warehouseCode和logisticsCode两个字段，以适配以前的版本

2015.7.20

2.2

1、库存异动接口，结构体变化，将warehouseCode，ownerCode，orderCode，orderType，outbizCode等放到item节点下

2015.7.21

2.2

1、快递编码中增加京东配送（JD），当当宅配（DD）

2015.7.22

2.2

1、出库单创建和出库单确认接口增加logisticsCode字段

2015.7.23

2.2

1、入库单创建、入库单确认、出库单创建、出库单确认等四个接口增加totalOrderLines，outBizCode这两个字段用于分批传输处理

2015.7.30

2.2

1、发货单确认接口增加“包裹理论重量”

2015.8.14

2.2

1、新增接口订单状态查询接口（批量），用于解决通过订单最后操作时间的区间值等信息，去批量查询订单

2、发货单创建接口的orderLine下面增加batchCode等字段，用于解决指定批次发货的问题

2015.8.20

2.2

1、发货单创建接口的orderLine下面增加productDate,expireDate等字段

2、渠道枚举字段调整，凡客由FK调整为VANCL

2015/8/31

2.3

1、新增5个接口，支持用于各种订单在仓内操作结果的详情查询，包括入库单查询，出库单查询，退货入库单查询，发货单查询，发货单缺货查询。

2、订单流水查询和订单流水确认接口的status，增加两个状态，PARTFULFILLED，FULFILLED两个状态。

3、入库单确认接口，出库单确认接口，增加单据状态字段status。

2015/9/6

2.3

1、发货单确认接口，单价和数量字段类型修正

2、所有正向接口，均补充warehouseCode，作为可能的一单分多仓的业务场景。

2015/9/7

2.3

1、新增接口，为菜鸟自动流转的业务新增的特殊业务接口。

2015/9/14

2.3

1、新增盘点单查询接口

2、盘点单确认接口和盘点单查询接口均增加checkOrderId

3、发货单查询接口，为了兼容，入参将deliveryOrderCode改为orderCode,deliveryOrderId改为orderId

2015/9/21

2.3

入库单确认，出库单确认，退货入库单确认，发货单确认，库存异动通知

2015/9/22

2.3

新增心跳接口

2015/9/24

2.3

1、订单流水查询接口增加orderType

2、发货单确认接口orderType增加枚举值QTCK。

2015/10/10

2.3

1、库存盘点查询的接口名变更

2015/10/15

2.3

1、在发货单确认，发货单查询，退货入库单确认，退货入库单查询等接口的orderline中增加商品二维码，用于对单个商品的管理。

2015/10/20

2.3

1、新增商品同步接口（批量），发货单创建接口（批量），发货单确认接口（批量）

2015/10/27

2.3

1、发货单创建接口的orderline下增加payNo，用于解决合单后的支付宝交易号的传输。

2015/11/19

2.3

1、出库单类型新增采购退货出库类型（CGTH）

2015/11/23

2.3

1、发货单创建接口，出参response下增加createTime。

2015/11/25

2.4

新增4个接口，主要用来注册奇门的仓库编码，奇门的用户号，包括奇门仓库注册接口，奇门仓库查询接口，奇门仓库更新接口，奇门用户注册接口

2015/12/3

2.4

1、新增店铺同步接口

2015/12/8

2.4

1、新增库存查询接口（多条件）

2015/12/21

2.4

1、新增挂起（恢复）接口

2、取消和挂起接口的订单类型增加THRK=退货入库

2015/12/28

2.4

1、组合商品增加itemId字段

2015/12/30

2.4

1、出库单确认接口，orderline节点下增加货主编码这个字段

2、单据取消接口，单据类型增加采购退货出库

2015/12/31

2.4

1、商品同步接口，商品同步接口（批量）新增字段goodsCode

2前言

业务背景

随着电子商务发展，商家所使用到的各类软件越来越多，各个软件之间没有相互打通，形成一个个信息孤岛，给商家的使用带来种种不便，商家要求各个系统之间的对接需求已经越来越迫切；

目前在行业内已经有部分系统直接由服务商之间完成了系统软件的对接，但是由于没有统一的接入标准，导致接入较混乱，对接接口的版本也参差不齐，往往这样的系统对接不具有可复制性，多个系统之间的对接，需要多次开发，给商家的使用和功能迭代升级带来了诸多的不便，同时也给服务商带来额外的维护、开发成本；为了满足商家需求，让商家能够突破各个业务系统之间的信息孤岛，提升商家在各个系统之间的操作效率，解决各个系统之间标准化对接的痛点，我们推出了奇门项目；

奇门项目一期支持ERP、WMS之间的系统标准化对接，通过构建ERP、WMS系统之间标准通信协议来实现不同系统之间的打通；对商家来说，省去了更换系统软件所带来的额外开发成本；对ISV来说，省去了与多家ERP、WMS系统对接难的问题，ERP通过一次对接奇门项目，打通与所有WMS之间的通信，WMS通过一次对接奇门项目，可以适配所有ERP软件；后期我们也将加入更多系统的支持，例如CRM与ERP的标准化对接，CRM与在线订购类营销工具的标准化对接；敬请期待！

名词解释

序号

名词

解释

1

奇门项目

阿里巴巴商家业务系统标准化对接平台

2

OMS

OrderManagementSystem订单管理系统

3

TMS

TransportationManagementSystem物流管理系统

4

WMS

WarehouseManagementSystem仓库管理系统

5

ERP

ERP EnterpriseResourcePlanning企业资源计划

6

正向调用

由ERP发起调用到奇门，奇门处理后将请求转发至WMS端

7

反向调用

由WMS发起调用到奇门，奇门处理后将请求转发至ERP端

3奇门对接方案

奇门对接方式

目前商家使用的各个业务系统之间依靠ISV帮助实现ERP到WMS的对接，如果有多仓需求的商家还需要使用到2套以上的第三方仓储服务所提供的WMS软件，ERP、WMS各自对接，对接的总工作量为N*N倍，不但给ISV的开发带来了极大的成本，对于后期维护，也将是一项艰巨的任务，如下图所示：

通过奇门项目后可使原有的网状对接结构变为一对一的对接方式，ERP、WMS只需要与奇门数据总线对接一次即可完成所有系统的适配（特殊场景可能采用扩展字段的方式给与支持），如下图：

奇门项目后继接口升级方式将采用字段升级方式，在原有基础上加入更多的业务字段，同时业务接口向下兼容，开发过一次，后继如需更多的业务字段只需在原有接口层面加入业务字段即可，无需重新开发业务逻辑；

奇门标准化对接构架

前端ERP系统通过TOP平台与奇门应用进行对接，ERP系统通过标准化通信协议、字段访问奇门系统，ERP在此需要进行改造；

奇门应用主要提供字段映射、数据翻译、数据路由、账号权限、流控、数据打点等功能，能够让双方的请求通过奇门进行正常的传输，奇门还提供商家自定义扩展字段，通过奇门项目的通用数据通道进行传输，在标准协议不能完全支持的情况下，可以采用扩展字段的方式进行补充；

后端WMS系统通过TOP平台与奇门应用进行对接，WMS系统通过标准化通信协议、字段调用奇门系统，WMS在此也需要进行改造；

（可选）WMS系统需要提供出能够在系统中新建用户、查询用户的API，以供奇门项目应用调用，新商家接入时，奇门项目可以直接调用该API创建新的用户；

系统调用流程

正向调用：

前端ERP系统通过TOP接口与奇门项目应用进行交互，对于想要发送到WMS的请求首先发送到奇门应用，由奇门负责数据的解析、字段映射、数据翻译，再将处理后的数据通过ERP系统所请求的目的地发送至WMS系统；WMS系统收到请求后，将返回结果送回至奇门应用，由奇门应用统一返回至ERP系统；

反向调用：

WMS系统主动向ERP系统发出状态更新请求也是类似以上的访问步骤；

以下是简版软件流程图：

联调、测试方式

奇门项目支持ERP系统的正向调用以及WMS系统的反向调用，所以对于ERP系统以及WMS系统的测试方法并不一致，以下分别介绍ERP系统以及WMS系统的联调、测试方法：

3.1.1ERP端

配置信息确认阶段：

提前与WMS厂商进行沟通，根据商家的在WMS端的用户信息获取以下配置信息，并提供给奇门项目组，由奇门项目组完成在奇门当中的配置：

奇门标准字段

字段含义

备注

测试环境配置值

appkey

appkey

由开放平台分配，对应ERP软件的编码

customerid

用户id

访问WMS系统的账号

secretkey

用户密码

该账号访问WMS系统的密码

开发接口阶段：

奇门项目当中ERP端支持正向调用也支持反向调用，正向调用的API接口由TOP平台提供，ERP端直接发起对沙箱环境的调用即可完成接口的测试工作，沙箱环境调用地址如下（只需修改红色标示的method方法字段和test_type字段，test_type值可以取normal和error，normal会返回该请求成功的应答，error会返回该请求失败的应答）：

反向调用的API接口由ERP端提供，奇门会直接向ERP端发起调用，在此类型的API接口测试的过程当中，需要由服务商使用一个HttpRestful接口的客户端向奇门发起反向调用；（推荐使用Chrome浏览器下的RESTConsole插件）

系统联调阶段：

依次完成正向请求的开发与反向接口的工作后，与奇门项目组共同进行联调，在测试环境当中依次测试之前开发接口的业务逻辑；

系统发布阶段：

与WMS端服务商共同确认正式环境的配置值，ERP端直接发起对奇门正式环境的调用，需要将原有访问地址与具体配置地址切换成正式环境地址。

3.1.2WMS端

配置信息确认阶段：

WMS厂商需提前提供商家的在WMS端的用户信息以及如下的配置信息，提供给奇门项目组以及ERP端进行配置：

奇门标准字段

字段含义

备注

测试环境配置值

warehouseCode

仓库id

仓储服务商分配给商家的仓库编码

customerid

用户id

访问WMS系统的账号

开发接口阶段：

奇门项目当中WMS端支持正向调用也支持反向调用，反向调用的API接口由TOP平台提供，WMS端直接发起对沙箱环境的调用即可完成接口的测试工作，沙箱环境调用地址如下（只需修改红色标示的method方法字段和test_type字段，test_type值可以取normal和error，normal会返回该请求成功的应答，error会返回该请求失败的应答）：

method=taobao.qimen.itemlack.report×tamp=2015-04-26%2000:

00:

07&format=xml&test_type=normal&app_key=【奇门沙箱Appkey】&v=1.0&sign=abc&sign_method=md5&customerId=【奇门分配】&uid=123456789

正向调用的API接口由WMS端提供，奇门会直接向WMS端发起调用，在此类型的API接口测试的过程当中，需要由服务商使用一个HttpRestful接口的客户端向奇门发起正向调用；（推荐使用Chrome浏览器下的RESTConsole插件）

系统联调阶段：

依次完成正向请求的开发与反向接口的工作后，与奇门项目组共同进行联调，在测试环境当中依次测试之前开发接口的业务逻辑；

系统发布阶段：

WMS服务商与奇门共同确认正式环境的配置值，WMS端直接发起对奇门正式环境的调用，需要将原有访问地址与具体配置地址切换成正式环境地址。

4接口规范

ERP与奇门的通信协议

4.1.1协议描述

接口遵循REST规范，使用HTTPPOST方式进行通讯。

标准协议的HTTP入口地址为：

ERP发给奇门：

00:

00:

00]&format=xml&app_key=[erp_appkey]&v=1.0&sign=[xxxxxxxxxxxxxxxxxxxxxx]&sign_method=md5&customerId=[QIMENUSR1]

奇门发给ERP：

http:

//[erp_webservice_url]?

method=[erp_API]×tamp=[2015-02-0100:

00:

00]&format=xml&app_key=[wms_appkey]&v=1.0&sign=[xxxxxxxxxxxxxxxxxxxxxx]&sign_method=md5&customerId=[QIMENUSR1]

注：

1.[]中需要根据具体业务进行填写。

qimen_API，erp_API具体见下方的API名称。

2.URL需要做URLEncoding处理。

3.请求和响应的消息主体使用XML格式。

4.1.2访问授权

需要商家提供TOP的sessionkey（session）以及该商家在对应wms系统的客户ID（customerID）和密钥（用于计算sign）。

4.1.3请求参数说明

请求参数包含URL中带的系统参数和BODY中带的相关业务参数，系统参数如下：

参数

参数说明

类型

约束

session

session，TOP颁发给商家的

string

method

ERP相关的业务接口名称，如商品信息同步的请求，method=taobao.qimen.item.synchronize

string

必须

timestamp

时间戳，格式为yyyy-mm-ddHH:

mm:

ss

string

必须

format

content格式

string

目前支持XML

app_key

应用接入时申请的appkey

string

ERP的appkey

v

协议版本号，1.0或者2.0

string

必须

sign

根据url和密钥计算的结果。

具体算法参看附录1

string

必须

sign_method

参数加密方法，md5

customerid

WMS颁发给用户的ID

string

必须

4.1.4响应参数

响应参数包含系统参数和业务参数，系统参数如下：

参数

参数说明

类型

约束

flag

success|failure

string（50）

必须

code

返回状态码

string（50）

必须

message

返回状态描述

string（200）

必须

奇门与WMS的通信协议

4.1.5协议描述

接口遵循REST规范，使用HTTPPOST方式进行通讯。

标准协议的HTTP入口地址为：

奇门发给WMS：

http:

//[wms_webservice_url]?

method=[wms_API]&format=xml&app_key=[erp_appkey]&v=1.0&sign=[xxxxxxxxxxxxxxxxxxxxxx]&sign_method=md5&customerId=[QIMENUSR1]

WMS发给奇门：

×tamp=[2015-02-0100:

00:

00]&format=xml&app_key=[wms_appkey]&v=1.0&sign=[xxxxxxxxxxxxxxxxxxxxxx]&sign_method=md5&customerId=[QIMENUSR1]

注：

1.[]中需要根据具体业务进行填写。

qimen_API，wms_API具体见下方的API名称。

2.URL需要做URLEncoding处理。

3.请求和响应的消息主体使用XML格式。

4.1.6请求参数

请求参数包含URL中带的系统参数和BODY中带的相关业务参数，以下是系统参数：

参数

参数说明

类型

约束

method

WMS相关的业务接口名称，如商品信息同步的请求，method=item.synchronize

string

必须

format

content格式

string

目前支持XML

app_key

应用接入时申请的appkey

string

WMS的appkey

v

协议版本号，1.0或者2.0

string

必须

sign

根据url和密钥计算的结果。

具体算法参看附录1

string

必须

sign_method

参数加密方法，md5

customerid

WMS颁发给用户的ID

string

必须

4.1.7响应参数

响应参数包含系统参数和业务参数。

以下是系统参数：

参数

参数说明

类型

约束

flag

success|failure

string（50）

必须

code

返回状态码

string（50）

必须

message

返回状态描述