开始开发

术语说明

开发步骤
  第一步:创建、配置轻应用/订阅号
  第二步:查看AppID和AppSecret
  第三步:开启开发者权限
  第四步:配置安全链接
  第五步:获取access_token
  第六步:刷新access_token及缓存
  第七步:应用开发

接口调用频率限制

术语说明

AppID

AppID是轻应用/订阅号唯一识别标志,轻应用/订阅号管理员可在轻推管理后台中查看。

AppSecret

AppSecret是给轻应用/订阅号分配的密钥,开发者需要妥善保存这个密钥,防止被恶意使用,为了安全,管理员也可以对此密钥进行修改,修改后前密钥失效。轻应用/订阅号管理员可在轻推管理后台中查看。

access_token

access_token(身份令牌)是轻应用/订阅号的全局唯一票据,由AppID和AppSecret生成,轻应用/订阅号调用各接口时都需使用access_token,用于验证接口的访问权限。access_token的存储至少要保留512个字符空间。access_token的有效期目前为2个小时,需定时刷新。

user_id

user_id指用户的账号id,具有唯一性。

org_id

org_id是企业内的组织机构id。

openid

openid是用户关注某个轻应用/订阅号后生成的唯一id,可以通过身份验证接口来获取,主要用于消息推送接口。当给企业中单人或给部分成员推送消息的时候,必须携带此参数。

对于同一用户而言,关注不同的轻应用/订阅号,openid是不同的;

对于同一轻应用/订阅号而言,被不同用户关注,openid是不同的;

对于同一轻应用/订阅号而言,同一用户取消关注再关注,openid不变。

开发步骤

对于开发人员,可以使用access_token来访问轻推开放平台的接口。所有的接口需使用Https协议、Json数据格式以及UTF8编码。接口文档中,参数中标注大写的单词或xxx的地方,表示为需要替换的变量,请根据实际情况处理。

第一步:创建、配置轻应用订阅号

企业管理员从Web版轻推进入企业管理后台,根据需要选择创建轻应用还是订阅号。

创建/配置轻应用请参考:轻应用管理

创建/配置订阅号请参考:订阅号管理

第二步:查看AppID和AppSecret

管理轻应用·订阅号,然后找到要编辑的轻应用或订阅号,选择“编辑”,即可获取AppID和AppSecret。

第三步:开启开发者权限

对于轻应用,当开发者需要使用通讯录管理相关接口时,可以勾选“成员信息查询”及“成员信息变更”,默认未开启。

  • 若不涉及通讯录管理接口,可忽略此步骤;
  • 由于订阅号无通讯录管理能力,因此对于订阅号,可忽略此步骤。

第四步:配置安全链接

当开发者需要通过身份验证机制来获取用户基本信息时,需要在轻应用/订阅号中的URL链接(包括消息中的链接、自定义菜单以及轻应用入口)处,按照身份验证接口要求,正确填写链接信息以及配置安全域名。

  • 若不涉及使用身份验证来获取用户信息,可直接在轻应用/订阅号中的URL链接填写普通外链地址即可。
  • 若订阅号无需外链到其他网页,此步骤可忽略。

注: 对于轻应用配置应用入口时,除了支持填写网页地址,还支持拉起APP应用,即填写APP应用对应的URL Scheme,即可拉起用户手机上已安装的应用。

第五步:获取access_token

请求方式: GET

请求地址: https://open.qingtui.cn/v1/token?grant_type=client_credential&appid=APPID&secret=APPSECRET

注:请求地址中大写的单词APPID和APPSECRET,为需要替换的变量,请根据实际情况进行替换。

参数说明

参数 必须 说明
grant_type 固定填写client_credential
appid 轻应用/订阅号唯一凭证
secret appid对应的密钥,即AppSecret

返回说明

正常情况下,轻推会返回下述JSON数据包:

{
    "expires_in":7200,
    "refresh_token": "refresh_token1",
    "access_token":"access_token1"
}
参数 说明
access_token 获取到的凭证
refresh_token 刷新凭证,有效期30天,access_token失效后,可通过此凭证获取新的access_token,尽可能使用此刷新凭证获取最新access_token
expires_in 凭证有效时间,单位:秒

错误时轻推会返回错误码等信息,JSON数据包示例如下(该示例为AppID无效错误):

{
    "errcode":40401,
    "errmsg":"appid or secret is unauthenticated"
}

第六步:刷新access_token及缓存

请求方式: GET

请求地址: https://open.qingtui.cn/auth/autoRefreshToken?refresh_token=REFRESH_TOKEN

参数说明

参数 必须 说明
refresh_token 刷新Token,从获取access_token接口获得

返回说明

正常情况下,轻推会返回下述JSON数据包给轻应用/订阅号:

{
    "expires_in":7200,
    "access_token": "access_token2"
}
参数 说明
access_token 获取到的凭证

错误时轻推会返回错误码等信息,JSON数据包示例如下(该示例为刷新令牌无效错误):

{
    "errcode":40402,
    "errmsg":"invalid token"
}

备注:

当获取access_token接口再次调用后,refresh_token将立即失效,但其产生的access_token在access_token的有效期结束前可用。如果一直没有调用获取access_token接口,refresh_token会在30天后失效。

关于access_token的重要说明

  1. 身份令牌access_token是轻应用/订阅号的全局唯一票据,调用各接口时都需使用access_token,开发者需要进行妥善保存。
  2. 轻应用/订阅号可以使用AppID和AppSecret调用本接口来获取access_token,AppID和AppSecret可在轻推轻应用/订阅号管理后台页面中获得。
  3. 获取access_token的接口有调用频率的限制,每2秒内只能调用1次。
  4. access_token的有效期目前为2个小时,且获取access_token接口会有次数限制,可结合刷新access_token接口定时刷新来获取access_token。
  5. 开放平台的接口调用所需的access_token的使用及生成方式说明:

1、为了保密appsecrect,开发者需要一个access_token获取和刷新的中控服务器。而其他业务逻辑服务器所使用的access_token均来自于该中控服务器,不应该各自去刷新,否则会造成access_token覆盖而影响业务;

2、目前access_token的有效期通过返回的expire_in来传达,目前是7200秒之内的值。中控服务器需要根据这个有效时间提前去刷新access_token。在刷新过程中,中控服务器对外输出的依然是老access_token,此时开放平台后台会保证在刷新短时间内,新老access_token都可用,这保证了第三方业务的平滑过渡;

3、access_token的有效时间可能会在未来有调整,所以中控服务器不仅需要内部定时主动刷新,还需要提供被动刷新access_token的接口,这样便于业务服务器在API调用获知access_token已超时的情况下,可以触发access_token的刷新流程。

如果不使用中控服务器,而是选择各个业务逻辑点各自去刷新access_token,那么就可能会产生冲突,导致服务不稳定。

第七步:应用开发

完成了上面的操作步骤之后,就可以正常使用下面的接口了。为了方便大家快速入手,还可以下载我们的开源示例代码进行参考:Java版demo

接口调用频率限制

版本 接口调用次数上限
免费版(未认证) 300次/天
免费版(已认证) 2000次/天
大企业版 无限制

results matching ""

    No results matching ""