西域与各电商平台对接统一规范1 5 4VIP

1、西域与各电商平台对接统一规范西域与各电商平台对接统一规范西域对接项目组修改历史版本时间内容描述V0.12017-08-11创建V0.52017-12-20通用接口V0.62018-01-11添加查询物流信息的接口V0.72018-02-06补充/完善各接口数据结构示例V1.02018-03-14修订部分商品相关业务细节V1.12018-03-19新增接口调用流程图V1.22018-4-125.5.1下单接口新增“下单公司”字段V1.32018-4-185.1.2刷新token信息V1.42018-4-231.删除中upc（条形码）字段2.删除5.2.7 商品可售验证接口；3.优化

2、中submitState字段的说明和备注说明；V1.4.12018-4-25该上下级为上下架V1.52018-5-21.新增接口5.5.10，查询订单信息（根据第三方订单号）；2.将接口 5.5.7 中packageId对应的说明统一为“包裹号”。V1.5.12018-5-291、价格为空时传0V1.5.22018-6-6统一下单接口删除两个字段1.发票抬头类型，2.发票内容新增5个字段1增值税发票营业电话，2增值税发票营业地址3纳税人识别号4开户行5开户行账号V1.5.32018-7-31申请售后服务接口新增类型“取消”；服务单号查询服务单明细新增类型“取消”；消息type=1

3、02，定义说明包括取消V1.5.42018-8-17获取推送消息接口，增加Type=9西域商城订单确认的消息类型及其示例目录1.前言- 1 -2.缩略语和术语定义- 1 -2.1.缩略语- 1 -2.2.术语- 1 -3.接入指南- 1 -4.接入技术- 2 -4.1.实时接口- 2 -4.1.1.传输协议- 2 -4.1.2.报文协议- 3 -4.1.3.API调用方式- 3 -4.1.4.鉴权方式- 5 -5.接口服务- 6 -5.1.鉴权类- 6 -5.1.1.获取token信息- 6 -5.1.2.刷新token信息- 8 -5.2.商品类- 10 -5.2.1.获取商品池编号- 10

4、 -5.2.2.获取池内商品编号- 11 -5.2.3.获取商品详细信息- 13 -5.2.4.获取商品上下架状态- 19 -5.2.5.获取所有图片信息- 21 -5.2.6.商品区域购买限制查询- 23 -5.3.价格类- 26 -5.3.1.批量查询商品价格- 26 -5.4.库存类- 28 -5.4.1.批量查询商品库存- 28 -5.5.订单类- 31 -5.5.1.统一下单- 31 -5.5.2.确认订单（生成预订单的情况）- 37 -5.5.3.取消订单（只针对预订单的情况）- 39 -5.5.4.订单反查接口- 40 -5.5.5.查询订单信息- 42 -5.5.6.查询订单配

5、送信息接口（暂无，通过异步消息获取）- 46 -5.5.7.查询发货单信息接口- 48 -5.5.8.订单完结通知（暂无，通过异步消息获取）- 50 -5.5.9.物流信息查询- 52 -5.5.10.查询订单信息（根据第三方订单号）- 55 -5.6.对账类- 58 -5.6.1.新建订单对账接口- 58 -5.6.2.妥投/部分妥投订单对账接口- 61 -5.6.3.拒收订单对账接口- 64 -5.7.售后类- 67 -5.7.1.申请售后服务- 67 -5.7.2.根据服务单号查询服务单明细信息- 71 -5.8.信息获取- 75 -5.8.1.获取推送消息接口- 75 -5.8.2.删

6、除消息接口- 87 -5.9.发票类- 88 -5.9.1.申请发票开具- 88 -5.9.2.查询发票信息- 93 -5.9.3.查询发票运单信息- 96 -6.附录- 99 -6.1.返回码（不含发票类）- 99 -iii西域与各电商平台对接统一规范1. 前言本文档适用于自建电商平台，有意与西域战略合作，进行平台对接的客户平台。本文档主要提供给项目经理、产品经理、开发工程师、测试工程师等确认需求、了解API交互，API测试、流程测试、功能测试之用2. 缩略语和术语定义2.1. 缩略语本文档所涉及的缩略语解释请参见下表。缩略语英文全称中文全称SKUStock Keeping Unit库存量单

