开发文档规范-供应链平台API标准接口文档说明书

开发文档规范

供应链平台API标准接口

规范说明书（完整版）

设计单位:

建设单位:

编制日期:

目录

第一章文档概述.......................................................7

第二章业务对接说明...................................................8

2.1.接口说明....................................................8

2.1.1.接口地址............................................8

2.1.2.接口参数............................................8

2.2.接口清单....................................................9

第三章标准API.............................................................................................................10

3.1.货品档案同步...............................................10

3.1.1.功能说明............................................10

3.1.2.应用入参说明.......................................11

3.1.3.数据格式...........................................12

3.1.4.报文格式...........................................14

3.1.5.响应格式...........................................16

3.2.入库单下发................................................16

3.2.1.功能说明...........................................16

3.2.2.应用入参说明.......................................18

3.2.3.数据格式...........................................18

3.2.4.明细信息...........................................22

3.2.5.报文格式...........................................23

3.2.6.响应格式...........................................27

3.3.出库单下发.................................................27

3.3.1.功能说明............................................27

3.3.2.应用入参说明.......................................28

3.3.3.数据格式...........................................29

3.3.4.报文格式............................................33

3.3.5.响应格式............................................37

3.4.运输单下发.................................................37

3.4.1.功能说明...........................................37

3.4.2.应用入参说明.......................................39

3.4.3.数据格式...........................................39

3.4.4.明细信息...........................................43

3.4.5.报文格式...........................................44

3.4.6.响应格式...........................................48

3.5.订单取消...................................................48

3.5.1.功能说明...........................................48

3.5.2.应用入参说明.......................................50

3.5.3.出参说明............................................50

3.6.物流跟踪信息查询...........................................51

3.6.1.功能说明............................................51

3.6.2,应用入参说明.......................................52

3.6.3.数据格式............................................53

3.6.4.报文格式............................................53

3.6.5.响应报文............................................55

3.7.交货量同步.................................................55

3.7.1.功能说明............................................55

3.7.2.应用级入参说明.....................................56

3.7.3.数据格式............................................56

3.7.4.明细信息............................................57

3.7.5.报文格式............................................57

3.7.6.响应格式............................................59

3.8.订单对账推送接口..........................................59

3.8.1.功能说明...........................................59

3.8.2.数据格式...........................................59

3.8.3.报文格式...........................................61

3.8.4.响应格式...........................................62

3.9.订单状态推送接口..........................................62

3.9.1.功能说明...........................................62

3.9.2.数据格式.........................................63

3.9.3.报文格式...........................................64

3.9.4.响应格式...........................................66

3.10.入库单结果反馈...........................................66

3.10.1.功能说明..........................................66

3.10.2.数据格式..........................................66

3.10.3.报文格式..........................................68

3.10.4.响应报文...........................................70

3.11.出库单结果反馈............................................70

3.11.1.功能说明...........................................70

3.11.2.数据格式...........................................70

3.11.3.报文格式...........................................72

3.11.4.响应报文...........................................74

3.12.GPS设备信息查询.........................................74

3.12.1.功能说明..........................................74

3.12.2.应用入参说明......................................75

3.12.3.数据格式..........................................76

3.12.4.响应报文..........................................77

第四章响应报文......................................................80

4.1.响应说明..................................................80

4.2.报文格式...................................................80

第五章状态码........................................................81

5.1.接口状态码................................................81

5.2.业务状态码.................................................81

日期版本变更内容作者

1.0初稿

1.1修正

1.2新增新产品功能

6

第一章文档概述

本文档是协同平台对客户提供的一套标准对接文档。

7

第二章业务对接说明

2.1.接口说明

2.1.1.接口地址

测试地址：api-beta.XXXXXXXX.com;

正式地址：api.XXXXXXXX.com;

2.1.2.接口参数

参数名参数说明参数值备注

method接口方法名详见接口

appkey接口公钥测试：23578355

正式：23567577

requestTime请求时间yyyy-MM-ddHH：mm：ss

fromSYS来源系统对接联调时双方约定用于确定系

统来源

secret接口秘钥测试：f505bfa05bc4dde19bc0230df0799b7d

正式：04fb413e2f0702dfd50f833c25ad2059

requestContent请求报文详见接口

8

22接口清单

