【聚水潭SDK使用说明】

蛋炒喜红柿

已于 2022-05-12 17:02:13 修改

阅读量4.7k

点赞数

分类专栏：聚水潭平台对接文章标签：聚水潭

于 2022-05-12 16:14:10 首次发布

本文链接：https://blog.csdn.net/W664160450/article/details/124733500

版权

聚水潭平台对接专栏收录该内容

2 篇文章

订阅专栏

聚水潭SDK使用说明（只写了部分）。
聚水潭SDK下载地址：聚水潭sdk
gitee地址：gitee地址

1. 准备

在使用SDK之前，需要事先准备appKey，appSecret，signature

appKey：聚水潭应用的appKey
appSecret: 聚水潭应用的appSecret
signature: 授权回调验签是否开启，默认false

另外还需要注意以下的几个属性：

聚水潭开放平台测试环境：https://dev-api.jushuitan.com

聚水潭开放平台正式环境：https://openapi.jushuitan.com

开放平台沙箱数据：

app_key： b0b7d1db226d4216a3d58df9ffa2dde5
app_secret：99c4cef262f34ca882975a7064de0b87
access_token：b7e3b1e24e174593af8ca5c397e53dad

2. 使用

JSTService是所有API的入口，可以这样初始化

建议写到配置类中，示例如下：
@Configuration
public class config{
    
    @Bean
    public JSTService init(){
        JSTProperties properties = JSTProperties.builder()
            .serverUrl("https://dev-api.jushuitan.com")
            .appKey("b0b7d1db226d4216a3d58df9ffa2dde5")
            .appSecret("99c4cef262f34ca882975a7064de0b87")
            .build();
        return new JSTService(jstProperties);;
    }  
    
}

根据业务资源，API分为:

afterSale 售后API
allocate调拨API
auth 用于获取聚水潭授权地址
base 基础的API
express 物流API
inventory 用户管理库存
order 订单API
print 菜鸟电子面单云打印(待完善)
product 商品API
purchase 采购单API
sign 用于店铺授权回调的验证
stockIn 入库API
stockOut出库API
otherInOut 其他出入库API
supplier供应商API
token 用于获取用户的token

每个业务资源对应一组方法，例如，库存相关的 API，都可以在 .inventory() 找到。

举个例子，我们要获取商家授权地址，就可以这样写：

try {
    String state = "xxx";
    String url =  service.auth().authUrl(state);
} catch (Exception e) {
    e.printStackTrace();
}

对使用的 api 添加 try/catch ，如果使用的 api 没有抛出异常，代表请求成功，反之则请求失败，通过异常JSTException对象的 getCode()/getMessage() 拿到错误码以及错误描述。

2.1 auth

在初始化JSTService之后，我们首先要做的事情是获取聚水潭用户的授权。聚水潭用户只有授权之后，我们才能拿到token,拥有了token才能调用后续的接口。

调用示例：

try {
    String url = service.auth().authUrl();
} catch (Exception e) {
    e.printStackTrace();
}

或者

try {
    //state 自定义参数，在授权回调的时候会默认传过来
    String state = "xxx";
    String url = service.auth().authUrl(state);
} catch (Exception e) {
    e.printStackTrace();
}

这样我们就可以拿到店铺授权的url地址。

拿到授权地址之后，开发者还需要以下几个步骤需要操作：

先准备好一个授权回调接口，并把该接口地址配置到聚水潭开放平台中的回调地址中。
让公司的聚水潭账号管理者通过授权地址中展示的页面进行授权。
授权完成之后，聚水潭会通过授权回调接口，反馈授权码。
通过授权码，获取token

回调接口示例：

/**
 * 授权码有效期仅有15分钟，超时则需要重新生成授权链接，由商家重新授权。
 */
@ApiOperation("授权回调")
@ResponseBody
@RequestMapping(value = "/auth/callBack", method = RequestMethod.GET)
public Object callBackAuth(HttpServletRequest httpServletRequest){
    //app_key
    String app_key = httpServletRequest.getParameter("app_key");
    //授权码
    String code = httpServletRequest.getParameter("code");
    //自定义参数
    //获取授权地址时，如果有传递，回调时会一并传回来，如果没有，则忽略。
    String state = httpServletRequest.getParameter("state");
    //签名验证sign
    String sign = httpServletRequest.getParameter("sign");

    //验签
    //签名验证会在sign中详解
    VerifyRequest build = VerifyRequest.builder().appKey(app_key).code(code).sign(sign).state(state).build();
    boolean verify = service.sign().verify(build);
    if(!verify){
        //验签失败
        throw new JSTException(ExceptionEnum.USER_ERROR_A0341);
    }
    try {
        //获取token
        //token获取方法会在token中详解
        service.token().token(code);
    } catch (IOException e) {
        e.printStackTrace();
        //获取token失败的处理方式
        //...
    }
    //响应
    Map<String, Object> result = new HashMap<>();
    result.put("code", 0);
    result.put("msg", "success");
    return JSON.toJSON(result);
}

