开始开发

术语说明

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

打开你要查看的轻应用，点击查看应用凭证

若点击打开轻应用时提示“需设置为此轻应用的管理员才能查看”，则根据提示，去设置页面，将自己设置为轻应用管理员即可。

第三步：开启开发者权限

对于轻应用，当开发者需要使用用户信息、通讯录管理等相关接口时，需要在权限管理页面新增权限。

提交新增权限后，需要企业管理员审核，企业管理员在轻推客户端会收到权限申请。审核通过或不通过，申请人均会在轻推客户端收到提醒。

第四步：配置安全链接

当开发者需要通过身份验证机制来获取用户基本信息时，需要在轻应用/订阅号中的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，为需要替换的变量，请根据实际情况进行替换。

参数说明

返回说明

正常情况下，轻推会返回下述JSON数据包：

{
    "expires_in":7200,
    "refresh_token": "refresh_token1",
    "access_token":"access_token1"
}

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

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

第六步：刷新access_token及缓存

请求方式： GET

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

参数说明

返回说明

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

{
    "expires_in":7200,
    "access_token": "access_token2"
}

错误时轻推会返回错误码等信息，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

接口调用频率限制