序号场景处理方式接口提供方备注

1货品档案同步推送鲜易货品档案同步

2入库单下发推送鲜易回传入库状态

3出库单下发推送鲜易回传出库单

4运输单下发推送鲜易回传出库状态

5订单取消推送鲜易订单取消

6物流跟踪信息查询推送鲜易

7交货量同步推送鲜易

8订单对账推送推送客户

9订单状态推送推送客户

10入库单结果反馈推送客户

11出库单结果反馈推送客户

12GPS设备信息查询推送鲜易

9

第三章标准API

3.1.货品档案同步

3.1.1.功能说明

客户公司增加或更新货品档案时，需要向档案中心系统同步货品

档案信息

服务方：

调用方：客户

接口方向：客户今

通阿里云Api网关调用，目前只支持map的传递方式，如何调用阿

里云api网关示例代码由提供

Uri:http://........../restApi/epc/getProductSync

系统参数传递方式：

Map{

Key=nmethod",value=^^getProductSync^^;

,,,,,n,

Key=appkey;value=;

10

Key=nrequestTime,,,value=,,M;

Key="fromSYS=M,value=,M,;

Key="secret”,value="”;

Key=,,requestContenr,value=,n,

)

3.1.2.应用人参说明

字段名称回传字段字段长度是否必输备注

接口方法名method50YgetProductSync

密钥appkey50Y

签名密钥secret50Y

requestTimeN平台会按请求时间存，如

请求时间果输入，格式必须为

yyyy-MM-ddHH：mm：ss

来源系统fromSYS50Y

请求报文requestContentY无长度限制

11

3.1.3.数据格式

字段名称字段编码字段长是否必输备注

度

32Y鲜易平台为客

客户编码customcrCodc户分配的客户

编码

50Y客户系统的商

货品编码goodsCode

品编码

50Y客户系统的商

货品名称goodsName

品名称

50客户系统的自

货品条码barCode

编号

32鲜易平台的货畜禽类

货品种类goodTypcCodc品一级分类编

码

8鲜易平台的货区分鲜品、冻

smallGoodType

货品小类品二级分类编品、肉制品（需

Code

码要映射）

50客户系统的规

货品规格specification

格

12

50客户系统的单

货品单位unit

位编码

32鲜易平台的温

度带编码1：冷

温度带keeptemperate

冻，2：冷藏，3：

常温4：恒温

是否批次batchManageme50YY、N；此字段为

管理nt预留字段

是否保质expiryDateMan50YY、N；此字段为

期管理agement预留字段

保质期expiryDate50单位天

50单位m（长度不

长length

能大于10）

50单位m（长度不

宽width

能大于10）

50单位m（长度不

高height

能大于10）

50单位m3（不能超

体积volume

过1000）

50单位Kg（保留3

重量weight

位小数）

13

20Y状态：正常停

货品状态state

用

货品描述description200客户系统备注

brand50

品牌

custGoodTypeC50客户方分类末

客户分类ode级信息（对应我

方小类映射）

是否仓储10传Y/NY表示

isWhType

业务仓储业务

3.1.4.报文格式

<?xmlversion="1.0"encoding="UTF-8”?>

<products>

<product>

<customerCode>abc</customerCode>

<goodsCode>/</goodsCode>

<goodsName>/</goodsName>

14

<barCode>/</barCode>

<goodTypeCode>/</goodTypeCode>

<smallGoodTypeCode>/</smallGoodTypeCode>

<specification>/</specification>

<unit>/</unit>

<keeptemperate>/</keeptemperate>

<batchManagement>/</batchManagement>

<expiryDateManagement>/</expiryDateManagement>

<expiryDate>/</expiryDate>

<length>/</length>

<width>/</width>

<height>/</height>

<volume>/</volume>

<weight>/</weight>

<state>/</state>

15

<description>/</description>

<brand>/</brand>

<custGoodTypeCode>/</custGoodTypeCode>

<isWhType></isWhType>

<product>

<products>

3.15响应格式

参照4.1响应报文

3.2.入库单下发

3.2.1.功能说明

客户审核通过采购运输计划后，当仓库是我司时，需要向我司提

供入库的信息。

服务方：

调用方：客户

接口方向：客户”

16

