# jushuitan-sdk **Repository Path**: iwiFool/jushuitan-sdk ## Basic Information - **Project Name**: jushuitan-sdk - **Description**: 聚水潭-sdk - **Primary Language**: Java - **License**: MulanPSL-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 8 - **Created**: 2024-09-28 - **Last Updated**: 2024-09-28 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 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的入口，可以这样初始化 ```java 建议写到配置类中，示例如下： @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() 找到。 举个例子，我们要获取商家授权地址，就可以这样写： ```java 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`才能调用后续的接口。 调用示例： ```java try { String url = service.auth().authUrl(); } catch (Exception e) { e.printStackTrace(); } ``` 或者 ```java try { //state 自定义参数，在授权回调的时候会默认传过来 String state = "xxx"; String url = service.auth().authUrl(state); } catch (Exception e) { e.printStackTrace(); } ``` 这样我们就可以拿到店铺授权的url地址。 拿到授权地址之后，开发者还需要以下几个步骤需要操作： 1. 先准备好一个授权回调接口，并把该接口地址配置到聚水潭开放平台中的回调地址中。 2. 让公司的聚水潭账号管理者通过授权地址中展示的页面进行授权。 3. 授权完成之后，聚水潭会通过授权回调接口，反馈授权码。 4. 通过授权码，获取`token` 回调接口示例： ```java /** * 授权码有效期仅有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 result = new HashMap<>(); result.put("code", 0); result.put("msg", "success"); return JSON.toJSON(result); } ``` ## 2.2 sign 聚水潭商家授权回调时签名验证相关的API。 调用示例： ```java //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 ```java String code = "xxx"; String token = service.token().token(code); ``` 获取的token会默认存放在本地缓存中。`token`的有效时间为30天，`token`到期之后会触发`token`的监听事件，自动执行刷新token的方法，获取新的token。 从缓存中获取`toekn`的的方法如下： ```java ResponseToken token = (ResponseToken) DefaultMemoryCacheOperator.instance().get(Constants.TOKEN); ``` `ResponseToken`的结构如下： ```java public class ResponseToken { /** * 访问令牌 */ private String accessToken; /** * access_token有效期【单位是秒】 2592000 30天 */ private Long expiresIn; /** * 更新令牌 */ private String refreshToken; /** * 固定值：all */ private String scope; } ``` + 刷新token ```java String refreshToken = ""; String refresh = service.token().refresh(refreshToken); ``` 通过`refreshToken`获取新的token，不需要商家在进行授权。 ## 2.4 base 基础API + 店铺查询 ```java //nicks 店铺主账号，不支持模糊查询，非必填项，默认查所有 ShopRequest build = ShopRequest.builder().nicks("老板").build(); List shop = service.base().shop(build); ``` + 仓库查询 ```java WmsRequest build = WmsRequest.builder().pageIndex(1).pageSize(30).build(); List wms = service.base().wms(build); ``` + 物流公司查询 ```java LogisticsRequest build = LogisticsRequest.builder().pageSize(100).build(); List logistics = service.base().logistics(build); ``` ## 2.5 inventory 库存相关API + 库存查询 `modifiedBegin`: 修改开始时间 `modifiedEnd`: 修改结束时间 `wmsCoId`: 分仓公司编号，值不传或为0查询所有仓的总库存，其它为指定仓的库存 `skuIds`: 商品编码,多个用逗号分隔，最多20，与修改时间不能同时为空 ```java 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 query = service.inventory().query(build); ``` + 库存盘点查询 `modifiedBegin`: 修改开始时间 `modifiedEnd`: 修改结束时间 `ioIds`: 指定盘点单号，多个用逗号分隔，最多50，和时间段不能同时为空 `status`：状态;WaitConfirm:待确认,Confirmed:生效,Archive:归档,Cancelled:取消,Delete:作废 ```java 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 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`: 有效期 ```java Item item = Item.builder().qty(3).skuId("0101000101").build(); List items = new ArrayList<>(); items.add(item); Data data = Data.buider().soId("90871114901").warehouse(1).items(items).build(); List 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); ```