2.2 sign

聚水潭商家授权回调时签名验证相关的API。

调用示例：

//app_key
String appkey = "xxxxxx";

//授权码
String code = "xxxxxx";

//自定义参数
//获取授权地址时，如果有传递，回调时会一并传回来，如果没有，则忽略。
String state = "xxxxxx";

//签名验证sign
String sign = "xxxxxx";

VerifyRequest build = VerifyRequest.builder().appKey(appkey).code(code).sign(sign).state(state).build();
boolean verify = service.sign().verify(build);

其中的appkey,code,state,sign四个字段，聚水潭平台会通过授权回调接口传递到系统中。

而且验证签名时会根据初始化的JSTService中配置的signature属性的值来判断是否进行验证，默认是false，不验证。

2.3 token

获取token相关的API。

获取token

String code = "xxx";
String token = service.token().token(code);

获取的token会默认存放在本地缓存中。token的有效时间为30天，token到期之后会触发token的监听事件，自动执行刷新token的方法，获取新的token。

从缓存中获取toekn的的方法如下：

ResponseToken token = (ResponseToken) DefaultMemoryCacheOperator.instance().get(Constants.TOKEN);

ResponseToken的结构如下：

public class ResponseToken {

    /**
     * 访问令牌
     */
    private String accessToken;

    /**
     * access_token有效期【单位是秒】 2592000  30天
     */
    private Long expiresIn;

    /**
     * 更新令牌
     */
    private String refreshToken;

    /**
     * 固定值：all
     */
    private String scope;

}

刷新token

String refreshToken = "";
String refresh = service.token().refresh(refreshToken);

通过refreshToken获取新的token，不需要商家在进行授权。

2.4 base

基础API

店铺查询

//nicks 店铺主账号，不支持模糊查询，非必填项，默认查所有
ShopRequest build = ShopRequest.builder().nicks("老板").build();
List<ShopResponse> shop = service.base().shop(build);

仓库查询

WmsRequest build = WmsRequest.builder().pageIndex(1).pageSize(30).build();
List<WmsResponse> wms = service.base().wms(build);

物流公司查询

LogisticsRequest build = LogisticsRequest.builder().pageSize(100).build();
List<LogisticsResponse> logistics = service.base().logistics(build);

2.5 inventory

库存相关API

库存查询

modifiedBegin: 修改开始时间

modifiedEnd: 修改结束时间

wmsCoId: 分仓公司编号，值不传或为0查询所有仓的总库存，其它为指定仓的库存

skuIds: 商品编码,多个用逗号分隔，最多20，与修改时间不能同时为空

InventoryQueryRequest build = InventoryQueryRequest.builder()
    .modifiedBegin("2021-12-02 00:00:06")
    .modifiedEnd("2021-12-09 00:00:06")
    .skuIds("JST20211111003ABC,100890")
    .wmsCoId(0)
    .build();

List<InventoryQueryResponse> query = service.inventory().query(build);

库存盘点查询

modifiedBegin: 修改开始时间

modifiedEnd: 修改结束时间

ioIds: 指定盘点单号，多个用逗号分隔，最多50，和时间段不能同时为空

status：状态;WaitConfirm:待确认,Confirmed:生效,Archive:归档,Cancelled:取消,Delete:作废

InventoryCountRequest build = InventoryCountRequest.builder()
    .modifiedBegin("2021-12-02 00:00:00")
    .modifiedEnd("2021-12-09 00:00:00")
    .ioIds("3535290,3539256")
    .status(InventoryStatus.CONFIRMED)
    .build();

List<InventoryCountResponse> count = service.inventory().count(build);

新建盘点单

InventoryUploadRequest

wmsCoId: 分仓公司ID

type：盘点类型 :全量:check ;增量:adjust(默认adjust)

isConfirm: 是否自动确认，默认false，增量同步时只能传true
Data

soId: 外部单号，会在ERP判断重复，仅可用一次

warehouse: 仓库;主仓=1，销退仓=2，进货仓=3，次品仓 = 4

remark: 备注
Item

skuId: 商品编码

qty: 数量

batchId: 批次号;批次号存在批次信息和有效期必填

producedDate: 批次日期

expirationDate: 有效期

Item item = Item.builder().qty(3).skuId("0101000101").build();
List<Item> items = new ArrayList<>();
items.add(item);

Data data = Data.buider().soId("90871114901").warehouse(1).items(items).build();
List<Data> datas = new ArrayList<>();
datas.add(data);

InventoryUploadRequest build = InventoryUploadRequest
    .builder()
    .wmsCoId(10158015)
    .type("check")
    .isConfirm(true)
    .datas(datas)
    .build();
InventoryUploadResponse upload = service.inventory().upload(build);