[toc] ### 则一订单对接API 则一提供了不同规范的API，调用则一订单服务端API前，需了解开发前须知及调用流程。本文提供了调用则一订单服务端API示例，供开发者参考。 #### 白名单 则一服务端API接口访问有IP白名单限制，需要接口调用方提供调用API的服务器IP地址。 #### 数据加签 采用md5(32位小写)算法生成签名 appKey(则一提供) + appSecret(则一提供) + timestamp(当前时间戳毫秒) + nonce(6位随机码大小写字母数子组合) + data(请求数据) #### 数据加密 数据加密采用AES算法 加密模式： CBC 填充方式：PKCS5Padding 偏移量：iv(则一提供) 加密内容：appKey(则一提供) + timestamp(当前时间戳毫秒) + nonce(6位随机码大小写字母数子组合) + data(加密数据) 密钥： appSecret(则一提供) 输出：base64 字符集：utf-8 注：无敏感数据则无需加密 #### 获取访问凭证 ##### 概述 调用则一服务API时，都需要先获取对应权限类型的访问凭证accessToken。访问凭证（accessToken）是由则一权限系统颁发的，用来校验调用者的身份信息，确保调用者具有要执行的操作的权限。 **说明**： 在使用accessToken时，请注意： * accessToken的有效期默认为30天，有效期内重复获取会返回相同结果，过期后获取会返回新的accessToken。 * 开发者需要缓存accessToken，用于后续接口的调用。不能频繁调用获取accessToken接口，否则会受到频率拦截。 * 当调用业务API时，如果返回状态码为401，则说明accessToken不正确或已过期，这时需要重新获取accessToken后再调用对应的API。 ##### 接口信息 ###### 请求方式： post ###### 请求地址： * 生产：https://gw.shjiuze.cn/auth-service-api/login/password * 测试：https://test.shjiuze.cn/auth-service-api/login/password ###### Body参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | -------- | ------ | ---- | ----------- | ---------------- | | username | String | 是 | zhangsan | 用户名，则一提供 | | password | String | 是 | password123 | 密码，则一提供 | ###### 返回参数 | 名称 | 类型 | 示例值 | 描述 | | ------------------------------ | ---------- | -------------------------------- | -------------------------------------------------- | | success | boolean | true | 成功标识: true 成功，false 失败 | | businessException | boolean | false | 业务异常标识: true 业务异常，false 正常 | | errorCode | String | 200 | 错误码: 200 业务异常，500 系统异常， 空表示无错误 | | message | String | 订单号不能为空 | 错误信息，无错误则返回空 | | result | ZYTokenDto | | accessToken结果数据 | |     accessToken | String | 000626f15b4b41bba6fe56216a5d2f73 | accessToken | |     expiresIn | Integer | 2060 | 有效期限单位秒，accessToken在2060秒后过期 | |     tokenType | String | bearer | token类型 | ##### 请求示例 ###### Http方式 ```http POST /auth-service-api/login/password HTTP/1.1 Host:test.shjiuze.cn Content-Type:application/json { "username" : "zeyi", "password" : "test1111" } ``` ###### Java-sdk方式 [下载SDK](https://zeyi-tms-product.oss-cn-hangzhou.aliyuncs.com/file/jar/java-sdk/zy-java-sdk-1.0.0.jar) ```java public class Sample { public static void main(String[] args_) { String appKey = "appkey"; String appSecret = "appSecret"; ZYClient zyClient = new ZYClient(appKey, appSecret); ZYTokenRequestDto zyTokenRequest = new ZYTokenRequestDto(); zyTokenRequest.setUsername("zeyi"); zyTokenRequest.setPassword("test1111"); String body = gson.toJson(zyTokenRequest); HttpResponseData httpResponseData = zyClient.doPost(Constants.TEST_HOST + Constants.TOKEN_PATH, body); if(httpResponseData == null) { throw new TokenException("则一Token请求失败,返回为空!"); } ZYResponse zyResponse = gson.fromJson(httpResponseData.getBody(), new TypeToken>(){}.getType()); if(!Boolean.TRUE.equals(zyResponse.isSuccess())) { throw new TokenException("则一Token请求返回失败!" + zyResponse.getMessage()); } if(zyResponse.getResult() == null) { throw new TokenException("则一Token请求返回失败,返回结果为空!" + zyResponse.getMessage()); } if(StringUtils.isBlank(zyResponse.getResult().getAccessToken())) { throw new TokenException("则一Token请求返回数据异常,AccessToken为空!" + zyResponse.getMessage()); } // 结果 zyResponse.getResult(); } } ``` ##### 返回示例 ```json { "success": true, "businessException": false, "errorCode": null, "message": null, "result": { "accessToken": "64d7f367-609b-4f7d-a84d-a3d2a0b5ad85", "expiresIn": 602105, "tokenType": "bearer" } } ``` #### 下单 ##### 接口信息 ###### 请求方式： post ###### 请求地址： * 生产：https://gw.shjiuze.cn/oms-service-api/order/add * 测试：https://test.shjiuze.cn/oms-service-api/order/add ###### Headers参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ------------- | ------ | -------------------------- | -------------------------------- | ------------------------------------------------------------ | | Authorization | String | 是     | Bearer a2c5680001 | 调用服务端API的应用凭证accessToken，通过调用获取访问凭证接口获取。 | | appKey | String | 是 | 0867ef5f23ef6483749e19e1692b | 则一提供 | | timestamp | String | 是 | 1643251533306 | 当前时间戳毫秒值 | | nonce | String | 是 | gdst9t | 6位小写字母数字组合随机串 | | sign | String | 是 | fa3ed338d6dfe18e7273c8692234ee70 | 签名：appKey(则一提供) + appSecret(则一提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成 | ###### Body参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ------------------------------------- | -------------------- | -------------------------- | ---------------- | ------------------------------------------------------------ | | customerOrderCode | String | 是     | 220101000001 | 客户订单号，订单唯一标识 | | customerSn | String | 否 | 220101000001 | 客户委托单号 | | placeOrderTime | Number | 是 | 1643251533306 | 下单时间，时间戳毫秒值 | | loadTime | Number | 是 | 1643251533306 | 装货时间，时间戳毫秒值 | | expectArrivalTime | Number | 否 | 1643251533306 | 期望送达时间，时间戳毫秒值 | | receiptType | String | 否 | ELECTRON_TYPE | 回单类型：ELECTRON_TYPE/电子回单,PAPER_TYPE/纸质回单,NONE/无 | | receiptNumber | Number | 否 | 1 | 回单张数 | | receiptCode | String | 否 | A2022012602278 | 回单号 | | payType | String | 否 | PAY_IN_CASH | 付款方式：PAY_IN_CASH/现付,PAY_ON_DELIVERY/到付,PAY_ARREARS/欠付,PAY_MONTH/月结,PAY_BACK/回付,PAY_MULTIPLE/多笔付,PAY_FREE/免费 | | lineName | String | 否 | 上海-天津-北京 | 线路名称 | | remark | String | 否 | 需要雨布和尾板 | 订单备注 | | station | OrderStation[] | 是 | | 订单经停点 | |     stationId | String | 否 | 123abc | 站点id | |     stationName | String | 否 | 上海顺丰青浦站点 | 站点名称 | |     provinceCode | String | 否 | 310000 | 省份编号 | |     provinceName | String | 是 | 上海 | 省份名称 | |     cityCode | String | 否 | 310100 | 城市编号 | |     cityName | String | 是 | 上海市 | 城市名称 | |     areaCode | String | 否 | 310118 | 区域编号 | |     areaName | String | 是 | 青浦区 | 区域名称 | |     address | String | 是 | 纪鹤公路1988号 | 详细地址 | |     lat | String | 是 | 36.221825 | 纬度 | |     lng | String | 是 | 120.632908 | 经度 | |     contactName | String | 否 | 张三 | 联系人 | |     contactMobile | String | 否 | 18801000001 | 联系人电话 | |     loadFlag | String | 是 | true | 装货标识 | |     unloadFlag | String | 是 | false | 卸货标识 | |     expectArrivalTime | Number | 否 | 1643251533306 | 预计到达时间，时间戳毫秒值 | |    expectDepartTime | Number | 否 | 1643251533306 | 预计发车时间，时间戳毫秒值 | |     sort | Number | 否 | 1 | 经停点顺序，如果不传则默认按数组顺序 | | goods | OrderGoods[] | 否 | | 订单货物信息 | |     barCode | String | 否 | 21616162626 | 商品条码 | |     skuId | String | 否 | 1223233536436 | 商品sku_id | |     name | String | 是 | 鞋子 | 货物名称 | |     packageType | String | 否 | | 包装规格 | |     piece | Number | 否 | 200 | 件数 | |     weight | Number | 否 | 200000 | 重量 | |     volume | Number | 否 | 50 | 体积 | | addService | OrderAddService[] | 否 | | 增值服务 | |     serviceType | String | 否 | | 服务类型 | |     serviceName | String | 是 | 包装服务 | 服务名称 | |     serviceDemand | String | 否 | 纸箱包装 | 服务要求 | | tags | OrderTag[] | 否 | | 订单标签 | |  tagName | String | 是 | 易碎物品 | 标签名称 | | vehicleDemands | OrderVehicleDemand[] | 否 | | 车辆需求 | |  demandVanType | String | 是 | MOTOR_VAN | 需求厢型：MOTOR_VAN/厢车,GAOLAN_VAN/高栏,SLAB_VAN/平板,REFRIGERATOR_CAR/冷藏,IVECO/依维柯,JINBEI/金杯,MINI_VAN/小面包,ELSE_VAN/其他 | |   demandSpecification | String | 是 | 9.6 | 需求车型：2.7/3.8/4.2/6.8/7.6/9.6/11/12.5/13.5/15/16.5/17.5/19/21 | |  demandNumber | Number | 否 | 1 | 为空则默认1 | |  vehicleDemand | String | 否 | 车辆需要带雨布 | 车辆要求描述 | ##### 请求示例 ###### Java-sdk方式 [下载SDK](https://zeyi-tms-product.oss-cn-hangzhou.aliyuncs.com/file/jar/java-sdk/zy-java-sdk-1.0.0.jar) ```java public class Sample { public static void main(String[] args_) { String appKey = "appkey"; String appSecret = "appSecret"; String jsonData = "下单Body参数JSON数据"; ZYClient zyClient = new ZYClient(appKey, appSecret); HttpResponseData httpResponseData = zyClient.doPost(Constants.TEST_HOST + "/oms-service-api/order/add", "accessToken", jsonData); if(httpResponseData == null) { throw new BusinessException("则一请求失败,返回结果为空!"); } if(httpResponseData.getStatus() == HttpURLConnection.HTTP_UNAUTHORIZED) { //重新获取token再次请求 httpResponseData = zyClient.doPost(Constants.TEST_HOST + "/oms-service-api/order/add", "accessToken", jsonData); } } } ``` ##### 返回示例 ```json { "success": true, "businessException": false, "errorCode": null, "message": null, "result": { "code": "则一订单号", "customerOrderCode": "客户订单号" } } ``` #### 确认中标 ##### 接口信息 ###### 请求方式： post ###### 请求地址： * 生产：https://gw.shjiuze.cn/oms-service-api/order/confirmBid * 测试：https://test.shjiuze.cn/oms-service-api/order/confirmBid ###### Headers参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ------------- | ------ | -------------------------- | -------------------------------- | ------------------------------------------------------------ | | Authorization | String | 是     | Bearer a2c5680001 | 调用服务端API的应用凭证accessToken，通过调用获取访问凭证接口获取。 | | appKey | String | 是 | 0867ef5f23ef6483749e19e1692b | 则一提供 | | timestamp | String | 是 | 1643251533306 | 当前时间戳毫秒值 | | nonce | String | 是 | gdst9t | 6位小写字母数字组合随机串 | | sign | String | 是 | fa3ed338d6dfe18e7273c8692234ee70 | 签名：appKey(则一提供) + appSecret(则一提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成 | ###### Body参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ----------------- | ------ | -------------------------- | ------------ | ------------------------ | | code | String | 是 | 220101000001 | 则一订单号 | | customerOrderCode | String | 是     | 220101000001 | 客户订单号，订单唯一标识 | | confirmId | String | 是 | 220101000001 | 中标报价id | | quotePrice | Number | 是 | 10000 | 中标价格 | ##### 请求示例 ###### Java-sdk方式 [下载SDK](https://zeyi-tms-product.oss-cn-hangzhou.aliyuncs.com/file/jar/java-sdk/zy-java-sdk-1.0.0.jar) ```java public class Sample { public static void main(String[] args_) { String appKey = "appkey"; String appSecret = "appSecret"; String jsonData = "确认中标Body参数JSON数据"; ZYClient zyClient = new ZYClient(appKey, appSecret); HttpResponseData httpResponseData = zyClient.doPost(Constants.TEST_HOST + "/oms-service-api/order/confirmBid", "accessToken", jsonData); if(httpResponseData == null) { throw new BusinessException("则一请求失败,返回结果为空!"); } if(httpResponseData.getStatus() == HttpURLConnection.HTTP_UNAUTHORIZED) { //重新获取token再次请求 httpResponseData = zyClient.doPost(Constants.TEST_HOST + "/oms-service-api/order/confirmBid", "accessToken", jsonData); } } } ``` ##### 返回示例 ```json { "success": true, "businessException": false, "errorCode": null, "message": null, "result": { "code": "则一订单号", "customerOrderCode": "客户订单号", "confirmId": "中标报价id", "quotePrice": "中标价格" } } ``` #### 确认运费接口 ##### 接口信息 ###### 概述 调用该接口确认最终运费信息。 ###### 请求方式： post ###### 请求地址： * 生产：https://gw.shjiuze.cn/oms-service-api/order/confirmFreight * 测试：https://test.shjiuze.cn/oms-service-api/order/confirmFreight ###### Headers参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ------------- | ------ | ---- | -------------------------------- | ------------------------------------------------------------ | | Authorization | String | 是 | Bearer a2c5680001 | 调用服务端API的应用凭证accessToken，通过调用获取访问凭证接口获取。 | | appKey | String | 是 | 0867ef5f23ef6483749e19e1692b | 则一提供 | | timestamp | String | 是 | 1643251533306 | 当前时间戳毫秒值 | | nonce | String | 是 | gdst9t | 6位小写字母数字组合随机串 | | sign | String | 是 | fa3ed338d6dfe18e7273c8692234ee70 | 签名：appKey(则一提供) + appSecret(则一提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成 | ###### Body参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | --------------------------------- | ------ | ---- | ------------ | ------------------------ | | code | String | 是 | 220101000001 | 则一订单号 | | customerOrderCode | String | 是 | 220101000001 | 客户订单号，订单唯一标识 | | totalBasePrice | Number | 是 | 10000 | 基础运费合计 | | totalExtraPrice | Number | 是 | 500 | 超里程运费合计 | | totalPrice | Number | 是 | 10500 | 运费总额 | | attachment | String | 否 | 图片url | 附件 | | freightList | Array | 是 | | 运费信息 | |     waybillCode | String | 是 | Y20220101001 | 运单号 | |     specification | String | 是 | 9.6 | 车型 | |     vanType | String | 是 | MOTOR_VAN | 箱型 | |     number | Number | 否 | 1 | 数量 | |     volume | Number | 否 | 30.256 | 方数 | |     weight | Number | 否 | 80 | 吨位 | |     baseUnit | String | 是 | car/kg/m³ | 基础单位 | |     baseUnitPrice | Number | 是 | 100 | 基础单价 | |     basePrice | Number | 是 | 10000 | 基础运费 | |     extraUnit | String | 否 | car/kg/m³ | 超里程单位 | |     extraUnitPrice | Number | 否 | 100 | 超里程单价 | |     extraPrice | Number | 否 | 1000 | 超里程运费 | ##### 请求示例 ###### Java-sdk方式 [下载SDK](https://zeyi-tms-product.oss-cn-hangzhou.aliyuncs.com/file/jar/java-sdk/zy-java-sdk-1.0.0.jar) ```java public class Sample { public static void main(String[] args_) { String appKey = "appkey"; String appSecret = "appSecret"; String jsonData = "确认运费Body参数JSON数据"; ZYClient zyClient = new ZYClient(appKey, appSecret); HttpResponseData httpResponseData = zyClient.doPost(Constants.TEST_HOST + "/oms-service-api/order/confirmFreight", "accessToken", jsonData); if(httpResponseData == null) { throw new BusinessException("则一请求失败,返回结果为空!"); } if(httpResponseData.getStatus() == HttpURLConnection.HTTP_UNAUTHORIZED) { //重新获取token再次请求 httpResponseData = zyClient.doPost(Constants.TEST_HOST + "/oms-service-api/order/confirmFreight", "accessToken", jsonData); } } } ``` ##### 返回示例 ```json { "success": true, "businessException": false, "errorCode": null, "message": null, "result": { "code": "则一订单号", "customerOrderCode": "客户订单号" } } ``` #### 取消订单 ##### 接口信息 ###### 请求方式： post ###### 请求地址： * 生产：https://gw.shjiuze.cn/oms-service-api/order/cancel * 测试：https://test.shjiuze.cn/oms-service-api/order/cancel ###### Headers参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ------------- | ------ | -------------------------- | -------------------------------- | ------------------------------------------------------------ | | Authorization | String | 是     | Bearer a2c5680001 | 调用服务端API的应用凭证accessToken，通过调用获取访问凭证接口获取。 | | appKey | String | 是 | 0867ef5f23ef6483749e19e1692b | 则一提供 | | timestamp | String | 是 | 1643251533306 | 当前时间戳毫秒值 | | nonce | String | 是 | gdst9t | 6位小写字母数字组合随机串 | | sign | String | 是 | fa3ed338d6dfe18e7273c8692234ee70 | 签名：appKey(则一提供) + appSecret(则一提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成 | ###### Body参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ----------------- | ------ | -------------------------- | ------------ | ------------------------ | | code | String | 是 | 220101000001 | 则一订单号 | | customerOrderCode | String | 是     | 220101000001 | 客户订单号，订单唯一标识 | | cancelRemark | String | 否 | 货量不足 | 取消原因 | ##### 请求示例 ###### Java-sdk方式 [下载SDK](https://zeyi-tms-product.oss-cn-hangzhou.aliyuncs.com/file/jar/java-sdk/zy-java-sdk-1.0.0.jar) ```java public class Sample { public static void main(String[] args_) { String appKey = "appkey"; String appSecret = "appSecret"; String jsonData = "取消订单Body参数JSON数据"; ZYClient zyClient = new ZYClient(appKey, appSecret); HttpResponseData httpResponseData = zyClient.doPost(Constants.TEST_HOST + "/oms-service-api/order/cancel", "accessToken", jsonData); if(httpResponseData == null) { throw new BusinessException("则一请求失败,返回结果为空!"); } if(httpResponseData.getStatus() == HttpURLConnection.HTTP_UNAUTHORIZED) { //重新获取token再次请求 httpResponseData = zyClient.doPost(Constants.TEST_HOST + "/oms-service-api/order/cancel", "accessToken", jsonData); } } } ``` ##### 返回示例 ```json { "success": true, "businessException": false, "errorCode": null, "message": null, "result": { "code": "则一订单号", "customerOrderCode": "客户订单号" } } ``` #### 查询车辆定位 ##### 接口信息 ###### 概述 可以通过该接口查询车辆当前位置，该接口为收费接口。 ###### 请求方式： post ###### 请求地址： * 生产：https://gw.shjiuze.cn/oms-service-api/vehicle/location * 测试：https://test.shjiuze.cn/oms-service-api/vehicle/location ###### Headers参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ------------- | ------ | -------------------------- | -------------------------------- | ------------------------------------------------------------ | | Authorization | String | 是     | Bearer a2c5680001 | 调用服务端API的应用凭证accessToken，通过调用获取访问凭证接口获取。 | | appKey | String | 是 | 0867ef5f23ef6483749e19e1692b | 则一提供 | | timestamp | String | 是 | 1643251533306 | 当前时间戳毫秒值 | | nonce | String | 是 | gdst9t | 6位小写字母数字组合随机串 | | sign | String | 是 | fa3ed338d6dfe18e7273c8692234ee70 | 签名：appKey(则一提供) + appSecret(则一提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成 | ###### Body参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ----------------- | ------ | ---- | ------------- | ------------------------ | | code | String | 是 | D220101000001 | 则一订单号 | | waybillCode | String | 是 | Y220101000001 | 则一运单号 | | customerOrderCode | String | 是 | 220101000001 | 客户订单号，订单唯一标识 | | licenseNumber | String | 是 | 沪DP2312 | 车牌号 | ##### 请求示例 ###### Java-sdk方式 [下载SDK](https://zeyi-tms-product.oss-cn-hangzhou.aliyuncs.com/file/jar/java-sdk/zy-java-sdk-1.0.0.jar) ```java public class Sample { public static void main(String[] args_) { String appKey = "appkey"; String appSecret = "appSecret"; String jsonData = "车辆位置查询Body参数JSON数据"; ZYClient zyClient = new ZYClient(appKey, appSecret); HttpResponseData httpResponseData = zyClient.doPost(Constants.TEST_HOST + "/oms-service-api/vehicle/location", "accessToken", jsonData); if(httpResponseData == null) { throw new BusinessException("则一请求失败,返回结果为空!"); } if(httpResponseData.getStatus() == HttpURLConnection.HTTP_UNAUTHORIZED) { //重新获取token再次请求 httpResponseData = zyClient.doPost(Constants.TEST_HOST + "/oms-service-api/vehicle/location", "accessToken", jsonData); } } } ``` ##### 返回示例 ```json { "success":true, "businessException":false, "result":{ "lng":"106.1722328011559", //经度 "lat":"37.94834927106783", //纬度 "speed":0, //速度，km/h "time":"2022-02-07 19:33:19", //定位时间 "address":"宁夏回族自治区吴忠市利通区清二沟,东方向,296.5米" //定位地点 } } ``` #### 查询车辆历史轨迹 ##### 接口信息 ###### 概述 可以通过该接口查询车辆历史运行轨迹数据，该接口为收费接口。 ###### 请求方式： post ###### 请求地址： * 生产：https://gw.shjiuze.cn/oms-service-api/vehicle/track * 测试：https://test.shjiuze.cn/oms-service-api/vehicle/track ###### Headers参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ------------- | ------ | -------------------------- | -------------------------------- | ------------------------------------------------------------ | | Authorization | String | 是     | Bearer a2c5680001 | 调用服务端API的应用凭证accessToken，通过调用获取访问凭证接口获取。 | | appKey | String | 是 | 0867ef5f23ef6483749e19e1692b | 则一提供 | | timestamp | String | 是 | 1643251533306 | 当前时间戳毫秒值 | | nonce | String | 是 | gdst9t | 6位小写字母数字组合随机串 | | sign | String | 是 | fa3ed338d6dfe18e7273c8692234ee70 | 签名：appKey(则一提供) + appSecret(则一提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成 | ###### Body参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ----------------- | ------ | ---- | ------------- | ------------------------ | | code | String | 是 | D220101000001 | 则一订单号 | | waybillCode | String | 是 | Y220101000001 | 则一运单号 | | customerOrderCode | String | 是 | 220101000001 | 客户订单号，订单唯一标识 | | licenseNumber | String | 是 | 沪DP2312 | 车牌号 | | startTime | Number | 是 | 1643251533306 | 开始时间 | | endTime | Number | 是 | 1643251533308 | 结束时间 | ##### 请求示例 ###### Java-sdk方式 [下载SDK](https://zeyi-tms-product.oss-cn-hangzhou.aliyuncs.com/file/jar/java-sdk/zy-java-sdk-1.0.0.jar) ```java public class Sample { public static void main(String[] args_) { String appKey = "appkey"; String appSecret = "appSecret"; String jsonData = "车辆轨迹查询Body参数JSON数据"; ZYClient zyClient = new ZYClient(appKey, appSecret); HttpResponseData httpResponseData = zyClient.doPost(Constants.TEST_HOST + "/oms-service-api/vehicle/track", "accessToken", jsonData); if(httpResponseData == null) { throw new BusinessException("则一请求失败,返回结果为空!"); } if(httpResponseData.getStatus() == HttpURLConnection.HTTP_UNAUTHORIZED) { //重新获取token再次请求 httpResponseData = zyClient.doPost(Constants.TEST_HOST + "/oms-service-api/vehicle/track", "accessToken", jsonData); } } } ``` ##### 返回示例 ```json { "success":true, "businessException":false, "result":[ { "lon":"116.6709722499687", //经度 "lat":"39.64092201495669", //纬度 "gtm":"2022-02-07 18:55:13", //gps时间 "spd":"249", //速度 除以10为km/h "hgt":"4", //海拔m "agl":"257" //正北方向夹角 }, { "lon":"116.66919560752942", "lat":"39.64070361333219", "gtm":"2022-02-07 18:55:33", "spd":"272", "hgt":"6", "agl":"260" } ] } ``` #### 查询订单操作记录 ##### 接口信息 ###### 概述 可以通过该接口查询订单的操作记录。 ###### 请求方式： post ###### 请求地址： * 生产：https://gw.shjiuze.cn/oms-service-api/order/getOperateList * 测试：https://test.shjiuze.cn/oms-service-api/order/getOperateList ###### Headers参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ------------- | ------ | -------------------------- | -------------------------------- | ------------------------------------------------------------ | | Authorization | String | 是     | Bearer a2c5680001 | 调用服务端API的应用凭证accessToken，通过调用获取访问凭证接口获取。 | | appKey | String | 是 | 0867ef5f23ef6483749e19e1692b | 则一提供 | | timestamp | String | 是 | 1643251533306 | 当前时间戳毫秒值 | | nonce | String | 是 | gdst9t | 6位小写字母数字组合随机串 | | sign | String | 是 | fa3ed338d6dfe18e7273c8692234ee70 | 签名：appKey(则一提供) + appSecret(则一提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成 | ###### Body参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ----------------- | ------ | ---- | ------------ | ------------------------ | | code | String | 否 | 220101000001 | 则一订单号 | | customerOrderCode | String | 是 | 220101000001 | 客户订单号，订单唯一标识 | ##### 请求示例 ###### Java-sdk方式 [下载SDK](https://zeyi-tms-product.oss-cn-hangzhou.aliyuncs.com/file/jar/java-sdk/zy-java-sdk-1.0.0.jar) ```java public class Sample { public static void main(String[] args_) { String appKey = "appkey"; String appSecret = "appSecret"; String jsonData = "车辆轨迹查询Body参数JSON数据"; ZYClient zyClient = new ZYClient(appKey, appSecret); HttpResponseData httpResponseData = zyClient.doPost(Constants.TEST_HOST + "/oms-service-api/orderOperateRecord/getList", "accessToken", jsonData); if(httpResponseData == null) { throw new BusinessException("则一请求失败,返回结果为空!"); } if(httpResponseData.getStatus() == HttpURLConnection.HTTP_UNAUTHORIZED) { //重新获取token再次请求 httpResponseData = zyClient.doPost(Constants.TEST_HOST + "/oms-service-api/orderOperateRecord/getList", "accessToken", jsonData); } } } ``` ##### 返回示例 ```json { "success": true, "businessException": false, "errorCode": null, "message": null, "result": [ { "orderCode": "220101000001", "operateType": "ORDER_XXX", "operateContent": "操作详情XXXX1", "operateTime": "2022-02-10 18:23:30", "operateUser": "张三" }, { "orderCode": "220101000001", "operateType": "ORDER_XXX", "operateContent": "操作详情XXXX2", "operateTime": "2022-02-08 12:43:30", "operateUser": "李四" } ] } ``` ### 以下接口需要对接方提供 #### 报价接口 ##### 接口信息 ###### 概述 则一调用该接口进行报价，可以进行多次报价。 ###### 请求方式： post ###### 请求路径： /quotePrice ###### Body参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ----------------- | ------ | -------------------------- | ------------- | ------------------------ | | code | String | 是 | 220101000001 | 则一订单号 | | customerOrderCode | String | 是     | 220101000001 | 客户订单号，订单唯一标识 | | quoteId | String | 是 | 1a2111bacd56 | 报价id，报价唯一标识 | | quotePrice | Number | 是 | 10000 | 报价金额 | | contactName | String | 否 | 张三 | 报价联系人 | | contactMobile | String | 否 | 18801000000 | 报价联系电话 | | quoteInvalidTime | Number | 否 | 1643251533306 | 报价有效期，时间戳毫秒值 | | operateTime | Number | 是 | 1643251533306 | 操作时间戳 | ###### 返回示例 ```json { "success": true, "businessException": false, "errorCode": null, "message": null, "result": { "code": "则一订单号", "customerOrderCode": "客户订单号" } } ``` #### 报价接口V2 ##### 接口信息 ###### 概述 则一调用该接口进行报价，可以进行多次报价。 ###### 请求方式： post ###### 请求路径： /quotePrice ###### Body参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | --------------------------------- | ------ | ---- | ------------- | ------------------------ | | code | String | 是 | 220101000001 | 则一订单号 | | customerOrderCode | String | 是 | 220101000001 | 客户订单号，订单唯一标识 | | quoteId | String | 是 | 112242536364 | 报价id，报价唯一标识 | | quoteInvalidTime | Number | 否 | 1643251533306 | 报价有效期，时间戳毫秒值 | | contactName | String | 否 | 张三 | 报价联系人 | | contactMobile | String | 否 | 18801733668 | 报价联系人电话 | | operateTime | Number | 是 | 1643251533306 | 操作报价时间戳毫秒值 | | attachment | String | 否 | 图片url | 附件 | | freightList | Array | 是 | | 运费信息 | |     waybillCode | String | 是 | Y20220101001 | 运单号(子单号) | |     specification | String | 是 | 17.5 | 车型 | |     vanType | String | 是 | MOTOR_VAN | 箱型 | |     number | Number | 否 | 1 | 数量 | |     volume | Number | 否 | 30.256 | 方数 | |     weight | Number | 否 | 80 | 吨位 | |     baseUnit | String | 是 | car/kg/m³ | 基础单位 | |     baseUnitPrice | Number | 是 | 100 | 基础单价 | |     basePrice | Number | 否 | 10000 | 基础运费 | |     extraUnit | String | 否 | car/kg/m³ | 超里程单位 | |     extraUnitPrice | Number | 否 | 100 | 超里程单价 | ###### 返回示例 ```json { "success": true, "businessException": false, "errorCode": null, "message": null, "result": { "code": "则一订单号", "customerOrderCode": "客户订单号" } } ``` #### 接单接口 ##### 接口信息 ###### 概述 则一调用该接口推送运单号及参考运费范围。 ###### 请求方式： post ###### 请求路径： /receiveOrder ###### Body参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | -------------------------------- | --------- | -------------------------- | ------------- | ------------------------ | | code | String | 是 | 220101000001 | 则一订单号 | | customerOrderCode | String | 是     | 220101000001 | 客户订单号，订单唯一标识 | | startTotalPrice | Number | 是    | 18100 | 参考总金额起始值 | | endTotalPrice | Number | 是    | 21000 | 参考总金额结束值 | | WaybillList | Waybill[] | 是 | | 运单集合 | |     waybillCode | String | 是 | Y220101000001 | 则一运单号 | |     startPrice | Number | 是 | 18100 | 参考金额起始值 | |     endPrice | Number | 是 | 21000 | 参考总金额结束值 | |     vanType | String | 是 | MOTOR_VAN | 厢型 | |     specification | String | 是 | 9.6 | 车型 | ###### 返回示例 ```json { "success": true, "businessException": false, "errorCode": null, "message": null, "result": { "code": "则一订单号", "customerOrderCode": "客户订单号" } } ``` #### 推送司机车辆信息 ##### 接口信息 ###### 概述 则一调用该接口推送订单司机和车辆信息，可以进行多次推送，以操作时间戳最新一次推送的司机车辆信息为准。 ###### 请求方式： post ###### 请求路径： /assignVehicle ###### Body参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | -------------------- | ------ | -------------------------- | ------------- | ------------------------ | | code | String | 是 | 220101000001 | 则一订单号 | | waybillCode | String | 是  | Y220101000001 | 则一运单号 | | customerOrderCode | String | 是     | 220101000001 | 客户订单号，订单唯一标识 | | driverName | String | 是 | 张三 | 司机姓名 | | driverMobile | String | 是 | 18801000000 | 司机手机号 | | licenseNumber | String | 是 | 沪DP2312 | 车牌号 | | trailerLicenseNumber | String | 否 | 陕K7C72挂 | 挂车车牌号 | | operateTime | Number | 是 | 1643251533306 | 操作时间戳 | | weight | Number | 否 | 200000 | 重量 | | volume | Number | 否 | 16 | 体积 | ###### 返回示例 ```json { "success": true, "businessException": false, "errorCode": null, "message": null, "result": { "code": "则一订单号", "waybillCode": "则一运单号", "customerOrderCode": "客户订单号" } } ``` #### 推送靠站信息 ##### 接口信息 ###### 概述 则一调用该接口推送靠站签到数据。 ###### 请求方式： post ###### 请求路径： /againstStation ###### Body参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ----------------- | ------ | ---- | ------------- | ------------------------ | | code | String | 是 | 220101000001 | 则一订单号 | | waybillCode | String | 是 | Y220101000001 | 则一运单号 | | customerOrderCode | String | 是 | 220101000001 | 客户订单号，订单唯一标识 | | signTime | Number | 是 | 1643251533306 | 靠站签到时间戳 | | operateTime | Number | 是 | 1643251533306 | 操作时间戳 | ###### 返回示例 ```json { "success": true, "businessException": false, "errorCode": null, "message": null, "result": { "code": "则一订单号", "waybillCode": "则一运单号", "customerOrderCode": "客户订单号" } } ``` #### 推送发车信息 ##### 接口信息 ###### 概述 则一调用该接口推送发车运输数据。 ###### 请求方式： post ###### 请求路径： /departVehicle ###### Body参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ----------------- | ------ | -------------------------- | ------------- | ------------------------ | | code | String | 是 | 220101000001 | 则一订单号 | | waybillCode | String | 是   | Y220101000001 | 则一运单号 | | customerOrderCode | String | 是     | 220101000001 | 客户订单号，订单唯一标识 | | departTime | Number | 是 | 1643251533306 | 发车时间戳 | | operateTime | Number | 是 | 1643251533306 | 操作时间戳 | | weight | Number | 否 | 200000 | 重量 | | volume | Number | 否 | 16 | 体积 | ###### 返回示例 ```json { "success": true, "businessException": false, "errorCode": null, "message": null, "result": { "code": "则一订单号", "waybillCode": "则一运单号", "customerOrderCode": "客户订单号" } } ``` #### 推送到车信息 ##### 接口信息 ###### 概述 则一调用该接口推送到达数据。 ###### 请求方式： post ###### 请求路径： /arriveVehicle ###### Body参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ----------------- | ------ | -------------------------- | ------------- | ------------------------ | | code | String | 是 | 220101000001 | 则一订单号 | | waybillCode | String | 是    | Y220101000001 | 则一运单号 | | customerOrderCode | String | 是     | 220101000001 | 客户订单号，订单唯一标识 | | arriveTime | Number | 是 | 1643251533306 | 到车时间戳 | | operateTime | Number | 是 | 1643251533306 | 操作时间戳 | ###### 返回示例 ```json { "success": true, "businessException": false, "errorCode": null, "message": null, "result": { "code": "则一订单号", "waybillCode": "则一运单号", "customerOrderCode": "客户订单号" } } ``` #### 推送卸车信息 ##### 接口信息 ###### 概述 则一调用该接口推送卸车数据。 ###### 请求方式： post ###### 请求路径： /unload ###### Body参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ----------------- | ------ | ---- | ------------- | ------------------------ | | code | String | 是 | 220101000001 | 则一订单号 | | waybillCode | String | 是 | Y220101000001 | 则一运单号 | | customerOrderCode | String | 是 | 220101000001 | 客户订单号，订单唯一标识 | | unloadTime | Number | 是 | 1643251533306 | 卸车时间戳 | | operateTime | Number | 是 | 1643251533306 | 操作时间戳 | ###### 返回示例 ```json { "success": true, "businessException": false, "errorCode": null, "message": null, "result": { "code": "则一订单号", "waybillCode": "则一运单号", "customerOrderCode": "客户订单号" } } ``` #### 推送签收信息 ##### 接口信息 ###### 概述 则一调用该接口推送签收数据。 ###### 请求方式： post ###### 请求路径： /sign ###### Body参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ----------------- | ------ | ---- | ----------------------------- | ------------------------ | | code | String | 是 | 220101000001 | 则一订单号 | | waybillCode | String | 是 | Y220101000001 | 则一运单号 | | customerOrderCode | String | 是 | 220101000001 | 客户订单号，订单唯一标识 | | receiptAttachment | String | 是 | https://12.jpg,https://11.jpg | 回单文件地址 | | signTime | Number | 是 | 1643251533306 | 签收时间戳 | | operateTime | Number | 是 | 1643251533306 | 操作时间戳 | ###### 返回示例 ```json { "success": true, "businessException": false, "errorCode": null, "message": null, "result": { "code": "则一订单号", "waybillCode": "则一运单号", "customerOrderCode": "客户订单号" } } ``` #### 推送运费信息 ##### 接口信息 ###### 概述 则一调用该接口推送最终运费信息。 ###### 请求方式： post ###### 请求路径： /receiveFreight ###### Body参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | -------------------------------------- | ------ | ---- | ------------ | ------------------------ | | code | String | 是 | 220101000001 | 则一订单号 | | customerOrderCode | String | 是 | 220101000001 | 客户订单号，订单唯一标识 | | totalBasePrice | Number | 是 | 10000 | 基础运费合计 | | totalExtraPrice | Number | 是 | 500 | 超里程运费合计 | | totalPrice | Number | 是 | 10500 | 运费总额 | | attachment | String | 否 | 图片url | 附件 | | freightList | Array | 是 | | 运费信息 | |     waybillCode | String | 是 | Y20220101001 | 运单号 | |     specification | String | 是 | 9.6 | 车型 | |     vanType | String | 是 | MOTOR_VAN | 箱型 | |     number | Number | 否 | 1 | 数量 | |     volume | Number | 否 | 30.256 | 方数 | |     weight | Number | 否 | 80 | 吨位 | |     baseUnit | String | 是 | car/kg/m³ | 基础单位 | |     baseUnitPrice | Number | 是 | 100 | 基础单价 | |     basePrice | Number | 是 | 10000 | 基础运费 | |     extraUnit | String | 否 | car/kg/m³ | 超里程单位 | |     extraUnitPrice | Number | 否 | 100 | 超里程单价 | |     extraPrice | Number | 否 | 1000 | 超里程运费 | ###### 返回示例 ```json { "success": true, "businessException": false, "errorCode": null, "message": null, "result": { "code": "则一订单号", "customerOrderCode": "客户订单号" } } ``` ### Java-sdk下载 [zy-java-sdk](https://zeyi-tms-product.oss-cn-hangzhou.aliyuncs.com/file/jar/java-sdk/zy-java-sdk-1.0.0.jar) ### 2022-03-09更新日志 为了保证接口的通用性，本次涉及到改动的信息如下 - [x] 下单接口：接口返回值移除子单集合，通过接单接口推送。 - [x] 接单接口：由推送参考价改为接单接口，推送运单集合及每个运单的参考价格。 - [x] 对接接口中子单号subCode参数命名更改为运单号waybillCode。 ### 2023-02-22更新日志 - [x] 增加报价接口V2版本 - [x] 增加推送运费信息接口 - [x] 增加确认运费接口 ### 2023-05-06更新日志 - [x] 增加靠站签到接口 - [x] 增加卸车确认接口 - [x] 增加签收接口