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

== <p style="background:#6a9ee4;padding:8px 12px;color:#ffffff;">前言</p> ==

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

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

然后提供一个接口URL前缀'''[apiBaseUrl]'''，后面所有的接口都基于这个前缀。凡是接口URL是https://chengjiyun.com前缀的，说明这个接口由第三方向成绩云发起请求。而如果接口URL前缀是'''[apiBaseUrl]'''，说明接口是由成绩云向第三方发起请求。

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

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

;<p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">接口说明</p><br/>
请求方法:<code>GET</code><br/>
接口方向:<code>第三方</code>→<code>成绩云</code><br/>
PC版登录URL：https://chengjiyun.com/portal/'''[platform]'''?orgId='''[orgId]'''&account='''[account]'''&timestamp='''[timestamp]'''&sign='''[sign]'''<br/>
移动版登录URL：https://chengjiyun.com/mobile-portal/'''[platform]'''?orgId='''[orgId]'''&account='''[account]'''&timestamp='''[timestamp]'''&sign='''[sign]'''<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
|是
|时间戳（Unixtime），有效时长7200秒
|-
|sign
|string
|是
|签名, 详见附录[https://chengjiyun.com/wiki/index.php?title=%E6%88%90%E7%BB%A9%E4%BA%91%E6%8E%A5%E5%8F%A3%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#.E7.AD.BE.E5.90.8D.E5.8F.82.E6.95.B0sign.E7.94.9F.E6.88.90.E8.AF.B4.E6.98.8E 签名参数sign生成说明]
|}

== <p style="background:#6a9ee4;padding:8px 12px;color:#ffffff;">查询用户</p> ==

=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">查询所有用户列表</p> ===
此接口由成绩云向第三方发起请求，获取用户列表。

成绩云仅需要4种用户角色：学生，教师，管理员，家长。<br/>
此接口是下面其它接口的超集，后面的接口通过role参数查询子集。当指定了role参数后，返回结果中，可忽略用户的角色属性。<br/><br/>

;<span style="font-size:15px;">接口说明</span>
请求方式：<code>GET</code>  <br/>
请求URL:'''[apiBaseUrl]'''/queryUsers?orgId='''[orgId]'''&timestamp='''[timestamp]'''&sign='''[sign]'''  <br/>
请求参数:<br/>
{| class="wikitable"
|-
| style="width:80px; text-align:center;" | 参数
| style="width:150px; text-align:center;" | 类型
| style="width:100px; text-align:center;" | 是否必填
| style="width:250px; text-align:center;" | 描述
|-
|orgId
|string
|是
|学校 ID
|-
|role
|string
|否
|角色。可选值为“学生”、“教师”、“管理员、“家长”
|-
|timestamp
|int
|是
|时间戳（Unixtime）
|-
|sign
|string
|是
|签名。详见附录[https://chengjiyun.com/wiki/index.php?title=%E6%88%90%E7%BB%A9%E4%BA%91%E6%8E%A5%E5%8F%A3%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#.E7.AD.BE.E5.90.8D.E5.8F.82.E6.95.B0sign.E7.94.9F.E6.88.90.E8.AF.B4.E6.98.8E 签名参数sign生成说明]
|}

返回参数:<br/>
{| class="wikitable"
|-
| style="width:40px; text-align:center;" | 参数
| style="width:150px; text-align:center;" | 类型
| style="width:200px; text-align:center;" | 描述
|-
|account
|string
|账号
|-
|name
|string
|姓名
|-
|roleList
|array
|角色数组
|-
|schoolId
|string
|学号。要求同一个学校内唯一
|-
|gender
|string
|性别，可选“男”、“女”或“”（空字符串）
|-
|grade
|int
|年级，7表示初一，10表示高一，以此类推。
|-
|class
|int
|班级。必须为纯整数，不能含有其他字符
|}

'''返回样例'''
<pre>
{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "account": "zhiwei_01",
            "schoolId": "20190101",
            "name": "刘备",
            "gender": "男",
            "grade": 10,
            "class": 1,
            "roleList": [
                "学生"
            ]
        },
        {
            "account": "zhiwei_06",
            "name": "单福",
            "roleList": [
                "管理员",
                "教师"
            ]
        },
        {
            "account": "parent_01",
            "name": "费曼",
            "roleList": [
                "家长"
            ]
        },
    ]
}
</pre>
<br/>

=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">查询学生列表</p> ===
此接口由成绩云向第三方发起请求，获取学生用户列表。