7、位2.2. 术语本文档所涉及的术语定义请参见下表。名词解释API分类是指提供的API按功能进行分类，主要分为：商品类、订单类等API是指系统间对接的文件和实时接口API参数用于标识API的系统级和应用级的输入、输出参数定义实时接口实时接口是通过HTTP进行服务请求的调用方式，都是对接方请求西域接口文件接口系统间通过文件方式进行信息传递的方式3. 接入指南在与网上商城对接前需要准备如下工作： 环境准备：a) 网络接入：通过互联网网络与网上商城连接a) 系统开发：开发自身业务系统；b) 系统注册：获得网上商城或外部业务系统的标识、key、密钥、授权等信息； 对接测试：外部业务系统与网上商城系统进行

8、接口联通性测试；包括接口报文格式、系统参数校验，但不进行业务数据格式校验及业务逻辑测试，所有的调用通过模拟成功返回； 业务测试：外部业务系统与网上商城系统进行对接测试，包括接口报文格式、系统参数校验、业务逻辑校验，进行全流程的业务贯通测试，包括网络对接； 验证开通：系统在正式开放前，进行若干周期的试运行。4. 接入技术支持两种接入方式：实时接口、文件接口，并提供先关自服务功能，向外部业务系统提供信息公告、结算对账等服务。 实时接口是一种以实时数据处理进行交互的接入方式。 文件接口是一种以文件形式进行交互的接入方式，支持的文件类型包括结算清单、对账文件等。4.1. 实时接口4.1.1. 传输协议

9、 采用HTTP传输协议，并采用RESTFUL风格的服务访问方式。 为了提供简单、规范化的技术实现，使用POST方式发起API请求（具体使用说明详见5章节接口服务） GET请求的数据会附在URL之后，以?分割URL和传输数据，参数之间以&相连。 POST把提交的数据则放置在HTTP包的包体中。 所有参数值需要转换为UTF-8编码。 支持POST请求方式的API接口4.1.2. 报文协议. POST请求方式请求和响应报文消息均采用JSON表达。POST请求需要拼装JSON报文，报文消息使用UTF-8编码。.1. 请求报文格式示例POST http:/接口服务路径 HTT

10、P/1.1Accept: application/jsonContent-Type: application/json;charset=UTF-8Content-Length: #JSON消息长度token:x9lelkX,sku:cOKD31n20140101101937816x93z92,cOKD31n20140101101937816x93z9.2. 响应报文格式示例 正常情况响应报文格式：HTTP/1.1 200 OKContent-Type: application/json;charset=UTF-8Content-Length: #JSON字符串长度XX:.4.1

11、.3. API调用方式. 参数说明 名称：参数英文名称，用于HTTP-POST方式JSON报文中节点的名称和HTTP-GET方式链接中的节点名称,所有节点名称都小写。 类型：标识此节点的参数类型。类型名称格式样例booleantrue、falsetruedatetimeYYYY-MM-DD HH:MM:SS或其他时间格式2014-01-01 16:17:24、20140101161724timestampYYYY-MM-DD HH:MM:SS2014-01-01 16:17:24string字符串手机int整型数字123123，322342，24234Enum枚举类型basic_

12、service，system_service*_entityjson实体phone_number_entityjson实体集合phone_numberphone_number必填?：Y为必填，N为选填 备注：为具体描述此参数的业务和取值范围。. 公共参数除获取token接口之外，其他API接口都需要传递公共参数，以保证接口数据可查 请求公共参数名称类型必填?说明备注appkeyStringY发起方id西域商城为各对接方分配tokenStringY鉴权信息按照获取token接口获取timeStampStr

13、ingY时间戳格式为yyyy-MM-dd HH:mm:ssserialNumberStringY交易流水号一次调用的唯一流水号，20位定长 返回公共参数名称类型必填?说明备注successBooleanY执行结果成功，还是失败true：成功false：失败resultCodeStringY错误码详见错误码resultMessageStringY错误描述resultresult_entityY具体结果每个接口都会单独进行说明4.1.4. 鉴权方式1. 在对接方调用西域商城系统时，需要先向西域商城系统发起请求认证，调用获取token信息，之后才能访问API；在后续API调用时需要鉴权信息；当鉴权信

