查看“成绩云接口开发文档”的源代码

== 前言 ==

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

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

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

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

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

单点登录链接：
<pre> [apiBaseUrl]/[paltform]?orgId=[学校ID]&account=[账号]&type=[角色]&timestamp=[当前时间戳]&sign=[加密串]</pre>
<code>paltform</code>:平台ID<br/>
请求方法:<code>GET</code><br/>
接口方向:<code>第三方</code>→<code>成绩云</code><br/>
访问参数：

{| class="wikitable"
|+访问参数
|-
| style="width:40px; text-align:center;" | 参数
| style="width:100px; text-align:center;" | 类型
| style="width:100px; text-align:center;" | 是否必填
| style="width:250px; text-align:center;" | 描述
|-
|orgId
|string
|是
|学校ID
|-
|account
|string
|是
|账号
|-
|type
|string
|是
|角色
|-
|timestamp
|int
|是
|时间戳time()
|-
|sign
|string
|是
|加密串, 详见附录签名参数sign生成说明
|}

== 查询用户 ==

=== 查询所有用户列表 ===

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

请求方式：POST  <br/>
请求示例: [apiBaseUrl]/queryUsers?orgId=ORGID&timestamp=TIMESTAMP&sign=SIGN
{| class="wikitable"
|+访问参数
|-
| style="width:80px; text-align:center;" | 参数
| style="width:150px; text-align:center;" | 类型
| style="width:100px; text-align:center;" | 是否必填
| style="width:220px; text-align:center;" | 描述
|-
|orgId
|string
|是
|学校的唯一 id
|}

<br/>
'''返回样例'''
<pre>
{
    "code": 0,
    "msg": "成功",
    "data": {
        "学生": [
            {
                "id": "zhiwei_01",
                "schoolId": "20190101",
                "name": "刘备",
                "gender": "男",
                "grade": 10,
                "class": 1
            },
            {
                "id": "zhiwei_02",
                "schoolId": "20190102",
                "name": "关羽",
                "gender": "男",
                "grade": 11,
                "class": 2
            },
            {
                "id": "zhiwei_03",
                "schoolId": "20190103",
                "name": "张飞",
                "gender": "男",
                "grade": 12,
                "class": 3
            }
        ],
        "老师": [
            {
                "id": "zhiwei_04",
                "name": "孔明"
            },
            {
                "id": "zhiwei_05",
                "name": "郭嘉"
            },
            {
                "id": "zhiwei_06",
                "name": "单福"
            }
        ],
        "管理员": [
            {
                "id": "zhiwei_07",
                "name": "陈大文"
            },
            {
                "id": "zhiwei_08",
                "name": "张伟"
            },
            {
                "id": "zhiwei_09",
                "name": "杨红"
            }
        ],
        "家长": [
            {
                "id": "parent_01",
                "studentList": [
                    "zhiwei_01"
                ]
            },
            {
                "id": "parent_02",
                "studentList": [
                    "zhiwei_02",
                ]
            },
            {
                "id": "parent_03",
                "studentList": [
                    "zhiwei_03"
                ]
            }
        ]
    }
}
</pre>
<br/>
{| class="wikitable"
|+返回参数
|-
| style="width:80px; text-align:center;" | 参数
| style="width:100px; text-align:center;" | 类型
| style="width:150px; text-align:center;" | 描述
|-
|id
|string
|平台内的唯一 id
|-
|name
|string
|姓名
|-
|roleList
|array
|角色数组
|}

=== 查询学生列表 ===
请求方式：POST <br/>
请求示例:  [apiBaseUrl]/queryStudents?orgId=ORGID&timestamp=TIMESTAMP&sign=SIGN 
{| class="wikitable"
|+请求参数
|-
| style="width:60px; text-align:center;" | 参数
| style="width:60px; text-align:center;" | 类型
| style="width:80px; text-align:center;" | 是否必填
| style="width:60px; text-align:center;" | 描述
|-
|orgId
|string
|是
|学校 id
|}


'''返回样例'''
<pre>
{
    "code": 0,
    "msg": "成功",
    "data": [
        {
            "id": "zhiwei_01",
            "schoolId": "20190101",
            "name": "刘备",
            "gender": "男",
            "grade": 10,
            "class": 1
        },
        {
            "id": "zhiwei_02",
            "schoolId": "20190102",
            "name": "关羽",
            "gender": "男",
            "grade": 11,
            "class": 2
        },
        {
            "id": "zhiwei_03",
            "schoolId": "20190103",
            "name": "张飞",
            "gender": "男",
            "grade": 12,
            "class": 3
        }
    ]
}
</pre>


{| class="wikitable"
|+返回参数
|-
| style="width:40px; text-align:center;" | 参数
| style="width:150px; text-align:center;" | 类型
| style="width:300px; text-align:center;" | 描述
|-
|id
|string
|学生在平台内的唯一 id
|-
|schoolId
|string
|学号。要求同一个学校内唯一
|-
|name
|string
|姓名
|-
|gender
|enum ("男", "女")
|性别
|-
|grade
|int
|年级
|-
|class
|int
|班级。必须为纯整数，不能含有其他字符
|}

