目录一、先说结论二、先搞清楚服务商应用和自有商城应用不一样三、商家授权两种拿 token 的方式3.1 拼授权链接3.2 走回调接收 code3.3 用 code 换 token四、拿到 token 之后第一件事存好、算好到期时间五、第二件事调一个查询接口试一下六、第三件事到期怎么办6.1 三种情况6.2 过期了会发生什么6.3 到期提醒七、服务商刚建好应用的还有一条要注意八、最后一、先说结论聚水潭开放平台的服务商应用商家点完「同意授权」之后你要做五件事#做什么为什么1拿到access_token按商家存好以后调这个商家的接口都靠它2记下到期时间token 有效期是商家授权时选的30 / 90 / 180 / 360 天过期接口就停3先调一个查询接口试一下确认 token 能用、权限够顺便拿到店铺列表做对照4确认商家的聚水潭合同在有效期内开放平台标准 API 不另收费的前提是商家和聚水潭有有效的付费合同5做到期提醒服务商应用的 token不能刷新只能重新授权或让商家在 ERP 里续期下面按官方文档逐条讲原文出处写在每一段后面。二、先搞清楚服务商应用和自有商城应用不一样聚水潭开放平台有两种应用token 的规则完全不同网上很多文章混着讲。官方对比表docId22「应用说明」自有商城应用服务商应用谁用商家自己开发第三方开发者、服务商能对接几家聚水潭商家只支持一家可对接多家token 怎么拿调getInitToken接口授权工具或者走回调重新授权的限制token 过期前 12 小时才能重新授权或者过期后不限制重新授权之后原有 token 还有24 小时有效能不能刷新 token能调refreshToken接口不支持过期前或已过期都走重新授权token 有效期默认 30 天30 / 90 / 180 / 360 天授权时可选所以网上说的「用 refresh_token 刷新」「过期前 12 小时才能续」说的是自有商城应用。做对接服务的第三方用的是服务商应用这两条都不适用。同一份文档还说明了 token 和商家的关系app_key、app_secret相当于开发者的用户名和密码access_token代表具体哪个商家一个商家账号下的多个店铺共用一个 token不同商家、不同应用之间数据和调用频率互不影响三、商家授权两种拿 token 的方式官方文档 docId25「第三方授权流程」给了两条路授权工具自己拼授权链接 回调怎么做在官方「用户授权工具」里输入 app_key生成链接发给商家按规则拼授权 URL并在应用详情里配好回调地址授权后 token 在哪直接显示在商家的页面上不走回调平台把授权码code发到你的回调地址你再拿code换 token适合客户少手动处理客户多要自动化两条路共同的规则授权链接15 分钟内有效生成后要让商家尽快点商家要用聚水潭 ERP 主账号登录不是开放平台账号分仓授权登录主仓账号选对应的分仓3.1 拼授权链接正式环境https://openweb.jushuitan.com/auth测试环境https://isv-openweb.jushuitan.com/auth后面带这几个参数并签名参数说明app_key你的应用 Keytimestamp秒级时间戳charset固定utf-8不能不传state自定义用来区分是哪个商家授权完成时会原样返回sign签名规则见官方 docId70我在用的生成脚本Node.jsconstcryptorequire(crypto);// 聚水潭签名除 sign 外、值不为空的参数按键名排序拼成 key1value1key2value2…// 前面加 app_secretUTF-8 做 MD5取 32 位小写官方 docId70functionsign(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);}functionauthLink({appKey,appSecret,state,testfalse}){constbasetest?https://isv-openweb.jushuitan.com/auth:https://openweb.jushuitan.com/auth;constparams{app_key:appKey,timestamp:String(Math.floor(Date.now()/1000)),charset:utf-8,state,// 比如填客户代号回调时就知道是谁授权的};params.signsign(appSecret,params);returnbase?newURLSearchParams(params).toString();}一个坑官方文档写得很明白只有按上面规则拼的链接才会触发回调授权工具生成的链接不回调。反过来我实测过应用还没配回调地址时用自己拼的链接让沙箱商家授权授权成功了但页面上不显示 tokencode 又没地方收等于白授权一次。没配回调之前一律用授权工具。3.2 走回调接收 code商家同意授权后平台用HTTP GET请求你配置的回调地址带这几个参数参数说明app_key应用 Keycode授权码有效期只有 15 分钟state你拼链接时传的值sign签名回调接口的几条硬规定docId25 原文要点支持 http 或 https端口 80、443 或自定义都行回调地址本身不能带参数收到后必须返回{code:0}否则平台会在接下来 10 分钟里重试 10 次3.3 用 code 换 token拿到code后15 分钟内调换 token 接口正式环境POST https://openapi.jushuitan.com/openWeb/auth/accessToken测试环境POST https://dev-api.jushuitan.com/openWebIsv/auth/accessToken参数app_key、timestamp、grant_type固定authorization_code、charsetutf-8、code、sign。返回示例官方文档原样{code:0,data:{access_token:0ecde8631431a5ed6b3e7368afbabdadss,expires_in:2592000,refresh_token:eb1964a9d142423a9f0de88b97bb38fc,scope:all}}expires_in是还有多少秒过期上面的 2592000 秒就是 30 天。返回里还可能带coid授权的 ERP 公司编码。说明一下我目前给沙箱商家授权用的是授权工具那条路3.2 和 3.3 的回调流程是按官方文档整理的还没在正式环境跑过。四、拿到 token 之后第一件事存好、算好到期时间expires_in是相对时间一定要当场换算成绝对时间存下来不然过几天就不知道什么时候到期了// 换到 token 后立刻调用按商家存记下绝对到期时间functionsaveAuth(db,{state,coid,access_token,expires_in}){constnowDate.now();db.upsert(jst_auth,{merchant:state,// 拼链接时传的客户代号coid:coid||null,// 授权的 ERP 公司编码accessToken:access_token,// 敏感信息别打进日志authorizedAt:newDate(now).toISOString(),expiresAt:newDate(nowexpires_in*1000).toISOString(),});}几个注意点按商家存不是按店铺存。一个商家账号下的多个店铺共用一个 tokenaccess_token相当于这个商家数据的钥匙别写进日志、别发群服务商应用用不上refresh_token见第二节存不存都行五、第二件事调一个查询接口试一下token 拿到不代表一定能用接口权限可能没申请全、IP 白名单可能没配。上线前先调一个最简单的店铺查询/open/shops/query一次确认三件事token 是不是有效的签名、公共参数有没有写错这个商家有哪些店铺——做对接时要把店铺对应到财务软件里的客户这张对照表要商家确认我在测试环境用自己的服务商应用 沙箱商家授权的 token 跑过一遍签名、店铺查询、出库单增量拉取都是通的。六、第三件事到期怎么办6.1 三种情况情况怎么办出处还没过期重新生成授权链接让商家再授权一次重新授权后旧 token 还有 24 小时不会断docId22、docId25还没过期商家自己续商家在聚水潭 ERP 的「开放平台管理」页面选对应的应用续期常见问题 postId36已经过期页面上不能续了只能重新走授权常见问题 postId36、docId25「商家在 ERP 里自己续期」这条很多人不知道。对商家来说最省事不用等你发链接自己点一下就续上了。6.2 过期了会发生什么业务接口调不了拉单直接停官方常见问题里还提到token 过期后消息推送也会停止对财务对接来说最怕的是悄悄停了没人知道月底对账才发现少了半个月的单。6.3 到期提醒每天跑一次提前半个月提醒// 每天跑一次15 天内到期的提醒续期已过期的报警functioncheckExpiry(auths,nownewDate()){constalerts[];for(constaofauths){constleftMath.floor((newDate(a.expiresAt)-now)/86400000);if(left0){alerts.push(【已过期】${a.merchant}${-left}天前到期拉单已停要重新授权);}elseif(left15){alerts.push(【快到期】${a.merchant}还剩${left}天请商家在 ERP「开放平台管理」续期或重新授权);}}returnalerts;// 发到微信、邮件或者显示在状态页}授权时让商家选 360 天一年只折腾一次。七、服务商刚建好应用的还有一条要注意官方规定应用三个月内没有授权商家、也没有调用平台有权下架聚水潭开放平台商家授权流程文档docId280。所以服务商应用不要建得太早。建好以后三个月内要有第一个商家授权、并且真的调过接口。八、最后服务商在商家授权后要做的拿 token授权工具直接看页面或者走回调用code换code只有 15 分钟存好按商家存把expires_in换算成绝对到期时间试一下先调店铺查询确认 token、签名、权限都没问题确认合同商家和聚水潭的付费合同要在有效期内防过期服务商 token 不能刷新到期前重新授权旧 token 还有 24 小时或让商家在 ERP「开放平台管理」里续期在接聚水潭开放平台、被授权流程卡住的评论区说说卡在哪一步看到都会回。