目录一、先说结论二、注册和资质认证2.1 注册2.2 资质认证只能用企业三、创建应用服务商还是自有商城四、申请接口权限五、测试环境先在沙箱里跑通六、调第一个接口6.1 公共参数6.2 签名规则6.3 用官方算例验证你的签名6.4 第一个请求店铺查询6.5 出错了先看哪里七、还要知道的两条规定八、最后一、先说结论聚水潭开放平台接入一共五步全部免费步骤做什么要多久1注册开发者账号5 分钟2企业资质认证个人不能认证填 10 分钟审核 1–3 个工作日3创建应用选服务商应用还是自有商城应用填 10 分钟等审核4申请接口权限 填 IP 白名单几分钟5拿到商家授权的 token调第一个接口签名写对就通最容易卡住的是第 5 步的签名。本文最后给出官方文档里的两个签名算例你的代码算出来和它一样签名就对了。以下是我自己走完这套流程的记录规则部分都对照过聚水潭开放平台官方文档。二、注册和资质认证2.1 注册用电脑浏览器打开聚水潭开放平台openweb.jushuitan.com用手机号注册。注意开放平台账号和聚水潭 ERP 的商家账号是两套没有关系。你是开发者用开放平台账号你的客户是商家用 ERP 账号。2.2 资质认证只能用企业登录后点「创建应用」会先弹出资质认证。官方常见问题写明个人开发者不能认证身份只能选企业。要准备营业执照照片法人身份证正反面统一社会信用代码、营业地址照营业执照上的地址一字不差地填营业执照截止日执照上写「长期」就选「永续经营」联系人、手机、邮箱审核结果和平台通知会发到邮箱提交后页面提示 1–3 个工作日审核。三、创建应用服务商还是自有商城这一步选错了后面全要重来。两种应用的区别官方 docId22自有商城应用服务商应用谁用商家自己开发对接自己的系统第三方开发者、服务商能对接几家商家只支持一家可对接多家token 怎么拿调接口获取初始 token商家授权后拿token 能不能刷新能不能到期重新授权token 有效期默认 30 天30 / 90 / 180 / 360 天商家授权时选给别人做对接的选服务商应用。自有商城应用只能接一家而且申请时要上传商家和聚水潭签的合同。创建时要填栏目怎么填应用名称不能和别人重名应用描述写清楚做什么业务、调哪些接口。比如「为商家提供与财务软件的数据对接只读取销售出库单、售后退仓单、采购入库单、商品、店铺、仓库不修改聚水潭数据」回调地址不是必填。没写好回调接口之前先空着用官方授权工具拿 tokenIP 白名单你服务器的公网 IP程序从这台机器访问聚水潭审核通过后在「应用详情 → 证书信息」里能看到App Key和App Secret。App Secret 相当于密码别写进代码仓库、别发群。四、申请接口权限应用建好后默认没有任何接口权限要一个一个申请。在「应用详情 → API 接口权限」里按目录找接口每换一个目录要点一下右边的「搜索」列表才会刷新勾上要的那一行点那一行右边的「申请」在「我的申请」里把状态筛成「已通过」确认都在做财务对接我申请的是这 6 个目录接口用途基础 API/open/shops/query店铺查询基础 API/open/wms/partner/query仓库查询商品 API/open/sku/query商品资料查询出库 API/open/orders/out/simple/query销售出库查询售后 API/open/aftersale/received/query售后实际收货退仓查询入库 API采购入库查询见下面的坑一个坑采购入库查询的路径我实测测试环境和正式环境不一样环境申请通过的路径正式环境/open/webapi/wmsapi/purchasein/purchaseinquery测试环境/open/purchasein/query两个都叫「采购入库查询」。代码里别写死路径按环境从配置里取。五、测试环境先在沙箱里跑通聚水潭有独立的测试环境测试环境正式环境开发者后台isv-openweb.jushuitan.com右上角有「开发测试」openweb.jushuitan.com接口地址https://dev-api.jushuitan.comhttps://openapi.jushuitan.com官方文档「测试环境说明」docId110提供了沙箱商家账号和一组公开的测试参数所有开发者都能用。建议先用这组公开参数把签名调通再建自己的测试应用、用沙箱商家授权一遍最后才上正式环境。六、调第一个接口6.1 公共参数每个请求都要带官方 docId30参数说明app_key应用 Keyaccess_token商家授权后拿到的 tokentimestamp10 位秒级时间戳和服务器时间误差不能超过 10 分钟charsetutf-8version2biz业务参数JSON 字符串sign签名请求方式只收 POSTContent-Type用application/x-www-form-urlencoded。调用频率每个 token、每个接口每秒不超过 5 次、每分钟不超过 100 次。6.2 签名规则官方 docId70除sign外、值不为空的参数按键名字典序排序拼成key1value1key2value2…前面加上app_secretUTF-8 做 MD5取32 位小写两个容易错的地方biz整体当一个字符串参与签名不要把里面的字段拆出来中文不要做 URL 编码再签名constcryptorequire(crypto);functionsign(appSecret,params){constkeysObject.keys(params).filter(kk!signparams[k]!undefinedparams[k]!nullparams[k]!).sort();consttextappSecretkeys.map(kkString(params[k])).join();returncrypto.createHash(md5).update(text,utf8).digest(hex);}6.3 用官方算例验证你的签名官方文档给了两个带结果的算例。你的签名函数算出来和下面一样就是对的constassertrequire(node:assert);// 算例一授权接口assert.strictEqual(sign(e9c5ca33fecb404b8e6cdbd0ef4a6d25,{app_key:5b53060f23d84ddf9703056e84fa5a2d,timestamp:1639128407,grant_type:authorization_code,charset:utf-8,code:123456,}),05e3a51e19e0883afd1882ccd309e0b9);// 算例二业务接口biz 含中文整体参与签名assert.strictEqual(sign(e9c5ca33fecb404b8e6cdbd0ef4a6d25,{app_key:5b53060f23d84ddf9703056e84fa5a2d,access_token:d7b01bf0842a4742a9450e21ffd95f60,timestamp:1639128407,version:2,charset:utf-8,biz:{page_index:1,page_size:100,nicks:[老板]},}),395f5a78b446be465ac03a02491296c7);这两条我写成了单元测试每次改代码都跑一直是通过的。建议你也写成测试钉住签名一改错马上就能发现。6.4 第一个请求店铺查询店铺查询/open/shops/query最简单适合当第一个asyncfunctioncallJst({baseUrl,appKey,appSecret,accessToken},path,biz){constparams{app_key:appKey,access_token:accessToken,timestamp:String(Math.floor(Date.now()/1000)),charset:utf-8,version:2,biz:JSON.stringify(biz||{}),};params.signsign(appSecret,params);constresawaitfetch(baseUrlpath,{method:POST,headers:{Content-Type:application/x-www-form-urlencoded;charsetutf-8},body:newURLSearchParams(params).toString(),});constbodyawaitres.json();if(body.code!0)thrownewError(聚水潭${path}出错${body.code}${body.msg||});returnbody.data||{};}// 测试环境constdataawaitcallJst({baseUrl:https://dev-api.jushuitan.com,appKey,appSecret,accessToken},/open/shops/query,{page_index:1,page_size:10});console.log(data.datas);// 店铺列表shop_id、shop_name……注意body.code是0才是成功HTTP 状态码 200 不代表调用成功。6.5 出错了先看哪里现象先查签名错误用 6.3 的官方算例跑一遍你的签名函数检查biz是不是整体参与、中文有没有被编码token 无效或过期商家授权是否过期是不是拿测试环境的 token 调了正式环境没有权限这个接口的权限是否申请通过采购入库注意两个环境路径不一样调用频率超限每个接口每秒 5 次、每分钟 100 次请求之间加间隔时间戳错误服务器时间是否准误差不能超过 10 分钟七、还要知道的两条规定① 应用三个月没用会被下架。官方规定应用三个月内没有授权商家、也没有调用平台有权下架。所以有意向客户了再建正式应用别提前建好放着。② 淘宝天猫订单拿不到金额。聚水潭官方文档写明淘系订单的销售出库单不返回线上单号、收件人、金额要拿得走阿里的奇门网关。做财务对接的接入前一定要知道这一条。我另外写过一篇「聚水潭奇门是什么意思」。八、最后接入五步注册 → 企业认证个人不行→ 建应用 → 申请接口权限 IP 白名单 → 授权后调接口选应用给别人做对接选服务商应用签名app_secret 排序拼接 MD5 小写biz整体签用官方两个算例验证成功判断看code 0不看 HTTP 状态码两个坑采购入库路径两个环境不一样淘系订单没有金额商家授权之后具体要做什么token 怎么存、到期怎么续我单独写了一篇「聚水潭开放平台服务商在商家授权后需要做什么」。在接聚水潭开放平台、签名调不通的评论区贴出你的参数App Secret 和 token 打码看到都会回。