14、息失效或需要更换时，必须重新进行认证。示意图如下2. 每一个鉴权信息都拥有失效时间，必须在鉴权信息失效前重新认证或续期；5. 接口服务5.1. 鉴权类5.1.1. 获取token信息. 应用场景获取西域商城的token鉴权值。. 请求说明API名称accessToken调用入口http:/url/accessTokenHTTP请求方式HTTP-POST格式JSONAPI授权类型需要授权类型基础服务. 应用级输入参数名称类型必填?说明备注grant_typeStringY该值固定为access_tokenclient_idStringY鉴权账号由西域事先

15、分配client_secretStringY鉴权账号的密码由西域事先分配timestampStringY当前调用时间格式为“2014-01-01 01:01:01”usernameStringY用户名由西域事先分配passwordStringY用户密码由西域事先分配，md5加密后的字符串. 应用级返回结果名称类型必填?说明备注Access_tokenStringYAccess_token值Refresh_tokenStringNRefresh_token值timeStringY当前时间expires_inIntYAccess_token的过期时间，秒级别,有效期24小时refre

16、sh_token_expiresIntNrefresh_token的过期时间，毫秒级别. 示例.1. 请求示例 grant_type:access_token, client_id:x9lelkX, client_secret:sjd79and83cgem, timestamp:2017-08-10 01:01:01, username:guodianwssc, password:cOKD31n20140101101937816x93z9.2. 返回示例 result: time:2018-03-05 14:13:34, expires_in:863

17、99, access_token:d6b90e45-a35b-49cd-84ac-49461ed2ad31 , resultCode:0000, resultMessage:获取accessToken成功, success:true. 备注说明5.1.2. 刷新token信息. 应用场景获取西域商城的token鉴权值。. 请求说明API名称/refreshToken调用入口http:/url/refreshTokenHTTP请求方式HTTP-POST格式JSONAPI授权类型需要授权类型基础服务. 应用级输入参数名称类型必填?说明备注cl

18、ient_idStringY鉴权账号由西域事先分配client_secretStringY鉴权账号的密码由西域事先分配refresh_tokenStringY刷新tokenacessToken或refreshToken接口获取. 应用级返回结果名称类型必填?说明备注Access_tokenStringYAccess_token值Refresh_tokenStringNRefresh_token值timeStringY当前时间expires_inIntYAccess_token的过期时间，秒级别,有效期24小时refresh_token_expiresIntNrefresh_tok

19、en的过期时间，毫秒级别. 示例.1. 请求示例 client_id:x9lelkX, client_secret:sjd79and83cgem, refresh_token:633a45e9-19da-41f9-98b4-d0363a744a4.2. 返回示例 result: time:2018-03-05 14:13:34, expires_in:86399, access_token:d6b90e45-a35b-49cd-84ac-49461ed2ad31 , resultCode:0000, resultMessage:刷新accessTok

20、en成功, success:true. 备注说明5.2. 商品类5.2.1. 获取商品池编号. 应用场景获取对接双方划定的商品池列表。. 请求说明API名称getPageNum调用入口http:/url/mall/getPageNumHTTP请求方式HTTP-POST格式JSONAPI授权类型需要授权类型基础服务. 应用级输入参数. 应用级返回结果result_entity名称类型必填?说明备注nameStringY商品池名称西域一级产线名称page_numStringY商品池编码西域一级产线ID. 示例5.2

21、.1.5.1. 请求示例appkey:CGDC,serialnumber:sjd79and83cgem,timestamp:2017-08-19 10:13:01,token:7886f145d87cb5d3219e8291c225f9c.2. 返回示例result:name:气动,page_num:1,name:办公,page_num:2,name:实验室产品,page_num:3,resultCode:0000,resultMessage:查询成功,success:true. 备注说明5.2.2. 获取池内商品编号. 应用场景通过池编码获取商品池

