From 56b7e0fe46864b43b334d738f7f9824351a1db67 Mon Sep 17 00:00:00 2001 From: wangfuguo Date: Thu, 1 Sep 2022 13:49:50 +0800 Subject: [PATCH] feat: 添加通鲁仓储订单对接接口 --- order/warehouse/2022083101/仓储接口.md | 539 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 539 insertions(+), 0 deletions(-) create mode 100644 order/warehouse/2022083101/仓储接口.md diff --git a/order/warehouse/2022083101/仓储接口.md b/order/warehouse/2022083101/仓储接口.md new file mode 100644 index 0000000..bc68961 --- /dev/null +++ b/order/warehouse/2022083101/仓储接口.md @@ -0,0 +1,539 @@ +[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" + } +} +``` + +## 入库下单 + +### 简要描述 + +入库单创建接口 + +### 请求URL + +· 测试环境：https://test.shjiuze.cn/oms-service-api/warehouseOrder/inStock + +· 生产环境：https://gw.shjiuze.cn/oms-service-api/warehouseOrder/inStock + +### 请求方式 + +POST + +### Headers参数 + +| 名称 | 类型 | 必填 | 示例值 | 描述 | +| ------------- | ------ | -------------------------- | -------------------------------- | ------------------------------------------------------------ | +| Authorization | String | 是     | Bearer a2c5680001 | 调用服务端API的应用凭证accessToken，通过调用获取访问凭证接口获取。 | +| appKey | String | 是 | 0867ef5f23ef446483749e19e1692b40 | 则一提供 | +| timestamp | String | 是 | 1643251533306 | 当前时间戳毫秒值 | +| nonce | String | 是 | gdst9t | 6位小写字母数字组合随机串 | +| sign | String | 是 | fa3ed338d6dfe18e7273c8692234ee70 | 签名：appKey(则一提供) + appSecret(则一提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成 | + +### Body参数 + +| 参数名 | 必传 | 类型 | 说明 | +| ------------------------------------------ | ---- | ------ | ----------------------------------------- | +| code | 是 | string | 客户单号 | +| supplier | 否 | string | 供应商名称 | +| planTime | 否 | string | 预计操作日期时间戳(毫秒)-->入库通知日期 | +| billTime | 否 | string | 单据日期时间戳(毫秒)(如无默认当前时间) | +| remark | 否 | String | 备注 | +| goodList | 是 | list | 商品集合 | +|     warehouseCode | 是 | string | 仓库编号 | +|     warehouseAreaCode | 否 | string | 库区编号 | +|     warehouseLocCode | 否 | string | 库位编号 | +|     warehouseStatus | 是 | string | 库存状态（KCZ00 【正常】、KCZ01【冻结】） | +|     code | 是 | string | 商品编码 | +|     name | 否 | string | 商品名称 | +|     barCode | 否 | string | 商品条码 | +|     packageType | 否 | string | 包装规格 | +|     unit | 否 | string | 单位 | +|     produceDate | 否 | string | 生产日期时间戳(毫秒) | +|     expiryDate | 否 | string | 过期日期时间戳(毫秒) | +|     stockCount | 是 | int | 入库数量 | +|     weight | 否 | int | 重量 | +|     volume | 否 | int | 体积 | +|     transactionSubCode | 否 | string | 交易子单号(PO号) | +|     lineNumber | 否 | string | 单据行号 | +|     batchNumber | 否 | string | 批次号 | +|     pciCode | 否 | string | pciCode | +|     factoryLineNumber | 否 | string | 工厂行号 | +|     remark | 否 | string | 备注 | + +### 返回结果正常示例 + + { "success": true, "businessException": false} + +### 返回结果异常示例 + + { "success": false, "businessException": true, "errorCode": "500", "message": "XXX异常!"} + +### 请求示例 + +#### 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/warehouseOrder/inStock", "accessToken", jsonData); + if(httpResponseData == null) { + throw new BusinessException("则一请求失败,返回结果为空!"); + } + if(httpResponseData.getStatus() == HttpURLConnection.HTTP_UNAUTHORIZED) { + //重新获取token再次请求 + httpResponseData = zyClient.doPost(Constants.TEST_HOST + + "/oms-service-api/warehouseOrder/inStock", "accessToken", jsonData); + } + } +} +``` + + + +## 出库下单 + +### 简要描述 + +出库单创建接口 + +### 请求URL + +· 测试环境：https://test.shjiuze.cn/oms-service-api/warehouseOrder/outStock + +· 生产环境：https://gw.shjiuze.cn/oms-service-api/warehouseOrder/outStock + +### 请求方式 + +POST + +### Headers参数 + +| 名称 | 类型 | 必填 | 示例值 | 描述 | +| ------------- | ------ | -------------------------- | -------------------------------- | ------------------------------------------------------------ | +| Authorization | String | 是     | Bearer a2c5680001 | 调用服务端API的应用凭证accessToken，通过调用获取访问凭证接口获取。 | +| appKey | String | 是 | 0867ef5f23ef446483749e19e1692b40 | 则一提供 | +| timestamp | String | 是 | 1643251533306 | 当前时间戳毫秒值 | +| nonce | String | 是 | gdst9t | 6位小写字母数字组合随机串 | +| sign | String | 是 | fa3ed338d6dfe18e7273c8692234ee70 | 签名：appKey(则一提供) + appSecret(则一提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成 | + +### Body参数 + +| 参数名 | 必传 | 类型 | 说明 | +| ------------------------------------------ | ---- | ------ | ----------------------------------------- | +| code | 是 | string | 客户单号 | +| supplier | 否 | string | 供应商 | +| receiverCustomerCode | 是 | string | 收货客户编号 | +| receiver | 是 | string | 收货人 | +| receiverMobile | 否 | string | 收货人电话 | +| receiverAddress | 是 | string | 收货地址 | +| planTime | 否 | string | 预计操作时间-->入库通知日期 | +| billTime | 否 | string | 单据日期时间戳(毫秒)(如无默认当前时间) | +| cityCode | 否 | string | 城市编码 | +| bgm | 是 | string | 消息编号 | +| remark | 否 | string | 备注 | +| goodList | 是 | list | 商品集合 | +|     warehouseCode | 是 | string | 仓库编号 | +|     warehouseAreaCode | 否 | string | 库区编号 | +|     warehouseLocCode | 否 | string | 库位编号 | +|     warehouseStatus | 是 | string | 库存状态（KCZ00 【正常】、KCZ01【冻结】） | +|     code | 是 | string | 商品编码 | +|     name | 否 | string | 商品名称 | +|     barCode | 否 | string | 商品条码 | +|     packageType | 否 | string | 包装规格 | +|     unit | 否 | string | 单位 | +|     produceDate | 否 | string | 生产日期时间戳(毫秒) | +|     expiryDate | 否 | string | 过期日期时间戳(毫秒) | +|     stockCount | 是 | int | 应出库数量 | +|     weight | 否 | int | 重量 | +|     volume | 否 | int | 体积 | +|     transactionSubCode | 否 | string | 交易子单号 | +|     lineNumber | 否 | string | 单据行号 | +|     batchNumber | 否 | string | 批次号 | +|     ediSkuNo | 否 | string | D365内部编号 | +|     pciCode | 否 | string | pciCode | +|     factoryLineNumber | 否 | string | 工厂行号 | +|     remark | 否 | string | 备注 | + +### 返回结果正常示例 + + { "success": true, "businessException": false} + +### 返回结果异常示例 + + { "success": false, "businessException": true, "errorCode": "500", "message": "XXX异常!"} + +### 请求示例 + +#### 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/warehouseOrder/outStock", "accessToken", jsonData); + if(httpResponseData == null) { + throw new BusinessException("则一请求失败,返回结果为空!"); + } + if(httpResponseData.getStatus() == HttpURLConnection.HTTP_UNAUTHORIZED) { + //重新获取token再次请求 + httpResponseData = zyClient.doPost(Constants.TEST_HOST + + "/oms-service-api/warehouseOrder/outStock", "accessToken", jsonData); + } + } +} +``` + + + +## 库存释放接口 + +### 简要描述 + +库存释放接口 + +### 请求URL + +· 测试环境：https://test.shjiuze.cn/oms-service-api/warehouseOrder/release + +· 生产环境：https://gw.shjiuze.cn/oms-service-api/warehouseOrder/release + +### 请求方式 + +POST + +### Headers参数 + +| 名称 | 类型 | 必填 | 示例值 | 描述 | +| ------------- | ------ | -------------------------- | -------------------------------- | ------------------------------------------------------------ | +| Authorization | String | 是     | Bearer a2c5680001 | 调用服务端API的应用凭证accessToken，通过调用获取访问凭证接口获取。 | +| appKey | String | 是 | 0867ef5f23ef446483749e19e1692b40 | 则一提供 | +| timestamp | String | 是 | 1643251533306 | 当前时间戳毫秒值 | +| nonce | String | 是 | gdst9t | 6位小写字母数字组合随机串 | +| sign | String | 是 | fa3ed338d6dfe18e7273c8692234ee70 | 签名：appKey(则一提供) + appSecret(则一提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成 | + +### Body参数 + +| 参数名 | 必传 | 类型 | 说明 | +| --------------------------------------------- | ---- | ------ | ----------------------------------------------- | +| code | 是 | string | 客户单号 | +| planTime | 否 | string | 预计操作日期时间戳(毫秒) | +| billTime | 否 | string | 单据日期时间戳(毫秒)(如无默认当前时间) | +| remark | 否 | String | 备注 | +| goodList | 是 | list | 商品集合 | +|     warehouseCode | 是 | string | 仓库编号 | +|     warehouseAreaCode | 否 | string | 库区编号 | +|     warehouseLocCode | 否 | string | 库位编号 | +|     warehouseStatus | 是 | string | 释放后库存状态（KCZ00 【正常】、KCZ01【冻结】） | +|     beforeWarehouseStatus | 是 | string | 释放前状态（KCZ00 【正常】、KCZ01【冻结】） | +|     code | 否 | string | 商品编码 | +|     name | 否 | string | 商品名称 | +|     barCode | 否 | string | 商品条码 | +|     packageType | 否 | string | 包装规格 | +|     unit | 否 | string | 单位 | +|     produceDate | 否 | string | 生产日期时间戳(毫秒) | +|     expiryDate | 否 | string | 过期日期时间戳(毫秒) | +|     number | 否 | int | 数量 | +|     weight | 否 | int | 重量 | +|     volume | 否 | int | 体积 | +|     transactionSubCode | 否 | string | 交易子单号(PO号) | +|     lineNumber | 否 | string | 单据行号 | +|     batchNumber | 是 | string | 批次号 | +|     pciCode | 否 | string | pciCode | +|     factoryLineNumber | 否 | string | 工厂行号 | +|     remark | 否 | string | 备注 | + +### 返回结果正常示例 + + { "success": true, "businessException": false} + +### 返回结果异常示例 + + { "success": false, "businessException": true, "errorCode": "500", "message": "XXX异常!"} + +### 请求示例 + +#### 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/warehouseOrder/release", "accessToken", jsonData); + if(httpResponseData == null) { + throw new BusinessException("则一请求失败,返回结果为空!"); + } + if(httpResponseData.getStatus() == HttpURLConnection.HTTP_UNAUTHORIZED) { + //重新获取token再次请求 + httpResponseData = zyClient.doPost(Constants.TEST_HOST + + "/oms-service-api/warehouseOrder/release", "accessToken", jsonData); + } + } +} +``` + + + +## 货权转移(订单移库) + +### 简要描述 + +·货权转移接口 + +### 请求URL + +· 测试环境：https://test.shjiuze.cn/oms-service-api/warehouseOrder/transferStock + +· 生产环境：https://gw.shjiuze.cn/oms-service-api/warehouseOrder/transferStock + +### 请求示例 + +#### 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/warehouseOrder/transferStock", "accessToken", jsonData); + if(httpResponseData == null) { + throw new BusinessException("则一请求失败,返回结果为空!"); + } + if(httpResponseData.getStatus() == HttpURLConnection.HTTP_UNAUTHORIZED) { + //重新获取token再次请求 + httpResponseData = zyClient.doPost(Constants.TEST_HOST + + "/oms-service-api/warehouseOrder/transferStock", "accessToken", jsonData); + } + } +} +``` + +### Headers参数 + +| 名称 | 类型 | 必填 | 示例值 | 描述 | +| ------------- | ------ | -------------------------- | -------------------------------- | ------------------------------------------------------------ | +| Authorization | String | 是     | Bearer a2c5680001 | 调用服务端API的应用凭证accessToken，通过调用获取访问凭证接口获取。 | +| appKey | String | 是 | 0867ef5f23ef446483749e19e1692b40 | 则一提供 | +| timestamp | String | 是 | 1643251533306 | 当前时间戳毫秒值 | +| nonce | String | 是 | gdst9t | 6位小写字母数字组合随机串 | +| sign | String | 是 | fa3ed338d6dfe18e7273c8692234ee70 | 签名：appKey(则一提供) + appSecret(则一提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成 | + +### Body参数 + +| 参数名 | 必传 | 类型 | 说明 | +| -------------------------------------------- | ---- | ------ | --------------------------------------------- | +| code | 是 | string | 入库单号 | +| planTime | 否 | string | 预计操作日期 | +| billTime | 否 | string | 单据日期时间戳(毫秒)(如无默认当前时间) | +| goodList | 是 | list | 商品集合 | +|     inWarehouseCode | 是 | string | 调入仓库编号 | +|     inWarehouseAreaCode | 否 | string | 调入库区编号 | +|     inWarehouseLocCode | 否 | string | 调入库位编号 | +|     inWarehouseStatus | 是 | string | 调入库存状态（KCZ00 【正常】、KCZ01【冻结】） | +|     outWarehouseCode | 是 | string | 调出仓库编号 | +|     outWarehouseAreaCode | 否 | string | 调出库区编号 | +|     outWarehouseLocCode | 否 | string | 调出库位编号 | +|     outWarehouseStatus | 是 | string | 调出库存状态（KCZ00 【正常】、KCZ01【冻结】） | +|     inCustomerCode | 否 | string | 调入客户编号 | +|     inCustomerName | 否 | string | 调入客户名称 | +|     outCustomerCode | 否 | string | 调出客户编号 | +|     outCustomerName | 否 | string | 调出客户名称 | +|     code | 是 | string | 商品编码 | +|     name | 否 | string | 商品名称 | +|     barCode | 否 | string | 商品条码 | +|     packageType | 否 | string | 包装规格 | +|     unit | 否 | string | 单位 | +|     produceDate | 否 | string | 生产日期时间戳(毫秒) | +|     expiryDate | 否 | string | 过期日期时间戳(毫秒) | +|     number | 是 | int | 移库数量 | +|     weight | 否 | int | 重量 | +|     volume | 否 | int | 体积 | +|     lineNumber | 否 | string | 单据行号 | +|     batchNumber | 否 | string | 批次号 | +|     transactionSubCode | 否 | string | 交易子单号 | +|     ediSkuNo | 否 | string | ediSkuNo | +|     pciCode | 否 | string | pciCode | +|     factoryLineNumber | 否 | string | 工厂行号 | + +### 返回正常示例 + + { "success": true, "businessException": false} + +### 返回异常示例 + + { "success": false, "businessException": true, "errorCode": "500", "message": "XXX异常!"} + + + +------------------------------------------------------------------------------------------ + +## 2022-05-05更新日志 + +1. 接口初始化 + + + +## 2022-05-07更新日志 + +1. 出入库接口外层中warehouseStatus字段删除，商品集合中增加warehouseStatus字段。 +2. 移库接口商品集合中的inStockCount、outStockCount移除，增加number字段。 + + + +## 2022-05-08更新日志 + +1. 出入库接口请求参数商品集合中’库区编号‘命名更改为warehouseAreaCode ，增加’库位编号‘（warehouseLocCode）必填。 + +2. 移库接口请求参数商品集合中’入库库区编号‘、’出库库区编号‘命名更改为inWarehouseAreaCode、 outWarehouseAreaCode ，增加’入库库位编号‘、‘出库库位编号’（inWarehouseLocCode、outWarehouseLocCode）字段且必填。 + + + +## 2022-08-15更新日志 + +1. 增加 pciCode 和 工厂行号 +2. 增加则一入库下单接口和出库下单接口 +3. 增加库存释放接口 +4. 增加货权转移接口 -- libgit2 0.21.0