通阿里云Api网关调用，目前只支持map的传递方式，如何调用阿

里云api网关示例代码由提供

Uri:http://........./restApi/epc/getlnStockOrder

系统参数传递方式：

Map{

Key二"method”,value="getlnStockOrdern;

,,,,,n,

Key=appkey;value=;

Key二"requestTime,,,value=,n,;

Key="fromSYS=M,value=,,M;

Key="secret”,value="”；

Key=,,requestContenr,value=,,n

)

17

3.2.2.应用人参说明

字段名称字段编码字段长度是否必输备注

接口方法名method50YgetlnStockOrder

密钥appkey50Y

签名密钥secret50Y

requestTimN平台会按请求时间存，如

请求时间e果输入，格式必须为

yyyy-MM-ddHH：mm：ss

来源系统fromSYS50Y

requestConY无长度限制

请求报文

tent

3.2.3.数据格式

字段名称字段编码字段长度是否必输备注

warehouseCo50Y鲜易平台的仓库编码，

仓库编码

de需要映射

warehouseNa50仓库名称

仓库名称

me

custCode50Y鲜易平台为客户分配的

客户编码

客户编码

18

客户名称custNamo50Y客户名称

ordorType20Y60-运输订单，仅运输

业务

订单类型

61-仓配订单，有合作仓

同时配送业务

businsssTyp20Y订单类型：【61】业务类

e型：610-1销售出库】

611-【调拨出库】612-

【报损出库】613-【其

业务类型他出库】

620-【采购入库】621-

【调拨入库】622-1退

货入库】

623-【加工入库】

是否包含运输业provideTran1Y0-否1-是

务sport

custOrderCo30Y客户系统的订单流水号

客户订单编号

de

orderTimeyyyy-MM-ddY客户订单创建时间

订单时间

HH：mm：ss

供应商名称supportCont30Y商品的供应商名称

19

act

consignorNa50客户系统的发货单位

发货单位

me

consignorCo250Y客户系统的发货单位联

发货单位联系人

ntact系人

consignorPh250Y客户系统的发货联系电

发货人联系电话

one话

consignorPr255Y客户系统的发货地址

发货省

ovine3

consignorCi255Y客户系统的发货地址

发货市

ty

consignorCo255Y客户系统的发货地址

发货区县

unty

consignorTo255客户系统的发货地址

发货街道

wn

consignorAd255Y客户系统的发货地址

发货详细地址

dress

arrivsTimeyyyy-MM-dd

HH：mm：ss

预计入库时间

(2016-12-23

18：16:23)

20

relationOrd退货入库：原始出库单

er号

相关单号调拨入库：调拨出库单

号

此字段为预留字段；

运输车辆车牌号plateNumber30

运输车辆司机姓driverName30

名

运输车辆联系电contastNumb30

话er

pickupTime时间格式：

yyyy-MM-dd

取货时间HH：mm：ss

(2016-12-23

18:16:23)

transRequir500

运输要求

e

weight18,小数点三

重量

位

体积cubage20

件数quantity18,小数点三

21

位

totalStanda8最大值9999

合计标准箱

rdBox

备注notes300

3.2.4.明细信息

字段名称回传字段字段长度是否必输备注

货品编码gccdsCcdcROY客户系统的商品编码

货品名称goodsName1000Y客户系统的商品名称

货品规格goodsSpec20客户系统的规格

quantity18,保留Y入库件数

预期数量小数点两

位

货品单位unit6Y

productio100

生产批次

nBatch

productioyyyy-MM-

生产日期

nTimedd

invalidTiyyyy-MM-

失效日期

medd

22

销售单价unitPrice20Y单位人民币

包装pack30

supportBa50

供应商批次

tch

批号lotNumber50

weight18,小数单位kg

重量

点三位

体积cubage20单位

3.2.5.报文格式

<?xmlversion=n1.0"encoding="UTF-8H?>

<orders>

<order>

<warehouseCode></warehouseCode>

<warehouseName></warehouseName>

<custCode></custCode>

<custName></custName>

23

<orderType></orderType>

<businessType></businessType>

<provideTransport></provideTransport>

<custOrderCode></custOrderCode>

<orderTime></orderTime>

<supportContact></supportContact>

<consignorName></consignorName>

<consignorContact></consignorContact>