=== 查询管理员列表 ===
请求方式：POST  <br/>
请求示例: [apiBaseUrl]/queryAdmins?orgId=ORGID&timestamp=TIMESTAMP&sign=SIGN
{| class="wikitable"
|+访问参数
|-
| style="width:80px; text-align:center;" | 参数
| style="width:150px; text-align:center;" | 类型
| style="width:100px; text-align:center;" | 是否必填
| style="width:220px; text-align:center;" | 描述
|-
|orgId
|string
|是
|学校的唯一 id
|}

<br/>
'''返回样例'''
<pre>
{
    "code": 0,
    "msg": "成功",
    "data": [
        {
            "id": "zhiwei_07",
            "name": "陈大文"
        },
        {
            "id": "zhiwei_08",
            "name": "张伟"
        },
        {
            "id": "zhiwei_09",
            "name": "杨红"
        }
    ]
}
</pre>
<br/>
{| class="wikitable"
|+返回参数
|-
| style="width:80px; text-align:center;" | 参数
| style="width:100px; text-align:center;" | 类型
| style="width:150px; text-align:center;" | 描述
|-
|id
|string
|平台内的唯一 id
|-
|name
|string
|姓名
|}

=== 查询教师列表 ===
请求方式：POST  <br/>
请求示例: [apiBaseUrl]/queryTeachers?orgId=ORGID&timestamp=TIMESTAMP&sign=SIGN
{| class="wikitable"
|+访问参数
|-
| style="width:80px; text-align:center;" | 参数
| style="width:150px; text-align:center;" | 类型
| style="width:100px; text-align:center;" | 是否必填
| style="width:220px; text-align:center;" | 描述
|-
|orgId
|string
|是
|学校的唯一 id
|}

<br/>
'''返回样例'''
<pre>
{
    "code": 0,
    "msg": "成功",
    "data": [
        {
            "id": "zhiwei_04",
            "name": "孔明"
        },
        {
            "id": "zhiwei_05",
            "name": "郭嘉"
        },
        {
            "id": "zhiwei_06",
            "name": "单福"
        }
    ]
}
</pre>
<br/>
{| class="wikitable"
|+返回参数
|-
| style="width:80px; text-align:center;" | 参数
| style="width:100px; text-align:center;" | 类型
| style="width:150px; text-align:center;" | 描述
|-
|id
|string
|平台内的唯一 id
|-
|name
|string
|姓名
|}

=== 查询家长列表 ===
请求方式：POST <br/>
请求示例: [apiBaseUrl]/querys?orgId=ORGID&timestamp=TIMESTAMP&sign=SIGN
{| class="wikitable"
|+访问参数
|-
| style="width:40px; text-align:center;" | 参数
| style="width:100px; text-align:center;" | 类型
| style="width:100px; text-align:center;" | 是否必填
| style="width:180px; text-align:center;" | 描述
|-
|orgId
|string
|是
|学校的唯一 id
|}



'''返回样例'''
<pre>
{
    "code": 0,
    "msg": "成功",
    "data": [
        {
            "id": "parent_01",
            "studentList": [
                "stu_01"
            ]
        },
        {
            "id": "parent_02",
            "studentList": [
                "stu_02",
                "stu_03"
            ]
        },
        {
            "id": "parent_03",
            "studentList": [
                "stu_04",
                "stu_05",
                "stu_06"
            ]
        }
    ]
}
</pre>


{| class="wikitable"
|+返回参数
|-
| style="width:140px; text-align:center;" | 参数
| style="width:100px; text-align:center;" | 类型
| style="width:180px; text-align:center;" | 描述
|-
|id
|string
|家长在平台内的唯一 id
|-
|studentList
|array
|家长关联的学生 id数组
|}

== 更新用户 ==

== 查询班级任教信息列表 ==

== 更新班级任教信息列表 ==

== 常见问题 ==

== 附录 ==

=== 签名参数sign生成说明 ===
<code>第一步：</code>对传入的参数按照键名排序<br/>
<code>第二步：</code>使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串stringA <br/>
<code>第三步：</code>在stringA最后拼接上“&key=[平台密钥]”得到stringSignTemp字符串，并对stringSignTemp进行MD5运算<br/>
<code>第四步：</code>得到最终请求字符串sign<br/>
<br/>PHP签名算法示例：<br/>
<pre>
//$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);
</pre>

----
=== 返回结果 ===
{| class="wikitable"
|-
| style="width:200px; text-align:center;" | 参数名称
| style="width:200px; text-align:center;" | 类型
| style="width:450px; text-align:center;" | 描述
|-
|code
|int
|公共返回码，详见附录公共返回码
|-
|msg
|string
|返回信息
|-
|data
|object
|返回的查询或操作数据,数据可能是对象或数组。具体根据每个API而定。
|}

返回示例：
<pre>
{
    "code": "10000",
    "msg": "成功",
    "data": [
        {
            "userName": "成绩云",
            "schoolId": 101,
        }
    ]
}
</pre>

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

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