;<p style="font-size:15px;">接口说明</p>
请求方式：<code>GET</code> <br/>
请求URL:  '''[apiBaseUrl]'''/queryUsers?orgId='''[orgId]'''&timestamp='''[timestamp]'''&role=学生&sign='''[sign]'''<br/>
请求参数：
{| class="wikitable"
|-
| style="width:80px; text-align:center;" | 参数
| style="width:150px; text-align:center;" | 类型
| style="width:100px; text-align:center;" | 是否必填
| style="width:250px; text-align:center;" | 描述
|-
|orgId
|string
|是
|学校 ID
|-
|role
|string
|是
|填“学生”
|-
|timestamp
|int
|是
|时间戳（Unixtime）
|-
|sign
|string
|是
|签名。详见附录[https://chengjiyun.com/wiki/index.php?title=%E6%88%90%E7%BB%A9%E4%BA%91%E6%8E%A5%E5%8F%A3%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#.E7.AD.BE.E5.90.8D.E5.8F.82.E6.95.B0sign.E7.94.9F.E6.88.90.E8.AF.B4.E6.98.8E 签名参数sign生成说明]
|}

返回参数:<br/>
{| class="wikitable"
|-
| style="width:40px; text-align:center;" | 参数
| style="width:150px; text-align:center;" | 类型
| style="width:300px; text-align:center;" | 描述
|-
|account
|string
|账号
|-
|schoolId
|string
|学号。要求同一个学校内唯一
|-
|name
|string
|姓名
|-
|gender
|string
|性别，可选“男”、“女”或“”（空字符串）
|-
|grade
|int
|年级
|-
|class
|int
|班级。必须为纯整数，不能含有其他字符
|}

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

=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">查询管理员列表</p> ===
此接口由成绩云向第三方发起请求，获取管理员用户列表。
;<p style="font-size:15px;">接口说明</p>
请求方式：<code>GET</code>  <br/>
请求url:  '''[apiBaseUrl]'''/queryUsers?orgId='''[orgId]'''&timestamp='''[timestamp]'''&role=管理员&sign='''[sign]''' <br/>
请求参数:
{| class="wikitable"
|-
| style="width:80px; text-align:center;" | 参数
| style="width:150px; text-align:center;" | 类型
| style="width:100px; text-align:center;" | 是否必填
| style="width:250px; text-align:center;" | 描述
|-
|orgId
|string
|是
|学校 ID
|-
|role
|string
|是
|填“管理员”
|-
|timestamp
|int
|是
|时间戳（Unixtime）
|-
|sign
|string
|是
|签名。详见附录[https://chengjiyun.com/wiki/index.php?title=%E6%88%90%E7%BB%A9%E4%BA%91%E6%8E%A5%E5%8F%A3%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#.E7.AD.BE.E5.90.8D.E5.8F.82.E6.95.B0sign.E7.94.9F.E6.88.90.E8.AF.B4.E6.98.8E 签名参数sign生成说明]
|}

返回参数:<br/>
{| class="wikitable"
|-
| style="width:80px; text-align:center;" | 参数
| style="width:100px; text-align:center;" | 类型
| style="width:150px; text-align:center;" | 描述
|-
|account
|string
|账号
|-
|name
|string
|姓名
|}

'''返回样例'''
<pre>
{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "account": "zhiwei_07",
            "name": "陈大文"
        },
        {
            "account": "zhiwei_08",
            "name": "张伟"
        },
        {
            "id": "zhiwei_09",
            "name": "杨红"
        }
    ]
}
</pre>
<br/>