22、内的SKU编码。. 请求说明API名称getSkuByPage调用入口http:/url/mall/getSkuByPageHTTP请求方式HTTP-POST格式JSONAPI授权类型需要授权类型基础服务. 应用级输入参数名称类型必填?说明备注pageNumStringY池编码pageNoIntY页码默认取第一页，每页最多1000条数据，品类商品池可能存在多页数据，具体根据返回的页总数判断是否有下一页数据. 应用级返回结果名称类型必填?说明备注pageCountIntY总页数skuIdsStringYSku列表. 示例.1.

23、 请求示例 appkey:CGDC, serialnumber:sjd79and83cgem, timestamp:2017-08-19 10:13:01, token:7886f145d87cb5d3219e8291c225f9c8 pageNum:001, pageNo:.2. 返回示例result:pageCount:1,skuIds:MAQ483,MWK479,MWK478,MWK477,resultCode:0000,resultMessage:查询成功,success:true. 备注说明5.2.3. 获取商品详细信息. 应用场景通过sk

24、u编码查询sku的详细信息，包括商品名称、品牌、上下架状态、条形码、商品介绍等信息。. 请求说明API名称getDetail调用入口http:/url/mall/getDetailHTTP请求方式HTTP-POST格式JSONAPI授权类型需要授权类型基础服务. 应用级输入参数名称类型必填?说明备注skuStringY商品编号. 应用级返回结果名称类型必填?说明备注skuStringY商品编号weightStringN重量imagePathStringY主图地址stateIntY上下架状态1：上架0：下架brandNameStringY品牌中文名称br

25、andPicStringN品牌图片品牌图片地址nameStringY商品名称productAreaStringN产地saleUnitStringY销售单位categoryStringY类目按提供该SKU对应的所有类目信息，并按照照一二三四级顺序提供moqIntN最小起订量Mro专用mfgSkuStringN制造商型号Mro专用deliveryTimeIntN货期Mro专用单位：天0代表询货期isReturnIntN是否允许退换货0：允许退换货1：不允许退换货默认为0，不传默认按0处理introductionStringN商品描述HTML页面，可直接展现wareQDStringN包装信息包装描述

26、信息，HTML页面，可直接展现paramparam_entityN规格属性信息param_entity名称类型必填?说明备注attrCodeStringN属性编码attrNameStringY属性名称attrValueStringY属性值attrSeqStringY属性排序attrGroupCodeStringN属性组编码attrGroupNameStringN属性组名称attrGroupSeqStringN属性组排序. 示例-.1. 请求示例 appkey:CGDC, serialnumber:sjd79and83cgem, timestamp:2017-08-1

27、9 10:13:01, token:7886f145d87cb5d3219e8291c225f9c8 sku:MBW45.2. 返回示例result:brandName:亿洋,brandPic:null,category:5,71,701,701,deliveryTime:1,imagePath:/uploadfile/HT/MBW451.jpg,introduction:内六角扳手套装： 想了解更多内六角扳手套装信息，请联系西域工作人员;,isReturn:0,mfgSku:YP-127,moq:1,name:梅花扳手，8件套 5.

28、5-27mm，YP-127,param:attrCode:89,attrGroupCode:null,attrGroupName:null,attrGroupSeq:null,attrName:品牌,attrSeq:10,attrValue:国标制式,attrCode:2104,attrGroupCode:null,attrGroupName:null,attrGroupSeq:null,attrName:套装类型,attrSeq:12,attrValue:梅花扳手,attrCode:1610,attrGroupCode:null,attrGroupName:null,attrGroupSeq

29、:null,attrName:描述,attrSeq:20,attrValue:8件套梅花扳手,attrCode:1186,attrGroupCode:null,attrGroupName:null,attrGroupSeq:null,attrName:规格,attrSeq:30,attrValue:5.57,810,1012,1214,1417,1719,1922,2427mm,productArea:null,saleUnit:套,sku:MBW451,state:0,upc:null,wareQD:包装清单包装参数长度(mm)300宽度(mm)150高度(mm)30重量(kg)1.0,we

30、ight:null,resultCode:0000,resultMessage:查询成功,success:true. 备注说明5.2.4. 获取商品上下架状态. 应用场景通过sku编码该SKU当前的上下架状态。. 请求说明API名称skuState调用入口http:/url/mall/skuStateHTTP请求方式HTTP-POST格式JSONAPI授权类型需要授权类型基础服务. 应用级输入参数名称类型必填?说明备注skuStringY商品编号支持批量，以，分隔. 应用级返回结果result名称类型必填?说明备注skuSt

