成绩云接口开发文档

前言

本文档针对需要对接成绩云系统的平台而编写。

接入成绩云的平台需要先联系知未科技研发，获取2个基本参数：平台ID[platform]，平台密钥[key]。这两个参数也可以反过来向知未科技提供。

然后提供一个接口URL前缀[apiBaseUrl]，后面所有的接口都基于这个前缀。

为每一所接入学校向知未提供一个[orgId]。

单点登录

单点登录流程说明：

1. 第三方平台内添加成绩云访问单点登录链接，点击链接访问成绩云。
2. 成绩云接收来自第三方的的访问参数，查询站点信息。（成绩云是分学段建立站点的；如果一个学校包含了小学、初中、高中，那么成绩云中将分别建立小学、初中、高中三个站点。成绩云分学段建立的站点将使用第三方平台给定的学校唯一标识建立站点关联关系）。
3. 第三方平台给定的学校没有包含多个学段，则开始验证用户信息。
4. 第三方平台给定的学校包含多个学段，成绩云将会显示选择站点页面。选择站点页面将列举出访问用户可选择的站点。用户选择对应的站点后，则开始验证用户信息。

单点登录链接：

 [apiBaseUrl]/[paltform]?orgId=[学校ID]&account=[账号]&type=[角色]&timestamp=[当前时间戳]&sign=[加密串]

paltform:平台ID
请求方法:GET
接口方向:第三方→成绩云
访问参数：

访问参数

参数	类型	是否必填	描述
orgId	string	是	学校ID
account	string	是	账号
type	string	是	角色
timestamp	int	是	时间戳time()
sign	string	是	加密串, 详见附录签名参数sign生成说明

查询用户

查询所有用户列表

此接口是下面其它接口的超集，后面的接口通过role参数查询子集。

查询学生列表

请求参数

参数	类型	是否必填	描述
orgId	string	是	学校id

返回样例

{
    "list": [
        {
            "id": "zhiwei_01",
            "schoolId": "20190101",
            "name": "刘备",
            "sex": "0",
            "grade": "10",
            "class": "1"
        },
        {
            "id": "zhiwei_02",
            "schoolId": "20190102",
            "name": "关羽",
            "sex": "0",
            "grade": "11",
            "class": "2"
        },
        {
            "id": "zhiwei_03",
            "schoolId": "20190103",
            "name": "张飞",
            "sex": "0",
            "grade": "12",
            "class": "3"
        }
    ]
}

返回参数

参数	类型	描述
id	string	学生在平台内的唯一ID
schoolId	string	学号。要求同一个学校内唯一
name	string	姓名
sex	enum (1, 2)	性别。1=>男， 2=>女
grade	int	年级
class	int	班级。必须为纯整数，不能含有其他字符

查询家长列表

访问参数

参数	类型	是否必填	描述
orgId	string	是	学校的唯一 id

返回样例

{
    "list": [
        {
            "id": "parent_01",
            "studentList": [
                "stu_01"
            ]
        },
        {
            "id": "parent_02",
            "studentList": [
                "stu_02",
                "stu_03"
            ]
        },
        {
            "id": "parent_03",
            "studentList": [
                "stu_04",
                "stu_05",
                "stu_06"
            ]
        }
    ]
}

返回参数

参数	类型	描述
id	string	家长在平台内的唯一 id
studentList	array	家长关联的学生 id数组

附录

签名参数sign生成说明

第一步：对传入的参数按照键名排序
第二步：使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串stringA
第三步：在stringA最后拼接上“&key=[平台密钥]”得到stringSignTemp字符串，并对stringSignTemp进行MD5运算
第四步：得到最终请求字符串sign

PHP签名算法示例：

//$key 平台密钥
function sign($data, $key) {
  ksort($data);                                    // 正向排序
  $key_str = urldecode(http_build_query($data));  // 连接字符串
  $key_str .= '&key=' . $key;                     // 拼接key
  return md5($key_str);
}

$data = array(
   'orgId'=> 2345,
   'account'=> 4567,
   'type'=> 1,
   'timestamp'  => time(),
);
$sign = sign($data, $key);

---

返回结果

参数名称	类型	描述
code	int	公共返回码，详见附录公共返回码
msg	string	返回信息
data	object	返回的查询或操作数据,数据可能是对象或数组。具体根据每个API而定。

返回示例：

{
    "code": "10000",
    "msg": "成功",
    "data": [
        {
            "userName": "成绩云",
            "schoolId": 101,
        }
    ]
}

---

公共返回码

开发者每次调用接口时，可能获得正确或错误的返回码，开发者可以根据返回码信息调试接口，排查错误。 返回码如下:

返回码(code)	消息(msg)
10000	成功
10001	未知错误
10002	服务器忙
10003	服务器无响应
10004	操作超时
10005	网络异常
10006	IP地址无效或不匹配
10007	操作异常
10008	操作无效
10009	数据库操作异常
20001	没有匹配的数据
20002	数据无效
30001	接口不存在
30002	参数解析错误
30003	参数格式错误
30004	参数长度超出范围
30005	参数值内容错误
30006	验证失败
40001	用户账号不存在
40002	用户账号已经禁用