=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">查询教师列表</p> ===
此接口由成绩云向第三方发起请求，获取教师用户列表。
;<p style="font-size:15px;">接口说明</p>
请求方式：<code>GET</code>  <br/>
请求url: '''[apiBaseUrl]'''/queryUsers?orgId='''[orgId]'''&timestamp='''[timestamp]'''&role=教师&sign='''[sign]''' <br/>
请求参数:
{| class="wikitable"
|-
| style="width:80px; text-align:center;" | 参数
| style="width:150px; text-align:center;" | 类型
| style="width:100px; text-align:center;" | 是否必填
| style="width:250px; text-align:center;" | 描述
|-
|orgId
|string
|是
|学校 ID
|-
|role
|string
|是
|填“教师”
|-
|timestamp
|int
|是
|时间戳（Unixtime）
|-
|sign
|string
|是
|签名。详见附录[https://chengjiyun.com/wiki/index.php?title=%E6%88%90%E7%BB%A9%E4%BA%91%E6%8E%A5%E5%8F%A3%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#.E7.AD.BE.E5.90.8D.E5.8F.82.E6.95.B0sign.E7.94.9F.E6.88.90.E8.AF.B4.E6.98.8E 签名参数sign生成说明]
|}

返回参数:<br/>
{| class="wikitable"
|-
| style="width:80px; text-align:center;" | 参数
| style="width:100px; text-align:center;" | 类型
| style="width:150px; text-align:center;" | 描述
|-
|account
|string
|教师的账户 ID
|-
|name
|string
|姓名
|}

<br/>
'''返回样例'''
<pre>
{
    "code": 0,
    "msg": "成功",
    "data": [
        {
            "account": "zhiwei_04",
            "name": "孔明"
        },
        {
            "account": "zhiwei_05",
            "name": "郭嘉"
        },
        {
            "account": "zhiwei_06",
            "name": "单福"
        }
    ]
}
</pre>

=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">查询家长列表</p> ===
此接口由成绩云向第三方发起请求，获取家长用户列表。
;<p style="font-size:15px;">接口说明</p>
请求方式：<code>GET</code> <br/>
请求url:  '''[apiBaseUrl]'''/queryUsers?orgId='''[orgId]'''&timestamp='''[timestamp]'''&role=家长&sign='''[sign]''' <br/>
请求参数:
{| class="wikitable"
|-
| style="width:80px; text-align:center;" | 参数
| style="width:150px; text-align:center;" | 类型
| style="width:100px; text-align:center;" | 是否必填
| style="width:250px; text-align:center;" | 描述
|-
|orgId
|string
|是
|学校 ID
|-
|role
|string
|是
|填“家长”
|-
|timestamp
|int
|是
|时间戳（Unixtime）
|-
|sign
|string
|是
|签名。详见附录[https://chengjiyun.com/wiki/index.php?title=%E6%88%90%E7%BB%A9%E4%BA%91%E6%8E%A5%E5%8F%A3%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#.E7.AD.BE.E5.90.8D.E5.8F.82.E6.95.B0sign.E7.94.9F.E6.88.90.E8.AF.B4.E6.98.8E 签名参数sign生成说明]
|}

返回参数:<br/>
{| class="wikitable"
|-
| style="width:140px; text-align:center;" | 参数
| style="width:100px; text-align:center;" | 类型
| style="width:180px; text-align:center;" | 描述
|-
|account
|string
|账号
|-
|name
|string
|姓名
|-
|studentList
|array
|家长关联的学生 ID数组
|}


'''返回样例'''
<pre>
{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "account": "parent_01",
            "name": "费曼",
            "studentList": [
                "stu_01"
            ]
        },
        {
            "account": "parent_02",
            "name": "图灵",
            "studentList": [
                "stu_02",
                "stu_03"
            ]
        },
        {
            "account": "parent_03",
            "name": "香侬",
            "studentList": [
                "stu_04",
                "stu_05",
                "stu_06"
            ]
        }
    ]
}
</pre>