31、ringY商品编号stateIntY商品状态1：上架0：下架. 示例-.1. 请求示例appkey:CGDC, serialnumber:sjd79and83cgem, timestamp:2017-08-19 10:13:01, token:7886f145d87cb5d3219e8291c225f9c8, sku:MZA044,MCX775,MFB10.2. 返回示例result:sku:MCX775,state:1,sku:MFB102,state:1,sku:MZA044,state:1,resultCode:0000,resultMessa

32、ge:查询成功,success:true5.2.5. 获取所有图片信息. 应用场景通过sku编码查询该sku的所有图片信息。. 请求说明API名称skuImage调用入口http:/url/mall/skuImageHTTP请求方式HTTP-POST格式JSONAPI授权类型需要授权类型基础服务. 应用级输入参数名称类型必填?说明备注skuStringY商品编号支持批量，以，分隔. 应用级返回结果result名称类型必填?说明备注skuStringY商品编号skuPicskuPic_entityY商品图片skuPic_entity名称类型

33、必填?说明备注pathStringY图片地址图片地址isPrimaryIntY是否主图1：是0：否orderSortIntY排序主图可传null非主图传排序数字path字段中将图片地址按照从大、中、小的顺序都传，图片地址按照逗号分隔，其中至少有中图和小图。. 示例.1. 请求示例 appkey:CGDC, serialnumber:sjd79and83cgem, timestamp:2017-08-19 10:13:01, token:7886f145d87cb5d3219e8291c225f9c8, sku:MCX775,MZA04.2. 返回示例

34、result:skuPic:isPrimary:1,orderSort:1,path:/uploadfile/opc/img/2016/12/19/20161219143118407.jpg,/uploadfile/opc/img/2016/12/19/20161219143118407_M.jpg,/uploadfile/opc/img/2016/12/19/20161219143118407_S.jpg,sku:MCX775,skuPic:isPrimary:

35、1,orderSort:1,path:/uploadfile/opc/img/2016/12/14/20161214140101801.jpg,/uploadfile/opc/img/2016/12/14/20161214140101801_M.jpg,/uploadfile/opc/img/2016/12/14/20161214140101801_S.jpg,sku:MZA044,resultCode:0000,resultMessage:查询成功,succes

36、s:true. 备注说明5.2.6. 商品区域购买限制查询. 应用场景通过sku编码和地址查询该sku在该地址上是否可以购买。城市映射表如果放在对接方，则入参传西域城市ID；如映射表在西域，则可传对接方的城市编号. 请求说明API名称checkAreaLimit调用入口http:/url/mall/checkAreaLimitHTTP请求方式HTTP-POST格式JSONAPI授权类型需要授权类型基础服务. 应用级输入参数名称类型必填?说明备注skuIdsStringY商品编号支持批量，以，分隔provinceIntY一级地址编号city

37、IntY二级地址编号countyIntN三级地址编号如无传0townIntN四级地址编号如无传0. 应用级返回结果result名称类型必填?说明备注skuIdStringY商品编号isAreaRestrictbooleanYTruefalsetrue 代表区域受限false 区域不受限. 示例.1. 请求示例 appkey:CGDC, serialnumber:sjd79and83cgem, timestamp:2017-08-19 10:13:01, token:7886f145d87cb5d3219e8291c225f9c8,skuIds:4255

38、661,province:1,city:1,county:0,town:0.2. 返回示例result:isAreaRestrict:false,skuId:MAD613,isAreaRestrict:false,skuId:MAD712,resultCode:0000,resultMessage:查询成功,success:true. 备注说明5.3. 价格类5.3.1. 批量查询商品价格. 应用场景根据sku编码批量查询西域电商价和协议价。. 请求说明API名称getSellPrice调用入口http:/url/mall/getSellPriceHTTP请求方式HTTP-POST格式JSONAPI授权类型需要授权类型基础服务. 应用级输入参数名称类型必填?说明备注skuStringY商品编号，请以，(英文逗号)分割. 应用级返回结果result名称类型必填?