API - 巨商汇物流接口平台

接口说明
订单创建
订单状态修改
商品创建
订单生命周期
条码接收

接口说明

本文档目的是定义巨商汇物流系统接口平台（后面简称 JSH）的通用对外服务接口，以便快速集成大客户自有的系统，从而打通大客户与巨商汇物流系统之间的信息流，实现整体物流供应链的一体化，进而达到巨商汇与客户的双赢。

接入流程说明

客户自行巨商汇物流平台网站http://56.jsh.com，注册成为平台用户；
进行企业认证，升级为货主；
向巨商汇物流部申请巨商汇物流系统接入（包含服务器IP、客户名称）；
巨商汇物流部审批后，开通接入授权码、统一发放clientId，并提供对接支持；
客户进行系统对接开发和调试；
系统对接发布上线；

接口协议

服务接口使用HTTP协议进行通信
HTTP请求的ContentType需设置为”application/x-www-form-urlencoded”
接口的返回json格式的数据
请求和响应统一使用UTF-8方式进行编码

参数校验说明

为提高接口的安全性，调用接口时需要为每个请求增加一个校验参数（verifyCode），校验参数的生成算法如下：

按照字典排序规则对参数名称进行排序。
按照排序结果将参数名称、参数值和系统分配的授权码按照如下格式进行拼接：paramName1=paramValue1¶mName2=paramValue2&……&authCode。拼接字符串的时候参数值需要使用原始值，不能对其进行URL编码。
将第二步拼接出的字符串进行MD5编码，并将得到的值作为参数verifyCode一起发送到服务器端。

系统参数说明

除了业务参数外，所有的接口都需要携带clientId和verifyCode两个系统参数，用来进行请求校验。

参数名称	参数类型	说明
clientId	string	系统预分配，每个客户有独立的客户ID
verifyCode	string	按照《参数校验说明》计算出的校验码

请求值格式说明

请求值格式为param=value格式的字符串，其格式如下：

paramName1=paramValue1¶mName2=paramValue2&array[0]=arrayValue0&array[1]=arrayValue1&item[0].id=id1&item[0].name=name1&……&clientId=10000&verifyCode=xxx

返回值格式说明

接口返回值为json格式的字符串，其格式如下：


              {
              "code": 0,
              "data": {
              "orderId": "JSH123"
              },
              "success": true,
              "infoMsgs": ["下单成功"],
              "warningMsgs": [],
              "errorMsg": null
              }

参数含义如下：

参数名称	参数类型	说明
success	boolean	表示接口调用是否成功。true:成功，false:失败
code	int	1.如果接口调用成功，即success的值为true时，值为0； 2.如果接口调用失败，如无特殊约定，其值为-1，如果接口有特殊约定，则其值定义参考接口说明。
infoMsgs	String list	接口返回的说明性文字，起辅助说明的作用
warningMsgs	String list	记录接口执行过程的警告类信息
errorMsg	String	失败信息说明。若success为true，则消息为空；若success为false，则记录失败原因
data	object	接口业务数据。具体参考接口说明文档

订单创建

接收客户平台创建/修改订单资料，在巨商汇物流平台中创建/修改订单资料(无对应订单的数据就新增，已有记录，需要先判断订单状态是否允许修改，如允许就更新，不允许则返回错误提示；

接口基本信息

URL	http://56.jsh.com/order/rest/create
请求方式	POST
接口类型	接入

请求参数(主档)

请求参数orderDtl(明细档)

请求参数orderAs（可选）

返回值data部分说明

报文范例

请求代码样例：

sourceOrderNo=85123456789RK1&orderDtl.lineNo[0]=1&orderDtl.itemId[0]=123&orderDtl.lineNo[1]=2&orderDtl.itemId[1]=456&orderDtl.itemName[1]=456&clientId=10001&verifyCode=5bb24a2511b81218f1a0d45d9f030ebe

返回报文：


              {
              "code": 0,
              "data": [
              {
              "orderId": "1777543467",
              "orderNo": "P12313478234",
              "waybillNo": null
              }
              ],
              "success": true,
              "infoMsgs": [
              "创建订单成功!"
              ],
              "warningMsgs": [],
              "errorMsg": null
              }

订单状态修改

接收客户平台订单状态修改资料，在物流JSH平台中进行相应的订单状态变更处理；（但不一定成功，会返回相应的错误信息）

接口基本信息

URL	http://56.jsh.com/order/rest/updateStatus
请求方式	POST
接口类型	接入

请求参数

返回值data部分说明

报文范例

请求代码样例：略

返回报文：


              {
              "code": 0,
              "data": [
              {
              "orderId": "1777543467",
              "orderNo": "P12313478234",
              "waybillNo": null
              }
              ],
              "success": true,
              "infoMsgs": [
              "修改成功!"
              ],
              "warningMsgs": [],
              "errorMsg": null
              }

商品创建

将客户平台的商品主数据信息推送至巨商汇JSH平台。（套件商品需先传组件商品）

接口基本信息

URL	http://56.jsh.com/parts/rest/create
请求方式	POST
接口类型	接入

请求参数

套件明细（套件商品必选）

返回值data部分说明

无业务返回值

报文范例

请求代码样例：略

返回报文：


              {
              "code": 0,
              "data": [],
              "success": true,
              "infoMsgs": [
              "商品创建成功!"
              ],
              "warningMsgs": [],
              "errorMsg": null
              }

订单生命周期

将巨商汇JSH平台订单的生命周期信息，推送至客户平台。（增量推送）

接口基本信息

批量交易	支持
接口方法	以Http Post形式进行推送请求
接口类型	推送

请求参数

路由列表信息

返回值data部分说明

报文范例

请求代码样例：略

返回报文：


              {
              "code": 0,
              "data": [
              {
              "sId": ["1", "2", "3", "4", "5"],
              "errorId": ["6", "7"]
              }
              ],
              "success": true,
              "infoMsgs": [
              "路由信息接收成功!"
              ],
              "warningMsgs": [
              "存在失败路由id信息"
              ],
              "errorMsg": null
              }

条码接收

接收客户平台传入卸货扫描信息，在巨商汇物流平台中更新单据信息。

接口基本信息

URL	http://56.jsh.com/barcode/rest/create
请求方式	POST
接口类型	接入

请求参数

返回值data部分说明

无业务返回值

报文范例

请求代码样例：

machineNo[0]=B083278621&machineNo[1]=B083278622&machineNo[2]=B083278623&machineNo[3]=B213456411&machineNo[4]=B213456412&clientId=10001&receiptNo=85123456789RK1&verifyCode=5bb24a2511b81218f1a0d45d9f030ebe

返回报文：


              {
              "code": 0,
              "data": [
              {
              "sId": ["1", "2", "3", "4", "5"],
              "errorId": ["6", "7"]
              }
              ],
              "success": true,
              "infoMsgs": [
              "路由信息接收成功!"
              ],
              "warningMsgs": [
              "存在失败路由id信息"
              ],
              "errorMsg": null
              }