== <p style="background:#6a9ee4;padding:8px 12px;color:#ffffff;">管理用户</p> ==
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">新增用户</p> ===
第三方平台新增用户信息后，主动推送新增的用户到成绩云，通知成绩云新增相应用户。
;<span style="font-size:15px;">接口说明</span>
请求方式：<code>POST（Content-Type:application/json）</code>  <br/>
接口方向:<code>第三方</code>→<code>成绩云</code><br/>
请求url: https://chengjiyun.com/vendor-api/addUser?platform='''[platform]'''&orgId='''[orgId]'''&timestamp='''[timestamp]'''&sign='''[sign]'''<br/>
URL参数说明（并非所有角色都支持全部参数，例如班别信息对家长角色是无效的）:<br/>
{| class="wikitable"
|-
| style="width:80px; text-align:center;" | 参数
| style="width:150px; text-align:center;" | 类型
| style="width:100px; text-align:center;" | 是否必填
| style="width:300px; text-align:center;" | 描述
|-
|platform
|string
|是
|平台ID
|-
|orgId
|string
|是
|学校ID
|-
|timestamp
|int
|是
|时间戳（Unixtime），有效时长600秒
|-
|sign
|string
|是
|签名，只对orgId和timestamp签名，不用对POST数据内容签名。详见附录[https://chengjiyun.com/wiki/index.php?title=%E6%88%90%E7%BB%A9%E4%BA%91%E6%8E%A5%E5%8F%A3%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#.E7.AD.BE.E5.90.8D.E5.8F.82.E6.95.B0sign.E7.94.9F.E6.88.90.E8.AF.B4.E6.98.8E 签名参数sign生成说明]
|}

POST数据结构参数:<br/>
{| class="wikitable"
|-
| style="width:80px; text-align:center;" | 参数
| style="width:150px; text-align:center;" | 类型
| style="width:100px; text-align:center;" | 是否必填
| style="width:350px; text-align:center;" | 描述
|-
|account
|string
|是
|账号
|-
|roleList
|array
|是
|角色（支持管理员、教师、家长、学生）
|-
|name
|string
|是
|姓名
|-
|schoolId
|string
|否
|学号。要求同一个学校内唯一
|-
|gender
|string
|否
|性别，可选“男”、“女”或“”（空字符串）
|-
|grade
|int
|否
|年级，7表示初一，10表示高一，以此类推。
|-
|class
|int
|否
|班级。必须为纯整数，不能含有其他字符
|}

'''请求样例'''

POST数据如下：
<pre>
    [
        {
            "account": "zhiwei_01",
            "name": "刘备",
            "class": 2,
            "roleList": [
                 "管理员",
                 "教师",
            ]
        },
        {
            "account": "zhiwei_06",
            "name": "单福",
            "gender": "男",
             "roleList": [
                 "教师",
            ]
        },
        {
            "account": "parent_01",
            "name": "费曼",
             "roleList": [
                 "学生",
            ]
        }
    ]
</pre>
<br/>


'''返回样例'''
<pre>
{
    "code": 0,
    "msg": "success",
}
</pre>
<br/>

=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">删除用户</p> ===
第三方平台删除用户信息后，主动推送删除的用户到成绩云，通知成绩云进行删除。
;<span style="font-size:15px;">接口说明</span>
请求方式：<code>POST（Content-Type:application/json）</code>  <br/>
接口方向:<code>第三方</code>→<code>成绩云</code><br/>
请求url: https://chengjiyun.com/vendor-api/deleteUser?platform='''[platform]'''&orgId='''[orgId]'''&timestamp='''[timestamp]'''&sign='''[sign]'''<br/>
URL参数说明:<br/>
{| class="wikitable"
|-
| style="width:80px; text-align:center;" | 参数
| style="width:150px; text-align:center;" | 类型
| style="width:100px; text-align:center;" | 是否必填
| style="width:300px; text-align:center;" | 描述
|-
|platform
|string
|是
|平台ID
|-
|orgId
|string
|是
|学校ID
|-
|timestamp
|int
|是
|时间戳（Unixtime），有效时长600秒
|-
|sign
|string
|是
|签名，只对orgId和timestamp签名，不用对POST数据内容签名。详见附录[https://chengjiyun.com/wiki/index.php?title=%E6%88%90%E7%BB%A9%E4%BA%91%E6%8E%A5%E5%8F%A3%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#.E7.AD.BE.E5.90.8D.E5.8F.82.E6.95.B0sign.E7.94.9F.E6.88.90.E8.AF.B4.E6.98.8E 签名参数sign生成说明]
|}

POST数据结构参数:<br/>
{| class="wikitable"
|-
| style="width:80px; text-align:center;" | 参数
| style="width:150px; text-align:center;" | 类型
| style="width:100px; text-align:center;" | 是否必填
| style="width:350px; text-align:center;" | 描述
|-
|account
|string
|是
|账号
|}

'''请求样例'''

POST数据如下：
<pre>
   [
      "zhiwei_01",
      "zhiwei_06",
      "parent_01"
   ]
</pre>
<br/>


'''返回样例'''
<pre>
{
    "code": 0,
    "msg": "success",
}
</pre>
<br/>

=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">更新用户</p> ===
第三方平台修改用户信息后，主动推送被修改用户到成绩云进行修改。
;<span style="font-size:15px;">接口说明</span>
请求方式：<code>POST（Content-Type:application/json）</code>  <br/>
接口方向:<code>第三方</code>→<code>成绩云</code><br/>
请求url: https://chengjiyun.com/vendor-api/updateUser?platform='''[platform]'''&orgId='''[orgId]'''&timestamp='''[timestamp]'''&sign='''[sign]'''<br/>
URL参数说明:<br/>
{| class="wikitable"
|-
| style="width:80px; text-align:center;" | 参数
| style="width:150px; text-align:center;" | 类型
| style="width:100px; text-align:center;" | 是否必填
| style="width:300px; text-align:center;" | 描述
|-
|platform
|string
|是
|平台ID
|-
|orgId
|string
|是
|学校ID
|-
|timestamp
|int
|是
|时间戳（Unixtime），有效时长600秒
|-
|sign
|string
|是
|签名，只对orgId和timestamp签名，不用对POST数据内容签名。详见附录[https://chengjiyun.com/wiki/index.php?title=%E6%88%90%E7%BB%A9%E4%BA%91%E6%8E%A5%E5%8F%A3%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#.E7.AD.BE.E5.90.8D.E5.8F.82.E6.95.B0sign.E7.94.9F.E6.88.90.E8.AF.B4.E6.98.8E 签名参数sign生成说明]
|}

POST数据结构参数（并非所有角色都支持全部参数的修改，例如班别信息对家长角色是无效的）:<br/>
{| class="wikitable"
|-
| style="width:80px; text-align:center;" | 参数
| style="width:150px; text-align:center;" | 类型
| style="width:100px; text-align:center;" | 是否必填
| style="width:350px; text-align:center;" | 描述
|-
|account
|string
|是
|账号
|-
|name
|string
|否
|姓名
|-
|schoolId
|string
|否
|学号。要求同一个学校内唯一
|-
|gender
|string
|否
|性别，可选“男”、“女”或“”（空字符串）
|-
|grade
|int
|否
|年级，7表示初一，10表示高一，以此类推。
|-
|class
|int
|否
|班级。必须为纯整数，不能含有其他字符
|}

'''请求样例'''

POST数据如下：
<pre>
    [
        {
            "account": "zhiwei_01",
            "name": "刘备",
            "class": 2
        },
        {
            "account": "zhiwei_06",
            "name": "单福",
            "gender": "男"
        },
        {
            "account": "parent_01",
            "name": "费曼"
        },
    ]
</pre>
<br/>


'''返回样例'''
<pre>
{
    "code": 0,
    "msg": "success",
}
</pre>
<br/>

== <p style="background:#6a9ee4;padding:8px 12px;color:#ffffff;">查询班级任教信息列表</p> ==
成绩云向第三方平台发起请求，查询班级任教信息。
<p style="font-size:15px;">'''接口说明'''</p>
请求方式：<code>GET</code> <br/>
请求url:  '''[apiBaseUrl]'''/queryClassStatus?orgId='''[orgId]'''&timestamp='''[timestamp]'''&sign='''[sign]'''<br/>
'''请求参数'''：
{| class="wikitable"
|-
| style="width:80px; text-align:center;" | 参数
| style="width:150px; text-align:center;" | 类型
| style="width:100px; text-align:center;" | 是否必填
| style="width:250px; text-align:center;" | 描述
|-
|orgId
|string
|是
|学校 ID
|-
|timestamp
|int
|是
|时间戳（Unixtime）
|-
|sign
|string
|是
|签名。详见附录[https://chengjiyun.com/wiki/index.php?title=%E6%88%90%E7%BB%A9%E4%BA%91%E6%8E%A5%E5%8F%A3%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#.E7.AD.BE.E5.90.8D.E5.8F.82.E6.95.B0sign.E7.94.9F.E6.88.90.E8.AF.B4.E6.98.8E 签名参数sign生成说明]
|}

'''返回参数''':<br/>
{| class="wikitable"
|-
| style="width:30px; text-align:center;" | 参数
| style="width:40px; text-align:center;" | 类型
| style="width:300px; text-align:center;" | 描述
|-
|year
|int
|入学年份
|-
|grade
|int
|年级
|-
|class
|int
|班级。必须为纯整数，不能含有其他字符
|-
|headTeacher
|string
|班主任的账户 ID
|-
|subject
|enum(0,1,2)
|0=>未指定，1=>文科， 2=>理科
|-
|courseTeacherList
|object
|科目任教信息. 以科目的中文名为属性名, 教师的账户 ID 为 属性值的结构对象
例如： 
<pre>
{
 "语文":"zhiwei_04", 
 "数学":"zhiwei_05",
 "英语":"zhiwei_06"
}
</pre>
|}

'''返回样例'''
<pre>
{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "year": 2018,
            "grade": 10,
            "class": 1,
            "headTeacher": "zhiwei_04",
            "subject": 1,
            "courseTeacherList": {
                "语文": "zhiwei_04",
                "数学": "zhiwei_05",
                "英语": "zhiwei_06"
            }
        },
        {
            "year": 2018,
            "grade": 10,
            "class": 2,
            "headTeacher": "zhiwei_05",
            "subject": 1,
            "courseTeacherList": {
                "语文": "zhiwei_04",
                "数学": "zhiwei_05",
                "英语": "zhiwei_06"
            }
        }
    ]
}
</pre>

== <p style="background:#6a9ee4;padding:8px 12px;color:#ffffff;">通知更新班级任教信息列表</p> ==
第三方平台修改班级任教相关的数据后，需要主动通知成绩云重新读取第三方平台的数据更新。此接口无需传入更新的数据，只需通知成绩云即可。

;<span style="font-size:15px;">接口说明</span>
请求方式：<code>GET</code>  <br/>
接口方向:<code>第三方</code>→<code>成绩云</code><br/>
请求URL: https://chengjiyun.com/vendor-api/update/classStatus?orgId='''[orgId]'''&timestamp='''[timestamp]'''&sign='''[sign]'''<br/>
URL参数说明:<br/>
{| class="wikitable"
|-
| style="width:80px; text-align:center;" | 参数
| style="width:150px; text-align:center;" | 类型
| style="width:100px; text-align:center;" | 是否必填
| style="width:300px; text-align:center;" | 描述
|-
|orgId
|string
|是
|学校ID
|-
|timestamp
|int
|是
|时间戳（Unixtime），有效时长600秒
|-
|sign
|string
|是
|签名。详见附录[https://chengjiyun.com/wiki/index.php?title=%E6%88%90%E7%BB%A9%E4%BA%91%E6%8E%A5%E5%8F%A3%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#.E7.AD.BE.E5.90.8D.E5.8F.82.E6.95.B0sign.E7.94.9F.E6.88.90.E8.AF.B4.E6.98.8E 签名参数sign生成说明]
|}

== <p style="background:#6a9ee4;padding:8px 12px;color:#ffffff;">查询考试成绩</p> ==

=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">查询考试列表</p> ===
成绩云向第三方平台发起请求，获取考试列表。
;<span style="font-size:15px;">接口说明</span>
请求方式：<code>GET</code>  <br/>
请求URL:  '''[apiBaseUrl]'''/queryExam?orgId='''[orgId]'''&timestamp='''[timestamp]'''&sign='''[sign]''' <br/>
返回格式：<code>Content-Type:application/json</code><br/>
请求参数:<br/>
{| class="wikitable"
|-
| style="width:80px; text-align:center;" | 参数
| style="width:50px; text-align:center;" | 类型
| style="width:50px; text-align:center;" | 是否必填
| style="width:300px; text-align:center;" | 描述
|-
|orgId
|string
|是
|学校ID
|-
|timestamp
|int
|是
|时间戳（Unixtime），有效时长600秒
|-
|sign
|string
|是
|签名。详见附录[https://chengjiyun.com/wiki/index.php?title=%E6%88%90%E7%BB%A9%E4%BA%91%E6%8E%A5%E5%8F%A3%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#.E7.AD.BE.E5.90.8D.E5.8F.82.E6.95.B0sign.E7.94.9F.E6.88.90.E8.AF.B4.E6.98.8E 签名参数sign生成说明]
|}

返回参数:<br/>
{| class="wikitable"
|-
| style="width:140px; text-align:center;" | 参数
| style="width:100px; text-align:center;" | 类型
| style="width:100px; text-align:center;" | 是否允许为 null
| style="width:300px; text-align:center;" | 描述
|-
|examId
|string
|否
|考试ID
|-
|title
|string
|否
|考试标题
|-
|grade
|int
|是
|年级(可取值1,2,3,4,5,6,7,8,9,10,11,12)
|-
|year
|int
|是
|入学年份(学生入学时的年份)
|}


'''返回样例'''
<pre>
{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "examId": "233",
            "title": "考试标题",
            "grade": 11,
            "year": 2017,
        },
        {
            "examId": "234",
            "title": "考试标题",
            "grade": 11,
            "year": 2017,
        }
    ]
}
</pre>

=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">查询单次考试总分成绩</p> ===
成绩云向第三方平台发起请求，获取单次考试详细成绩数据。
;<span style="font-size:15px;">接口说明</span>
请求方式：<code>GET</code>  <br/>
请求url:  '''[apiBaseUrl]'''/queryExamDetail?orgId='''[orgId]'''&timestamp='''[timestamp]'''&sign='''[sign]''' <br/>
返回格式：<code>Content-Type:application/json</code><br/>
请求参数:<br/>
{| class="wikitable"
|-
| style="width:80px; text-align:center;" | 参数
| style="width:50px; text-align:center;" | 类型
| style="width:50px; text-align:center;" | 是否必填
| style="width:300px; text-align:center;" | 描述
|-
|orgId
|string
|是
|学校ID
|-
|examId
|string
|是
|考试ID
|-
|timestamp
|int
|是
|时间戳（Unixtime），有效时长600秒
|-
|sign
|string
|是
|签名。详见附录[https://chengjiyun.com/wiki/index.php?title=%E6%88%90%E7%BB%A9%E4%BA%91%E6%8E%A5%E5%8F%A3%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#.E7.AD.BE.E5.90.8D.E5.8F.82.E6.95.B0sign.E7.94.9F.E6.88.90.E8.AF.B4.E6.98.8E 签名参数sign生成说明]
|}

返回参数:<br/>
{| class="wikitable"
|-
| style="width:140px; text-align:center;" | 参数
| style="width:100px; text-align:center;" | 类型
| style="width:180px; text-align:center;" | 描述
|-
|account
|string
|学生账号
|-
|scores
|array
|科目成绩
|}


'''返回样例'''
<pre>
{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "account": "CJ20180101",
            "scores": {
                "语文": 120,
                "数学": 118,
                "英语": 121,
                "物理": 89,
                "化学": 78,
                "生物": 88,
                "政治": 78,
                "历史": 85,
                "地理": 83,
            }
        },
        {
            "account": "CJ20180102",
            "scores": {
                "语文": 118,
                "数学": 136,
                "英语": 98
            }
        }
    ]
}
</pre>

=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">查询考试小题分科目列表</p> ===
成绩云向第三方平台发起请求，获取考试小题分列表。
;<span style="font-size:15px;">接口说明</span>
请求方式：<code>GET</code>  <br/>
请求url:  '''[apiBaseUrl]'''/queryQuestionList?orgId='''[orgId]'''&timestamp='''[timestamp]'''&examId='''[examId]'''&sign='''[sign]''' <br/>
返回格式：<code>Content-Type:application/json</code><br/>
请求参数:<br/>
{| class="wikitable"
|-
| style="width:80px; text-align:center;" | 参数
| style="width:50px; text-align:center;" | 类型
| style="width:50px; text-align:center;" | 是否必填
| style="width:300px; text-align:center;" | 描述
|-
|orgId
|string
|是
|学校ID
|-
|examId
|string
|是
|考试ID
|-
|timestamp
|int
|是
|时间戳（Unixtime），有效时长600秒
|-
|sign
|string
|是
|签名。详见附录[https://chengjiyun.com/wiki/index.php?title=%E6%88%90%E7%BB%A9%E4%BA%91%E6%8E%A5%E5%8F%A3%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#.E7.AD.BE.E5.90.8D.E5.8F.82.E6.95.B0sign.E7.94.9F.E6.88.90.E8.AF.B4.E6.98.8E 签名参数sign生成说明]
|}

返回参数:<br/>
{| class="wikitable"
|-
| style="width:140px; text-align:center;" | 参数
| style="width:100px; text-align:center;" | 类型
| style="width:100px; text-align:center;" | 是否允许为 null
| style="width:300px; text-align:center;" | 描述
|-
|examId
|string
|否
|考试ID
|-
|courses
|array
|否
|有分析小题分的科目集合
|}


'''返回样例'''
<pre>
{
    "code": 0,
    "msg": "success",
    "data": 
        {
            "examId": "233",
            "courses": [
               "语文",
               "数学",
            ],
        }
}
</pre>

=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">查询单次考试小题分试卷结构</p> ===
成绩云向第三方平台发起请求，获取单次考试某一科目小题分试卷结构。
<p style="font-size:15px;">'''接口说明'''</p>
请求方式：<code>GET</code> <br/>
请求url:  '''[apiBaseUrl]'''/queryQuestionStructure?orgId='''[orgId]'''&examId='''[examId]'''&course='''[course]'''&timestamp='''[timestamp]'''&sign='''[sign]'''<br/>
'''请求参数'''：
{| class="wikitable"
|-
| style="width:80px; text-align:center;" | 参数
| style="width:100px; text-align:center;" | 类型
| style="width:100px; text-align:center;" | 是否必填
| style="width:250px; text-align:center;" | 描述
|-
|orgId
|string
|是
|学校 ID
|-
|examId
|string
|是
|考试 ID
|-
|course
|string
|是
|科目的中文名
|-
|timestamp
|int
|是
|时间戳（Unixtime）
|-
|sign
|string
|是
|签名。详见附录[https://chengjiyun.com/wiki/index.php?title=%E6%88%90%E7%BB%A9%E4%BA%91%E6%8E%A5%E5%8F%A3%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#.E7.AD.BE.E5.90.8D.E5.8F.82.E6.95.B0sign.E7.94.9F.E6.88.90.E8.AF.B4.E6.98.8E 签名参数sign生成说明]
|}

'''返回参数''':<br/>
下面参数的具体定义，请阅读理解  [https://chengjiyun.com/wiki/index.php?title=%E8%AF%95%E5%8D%B7%E7%BB%93%E6%9E%84 试卷结构 ]
{| class="wikitable"
|-
| style="width:30px; text-align:center;" | 参数
| style="width:200px; text-align:center;" | 类型
| style="width:120px; text-align:center;" | 是否允许为 null
| style="width:100px; text-align:center;" | 描述
|-
|number
|string
|否
|题号
|-
|subjective
|enum("主观题"，"客观题")
|否
|类型
|-
|score
|float
|否
|满分值
|-
|scroll
|enum("一卷"，"二卷")
|否
|卷别
|-
|selection
|string
|是
| 选做题分组
|-
|type
|string
|是
|题型
|-
|knowledge
|string
|是
|知识点
|-
|ability
|string
|是
|能力
|}

'''返回样例'''
<pre>
{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "number": "1",
            "subjective": "客观题",
            "score": 5,
            "scroll": "一卷",
            "selection": "A1",
            "type": "基础选择",
            "knowledge": "语文基础知识",
            "ability": "掌握"
        },
        {
            "number": "2",
            "subjective": "主观题",
            "score": 10,
            "scroll": "二卷",
            "selection": null,
            "type": null,
            "knowledge": null,
            "ability": null
        }
    ]
}

</pre>

=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">查询单次考试小题分成绩</p> ===
成绩云向第三方平台发起请求，获取单次考试某一科目小题分所有学生分数。
<p style="font-size:15px;">'''接口说明'''</p>
请求方式：<code>GET</code> <br/>
请求url:  '''[apiBaseUrl]'''/queryQuestionScore?orgId='''[orgId]'''&examId='''[examId]'''&course='''[course]'''&timestamp='''[timestamp]'''&sign='''[sign]'''<br/>
'''请求参数'''：
{| class="wikitable"
|-
| style="width:100px; text-align:center;" | 参数
| style="width:100px; text-align:center;" | 类型
| style="width:100px; text-align:center;" | 是否必填
| style="width:300px; text-align:center;" | 描述
|-
|orgId
|string
|是
|学校 ID
|-
|examId
|string
|是
|考试 ID
|-
|course
|string
|是
|科目的中文名
|-
|timestamp
|int
|是
|时间戳（Unixtime）
|-
|sign
|string
|是
|签名。详见附录[https://chengjiyun.com/wiki/index.php?title=%E6%88%90%E7%BB%A9%E4%BA%91%E6%8E%A5%E5%8F%A3%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#.E7.AD.BE.E5.90.8D.E5.8F.82.E6.95.B0sign.E7.94.9F.E6.88.90.E8.AF.B4.E6.98.8E 签名参数sign生成说明]
|}

'''返回参数''':<br/>
下面参数的具体定义，请阅读理解  [https://chengjiyun.com/wiki/index.php?title=%E8%AF%95%E5%8D%B7%E7%BB%93%E6%9E%84 试卷结构 ]
{| class="wikitable"
|-
| style="width:100px; text-align:center;" | 参数
| style="width:100px; text-align:center;" | 类型
| style="width:120px; text-align:center;" | 是否允许为 null
| style="width:280px; text-align:center;" | 描述
|-
|account
|string
|否
|学生账户 ID
|-
|scores
|hash
|是
|题号: 分数。分数为 null 时, 表示学生缺答
|}

'''返回样例'''
<pre>
{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "account": "zhiwei_01",
            "scores": {
                "1": 5,
                "2": 8,
                "3.a": 4.5,
                "3.b": 3
            }
        },
        {
            "account": "zhiwei_02",
            "scores": {
                "1": 5,
                "2": 2,
                "3.a": null,
                "3.b": 4
            }
        }
    ]
}


</pre>

== <p style="background:#6a9ee4;padding:8px 12px;color:#ffffff;">常见问题</p> ==

== <p style="background:#6a9ee4;padding:8px 12px;color:#ffffff;">附录</p> ==

=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">签名参数sign生成说明</p> ===
<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/><code>PHP签名算法示例:</code><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'=>'testapi',
   'account'=> 'zhiwei_01',
   'type'=> '高中',
   'timestamp'  => time(),
);
$sign = sign($data, $key);
</pre>

注意：一般接口会有一个timestamp参数，如无特别说明，timestamp的有效时间为600秒（登录接口有效时常为7200秒），超过该时长请求无效，以降低受到重放攻击的风险。此时长在实际使用中可能会做出调整，请尽可能地使用实时时间。

----

=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">返回结果</p> ===
{| 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": 0,
    "msg": "success",
    "data": [
        {
            "userName": "成绩云",
            "schoolId": 101,
        }
    ]
}
</pre>

----

=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">公共返回码</p>  ===
开发者每次调用接口时，可能获得正确或错误的返回码，开发者可以根据返回码信息调试接口，排查错误。
返回码如下:

{| 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
|用户账号已经禁用
|}