[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/jgwl/inquiryNotice * 测试：https://test.shjiuze.cn/oms-service-api/jgwl/inquiryNotice ###### 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参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ------------- | ------- | ---- | ------------- | ---------------------- | | id | String | 是 | 1112122324252 | 流水号 | | inquiryCode | String | 是 | 220101000001 | 询价单号 | | type | Integer | 是 | 100 | 类型 | | operationTime | Number | 否 | 1643251533306 | 操作时间，时间戳毫秒值 | ##### 请求示例 ###### 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/jgwl/inquiryNotice", "accessToken", jsonData); if(httpResponseData == null) { throw new BusinessException("则一请求失败,返回结果为空!"); } if(httpResponseData.getStatus() == HttpURLConnection.HTTP_UNAUTHORIZED) { //重新获取token再次请求 httpResponseData = zyClient.doPost(Constants.TEST_HOST + "/oms-service-api/jgwl/inquiryNotice", "accessToken", jsonData); } } } ``` ##### 返回示例 ```json { "success": true, "businessException": false, "errorCode": null, "message": null, "result": { "id": "流水号", "inquiryCode": "询价单号", "type": 100 } } ``` #### 运费确认接口 ##### 接口信息 ###### 概述 调用该接口确认运费信息。 ###### 请求方式： post ###### 请求地址： * 生产：https://gw.shjiuze.cn/oms-service-api/jgwl/confirmFreight * 测试：https://test.shjiuze.cn/oms-service-api/jgwl/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参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ------------- | ------- | ---- | ------------- | -------- | | id | String | 是 | 1112122324252 | 流水号 | | inquiryCode | String | 是 | 220101000001 | 询价单号 | | type | Integer | 是 | 1 | 类型 | | operationTime | Number | 是 | 1643251533306 | 操作时间 | ##### 请求示例 ###### 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/jgwl/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/jgwl/confirmFreight", "accessToken", jsonData); } } } ``` ##### 返回示例 ```json { "success": true, "businessException": false, "errorCode": null, "message": null, "result": { "inquiryCode": "询价单号", "type": "类型" } } ``` #### 推送发车/到车信息 ##### 接口信息 ###### 概述 调用该接口推送发车运输以及到达数据。 ###### 请求方式： post ###### 请求地址： * 生产：https://gw.shjiuze.cn/oms-service-api/jgwl/operationRecord * 测试：https://test.shjiuze.cn/oms-service-api/jgwl/operationRecord ###### Body参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ------------- | ------- | -------------- | ------------- | ---------------------- | | id | String | 是 | 1222222122122 | 流水号 | | inquiryCode | String | 是 | 220101000001 | 询价单号 | | waybillCode | String | 是   | Y220101000001 | 运单号 | | type | Integer | 是 | 1 | 类型 | | departTime | Number | 否 | 1643251533306 | 发车时间戳（发车必填） | | arrivalTime | Number | 否 | 1643251533306 | 到车时间戳（到达必填） | | operationTime | Number | 是 | 1643251533306 | 操作时间戳 | ##### 请求示例 ###### 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/jgwl/operationRecord", "accessToken", jsonData); if(httpResponseData == null) { throw new BusinessException("则一请求失败,返回结果为空!"); } if(httpResponseData.getStatus() == HttpURLConnection.HTTP_UNAUTHORIZED) { //重新获取token再次请求 httpResponseData = zyClient.doPost(Constants.TEST_HOST + "/oms-service-api/jgwl/operationRecord", "accessToken", jsonData); } } } ``` ###### 返回示例 ```json { "success": true, "businessException": false, "errorCode": null, "message": null, "result": { "inquiryCode": "询价单号", "waybillCode": "运单号" } } ``` ### 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) ### 2023-04-21更新日志 初始化接口