<consignorPhone></consignorPhone>

<consignorProvince></consignorProvince>

<consignorCity></consignorCity>

<consignorCounty></consignorCounty>

<consignorTDwn></consignorlbwn>

<consignorAddress></consignorAddress>

<arriveTime></arriveTime>

24

<relationOrder></relationOrder>

<plateNumber></plateNumber>

<driverName></driverName>

<contactNumber></contactNumber>

<pickupTime></pickupTime>

<transRequire></transRequire>

<weight></weight>

<cubage></cubage>

<quantity></quantity>

<totalStandardBox></totalStandardBox>

<notes></notes>

<orderDetails>

<orderDetail>

<goodsCode></goodsCode>

<goodsName></goodsName>

25

<goodsSpec></goodsSpec>

<quantity></quantity>

<unit></unit>

<productionBatch></productionBatch>

<productionTime></productionTime>

<invalidTime></invalidTime>

<unitPrice></unitPrice>

<pack></pack>

<supportBatch></supportBatch>

<lotNumber></lotNumber>

<weight></weight>

<cubage></cubage>

</orderDetail>

</orderDetails>

</order>

26

</orders>

326,响应格式

参照4.1响应报文

3.3.出库单下发

3.3.1.功能说明

当客户完成出库作业后触发该接口，将出库发运数据推送到协同

平台，支持批量业务处理。

服务方：

调用方：客户

接口方向：客户今

通阿里云Api网关调用，目前只支持map的传递方式，如何调用阿

里云api网关示例代码由提供

Uri:http://........./restApi/epc/getOutStockOrder

系统参数传递方式：

27

Map{

>>

Key二"method",value="getOutStockOrder;

,,,,,n,

Key=appkey;value=;

Key="requestTime,,,value=,n,;

Key="fromSYS=n,value=>,M;

Key="secret”,value="”；

Key=nrequestContenr,value=,n,

)

3.3.2.应用人参说明

字段名称字段编码字段长度是否必输备注

接口方法名method50YgetOutStockOrder

密钥appkey50Y

签名密钥secret50Y

requestTimeN平台会按请求时间存，如

请求时间果输入，格式必须为

yyyy-MM-ddss

28

来源系统fromSYS50Y

请求报文requcstContentY无长度限制

3.3.3.数据格式

字段名称字段编码字段长度是否必输备注

仓库编码warchouscCode50Y鲜易平台的仓库编码

仓库名称warchouseName50Y仓库名称

50Y鲜易平台为客户分配

客户编码custCode

的客户编码

客户名称custName50Y客户名称

orderType2Y60-运输订单，仅运输

业务

订单类型

61-仓配订单，有合作

仓同时配送业务

businessType20Y订单类型：【61】业务

类型：610-1销售出库】

611-【调拨出库】312-

业务类型

【报损出库】613-【其

他出库】

620-【采购入库】521-

29

【调拨入库】622-1退

货入库】

623-【加工入库】

custOrderCode30Y客户系统的订单流水

客户订单编号

号

provideTranspoY0-否1-是

是否包含运输业务

rt

orderTime格式：Y客户订单创建时间

vvvy-MM-dd

HH：mm：ss

订单时间

(2016-12-2

3

18：16：23)

consigneeConta250收货方联系人编码

收货方联系人编码

ctCode

收货单位consignecName250Y收货方名称

consigneeConta250Y收货单位联系人

收货单位联系人

Ct

收货人联系电话consigneoPhone250Y收货人联系电话

收货省consigneeProvi255Y收货省

30

nee

收货市consignoeCity255Y收货市

consigneeCount255Y收货区县

收货区县

y

收货街道consigneeTown255收货街道

consigneeAddre255Y收货详细地址

收货详细地址

ss

运输司机姓名driverName30

车牌号plateNumber30

联系电话contactNumber30

arriveTime格式：N客户系统计划时间

yyyy-MM-dd

预计出库时间HH：mm：ss

(2016-12-2

318：16:23

relationOrder退货入库：原始出库单

号

相关单号调拨入库：调拨出库单

号

此字段为预留字段

运输要求transRequire500

31

totalStandardB8

合计标准箱

ox

weight18,小数点

重量

三位

体积cubage20

quantity18,小数点

件数

三位

备注