【聚水潭SDK使用说明】

聚水潭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地址。

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

1. 先准备好一个授权回调接口，并把该接口地址配置到聚水潭开放平台中的回调地址中。

2. 让公司的聚水潭账号管理者通过授权地址中展示的页面进行授权。

3. 授权完成之后，聚水潭会通过授权回调接口，反馈授权码。

4. 通过授权码，获取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);