zeyi / open-doc

仓储接口.md 31.5 KB

[toc]

仓储订单对接API

则一提供了不同规范的API，调用服务端API前，需了解开发前须知及调用流程。本文提供了调用则一服务端API示例，供开发者参考。

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">白名单

则一服务端API接口访问有IP白名单限制，需要接口调用方提供调用API的服务器IP地址。

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">数据加签

采用md5(32位小写)算法生成签名 appKey(则一提供) + appSecret(则一提供) + timestamp(当前时间戳毫秒) + nonce(6位随机码大小写字母数子组合) + data(请求数据)

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">数据加密

数据加密采用AES算法 加密模式： CBC 填充方式：PKCS5Padding 偏移量：iv(则一提供) 加密内容：appKey(则一提供) + timestamp(当前时间戳毫秒) + nonce(6位随机码大小写字母数子组合) + data(加密数据) 密钥： appSecret(则一提供) 输出：base64 字符集：utf-8 注：无敏感数据则无需加密

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">获取访问凭证

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">概述

调用则一服务API时，都需要先获取对应权限类型的访问凭证accessToken。访问凭证（accessToken）是由则一权限系统颁发的，用来校验调用者的身份信息，确保调用者具有要执行的操作的权限。 说明： 在使用accessToken时，请注意：

  • accessToken的有效期默认为30天，有效期内重复获取会返回相同结果，过期后获取会返回新的accessToken。
  • 开发者需要缓存accessToken，用于后续接口的调用。不能频繁调用获取accessToken接口，否则会受到频率拦截。
  • 当调用业务API时，如果返回状态码为401，则说明accessToken不正确或已过期，这时需要重新获取accessToken后再调用对应的API。

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">接口信息

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">请求方式：

post

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">请求地址：

Body参数

名称 类型 必填 示例值 描述
username String 是 zhangsan 用户名，则一提供
password String 是 password123 密码，则一提供

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">返回参数

名称 类型 示例值 描述
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类型

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">请求示例

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
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<ZYTokenDto> zyResponse = gson.fromJson(httpResponseData.getBody(), new      TypeToken<ZYResponse<ZYTokenDto>>(){}.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();
    }
}

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">返回示例

{
    "success": true,
    "businessException": false,
    "errorCode": null,
    "message": null,
    "result": {
        "accessToken": "64d7f367-609b-4f7d-a84d-a3d2a0b5ad85",
        "expiresIn": 602105,
        "tokenType": "bearer"
    }
}

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">入库下单

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">简要描述

入库单创建接口

请求URL

· 测试环境：https://test.shjiuze.cn/oms-service-api/warehouseOrder/inStock

· 生产环境：https://gw.shjiuze.cn/oms-service-api/warehouseOrder/inStock

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">请求方式

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 备注

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">返回结果正常示例

{ "success": true, "businessException": false}

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">返回结果异常示例

{ "success": false, "businessException": true, "errorCode": "500", "message": "XXX异常!"}

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">请求示例

Java-sdk方式 下载SDK

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);
        }
    }
}

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">出库下单

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">简要描述

出库单创建接口

请求URL

· 测试环境：https://test.shjiuze.cn/oms-service-api/warehouseOrder/outStock

· 生产环境：https://gw.shjiuze.cn/oms-service-api/warehouseOrder/outStock

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">请求方式

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 备注

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">返回结果正常示例

{ "success": true, "businessException": false}

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">返回结果异常示例

{ "success": false, "businessException": true, "errorCode": "500", "message": "XXX异常!"}

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">请求示例

Java-sdk方式 下载SDK

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);
        }
    }
}

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">库存释放接口

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">简要描述

库存释放接口

请求URL

· 测试环境：https://test.shjiuze.cn/oms-service-api/warehouseOrder/release

· 生产环境：https://gw.shjiuze.cn/oms-service-api/warehouseOrder/release

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">请求方式

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 备注

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">返回结果正常示例

{ "success": true, "businessException": false}

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">返回结果异常示例

{ "success": false, "businessException": true, "errorCode": "500", "message": "XXX异常!"}

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">请求示例

Java-sdk方式 下载SDK

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);
        }
    }
}

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">货权转移(订单移库)

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">简要描述

·货权转移接口

请求URL

· 测试环境：https://test.shjiuze.cn/oms-service-api/warehouseOrder/transferStock

· 生产环境：https://gw.shjiuze.cn/oms-service-api/warehouseOrder/transferStock

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">请求示例

Java-sdk方式 下载SDK

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 工厂行号

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">返回正常示例

{ "success": true, "businessException": false}

56b7e0fe46864b43b334d738f7f9824351a1db67/order/warehouse/2022083101/仓储接口.md#">返回异常示例

{ "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. 增加货权转移接口