From d6fdb4e4e891c8807cd13081433f978fe3c370cd Mon Sep 17 00:00:00 2001 From: 王富国 Date: Tue, 23 May 2023 16:27:29 +0800 Subject: [PATCH] feat: 添加希音订单接口 --- order/truck/shein/order.md | 342 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 342 insertions(+), 0 deletions(-) create mode 100644 order/truck/shein/order.md diff --git a/order/truck/shein/order.md b/order/truck/shein/order.md new file mode 100644 index 0000000..36a7583 --- /dev/null +++ b/order/truck/shein/order.md @@ -0,0 +1,342 @@ + + +[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/shein/add +* 测试：https://test.shjiuze.cn/oms-service-api/shein/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 | 是     | ZY2301010001 | 任务编号 | +| 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 | 否 | 需要雨布和尾板 | 订单备注 | +| loadAddress | Object[] | 是 | | 装货地址信息 | +|     stationId | String | 是 | 11212abc | 园区id | +|     stationName | String | 是 | 高明新宜园区 | 园区名称 | +|     addressId | String | 是 | 123abc | 地址id | +|     addressName | String | 是 | 高明新宜园区-新宜6号仓-二楼18号门 | 装货地址名称 | +|     lat | String | 是 | 36.221825 | 纬度(GPS坐标系：高德的，GCJ-02) | +|     lng | String | 是 | 120.632908 | 经度(GPS坐标系：高德的，GCJ-02) | +|     contactName | String | 否 | 张三 | 联系人 | +|     contactMobile | String | 否 | 18801000001 | 联系人电话 | +|     expectArrivalTime | Number | 否 | 1643251533306 | 预计到达时间，时间戳毫秒值 | +|     expectDepartTime | Number | 否 | 1643251533306 | 预计发车时间，时间戳毫秒值 | +|     sort | Number | 否 | 1 | 经停点顺序，如果不传则默认按数组顺序 | +| unloadAddress | Object[] | 是 | | 卸货地址信息 | +|     stationId | String | 是 | 11212abc | 园区id | +|     stationName | String | 是 | 高明新宜园区 | 园区名称 | +|     addressId | String | 是 | 123abc | 地址id | +|     addressName | String | 是 | 高明新宜园区-新宜6号仓-二楼18号门 | 卸货地址名称 | +|     lat | String | 是 | | 纬度(GPS坐标系：高德的，GCJ-02) | +|     lng | String | 是 | | 经度(GPS坐标系：高德的，GCJ-02) | +|     contactName | String | 否 | | 联系人 | +|     contactMobile | String | 否 | | 联系人电话 | +|     expectArrivalTime | Number | 否 | | 预计到达时间，时间戳毫秒值 | +|     expectDepartTime | Number | 否 | | 预计发车时间，时间戳毫秒值 | +|     sort | Number | 否 | 1 | 经停点顺序，如果不传则默认按数组顺序 | +| goods | Object[] | 否 | | 订单货物信息 | +|     barCode | String | 否 | 21616162626 | 商品条码 | +|     skuId | String | 否 | 1223233536436 | 商品sku_id | +|     name | String | 是 | 鞋子 | 货物名称 | +|     packageType | String | 否 | | 包装规格 | +|     piece | Number | 否 | 200 | 件数 | +|     weight | Number | 否 | 200000 | 重量 | +|     volume | Number | 否 | 50 | 体积 | +| addService | Object[] | 否 | | 增值服务 | +|     serviceType | String | 否 | | 服务类型 | +|     serviceName | String | 是 | 包装服务 | 服务名称 | +|     serviceDemand | String | 否 | 纸箱包装 | 服务要求 | +| tags | Object[] | 否 | | 订单标签 | +|  tagName | String | 是 | 易碎物品 | 标签名称 | +| 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 | 否 | 车辆需要带雨布 | 车辆要求描述 | +| vehicleCode | String | 否 | 12313 | 车辆编号 | +| vehicleLicenseNum | String | 否 | 沪DP2312 | 车牌号 | +| driverCode | String | 否 | 123123 | 司机编号 | +| driverName | String | 否 | 张三 | 司机姓名 | +| driverMobile | String | 否 | 18801733666 | 司机电话 | + +##### 请求示例 + +###### 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/shein/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/shein/add", "accessToken", jsonData); + } + } +} +``` + +##### 返回示例 + +```json +{ + "success": true, + "businessException": false, + "errorCode": null, + "message": null, + "result": { + "code": "则一订单号", + "customerOrderCode": "任务单号" + } +} +``` + +#### 取消订单 + +##### 接口信息 + +###### 请求方式： + +post + +###### 请求地址： + +* 生产：https://gw.shjiuze.cn/oms-service-api/shein/cancel +* 测试：https://test.shjiuze.cn/oms-service-api/shein/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参数 + +| 名称 | 类型 | 必填 | 示例值 | 描述 | +| ----------------- | ------ | -------------------------- | ------------ | -------- | +| customerOrderCode | String | 是     | ZY2301010001 | 任务单号 | +| cancelRemark | String | 否 | 货量不足 | 取消原因 | +| contact | String | 否 | 张三 | 联系人 | +| contactMobile | String | 否 | 18801733666 | 联系电话 | + +##### 请求示例 + +###### 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/shein/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/shein/cancel", "accessToken", jsonData); + } + } +} +``` + +##### 返回示例 + +```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) + + + +### 2023-05-06更新日志 + +- [x] 增加靠站签到接口 +- [x] 增加卸车确认接口 +- [x] 增加签收接口 \ No newline at end of file -- libgit2 0.21.0