开发前必读
基本概念介绍
- SuiteId：应用的唯一身份标识
- SuiteKey：SuiteId 对应的调用身份密钥（又名 SuiteSecret）
- CorpId：教育号的机构，学校或者教育局的id
- suite_ticket：suite_ticket 与 SuiteKey 配套使用，用于获取 suite_access_token。suite_ticket 由教育号后台向登记的应用指令回调地址定期推送（10分钟），用于加强调用者身份确认（即使 SuiteKey 泄露，也无法获取到 suite_access_token）
接口类型
- 登录接入接口：用于应用登录过程中的身份验证和登录态下发
- 应用授权类接口：用于应用接入过程中的机构授权与安装
- 回调通知接口：由开发者提供的回调接口，用于接收教育号发送的回调信息
- 开放接口：用于查询和操作授权机构相关信息
接口调用凭证
在第三方应用开发提供的接口中，会涉及到三种类型的 access_token，用于接口调用时验证身份的凭证。 下面表格对这三类 token 的定义及使用场景进行说明，开发者应在不同场景中选择并生成对应的 token：
| 类型 | 说明 | 适用场景 | 获取方式 |
|---|---|---|---|
| access_token | 用户应用登录 token | 用于完成登录态下发，查询用户信息 | 说明文档参考code换取access_token |
| suite_access_token | 第三方应用的 token。代表第三方应用的身份 | 用于获取第三方应用的预授权码，获取授权机构信息等 | 说明文档参考获取第三方应用凭证 |
| corp_access_token | 授权机构的 token。机构安装第三方应用后，代表安装该应用的机构身份 | 用于调用开发平台接口，如通讯录管理接口，家校沟通管理接口等 | 说明文档参考获取机构凭证 |
开发文档阅读说明
所有的接口需使用HTTPS协议、JSON数据格式、UTF8编码。接口说明格式如下：
请求方式：GET/POST（HTTPS）
请求地址：https://oapi.szns.edu.cn/service/gettoken?corpid=ID&corpsecret=SECRET
请求包体：
...
参数说明：
...
返回结果：
...
参数说明：
...
- 请求方式，标明接口调用的HTTP方法，区分HttpGet/HttpPost请求。所有的请求都为https协议。
- 请求地址，参数中标注大写的单词，表示为需要替换的变量。在上面的例子中 ID 及 SECRET 为需要替换的变量，根据实际获取值更新。假如，这里我们获取到的ID=wxdd725338566d6ffe，SECRET=vQT_03RsfVA3uE6J5dofR7hJeOdiXUvccqV8mDgLdLI，那么上述的请求在发送时为：
https://oapi.szns.edu.cn/service/gettoken?corpid=wxdd725338566d6ffe&corpsecret=AAA_03RsfVA3uE6J5dofR7hJeOdiXUvccqV8mDgLdLI
- 请求包体/参数说明，标明请求参数示例及说明，参数说明包括字段含义、取值范围，开发者在设计数据结构时，应参考该定义范围。
- 返回结果/参数说明，标明返回参数示例及说明。特别留意，所有接口返回包里都有errcode、errmsg。开发者需根据errcode是否为0判断是否调用成功。而errmsg仅作参考，后续可能会有变动，因此不可作为是否调用成功的判据。
替换内网应用后台地址
由于应用服务后台属于内网应用，小程序环境无法直接访问，现通过外网网关进行一层代理，需要应用侧调整一下后台服务的访问地址。具体示例如下 ：
科研应用
修改前调用后台地址：http://10.202.237.245/twxyz
修改后调用后台地址：https://keyan-appproxy.szns.edu.cn
其中(keyan)为应用对应的英文名，keyan-appproxy.szns.edu.cn为教育局分配给应用的转发地址