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

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

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

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

然后提供一个接口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）
|-
|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;" | 描述
|-
|id
|string
|用户的唯一 ID
|-
|name
|string
|姓名
|-
|roleList
|array
|角色数组
|-
|schoolId
|string
|学号。要求同一个学校内唯一
|-
|gender
|string
|性别，可选“男”、“女”或“”（空字符串）
|-
|grade
|int
|年级，7表示初一，10表示高一，以此类推。
|-
|class
|int
|班级。必须为纯整数，不能含有其他字符
|}

'''返回样例'''
<pre>
{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "id": "zhiwei_01",
            "schoolId": "20190101",
            "name": "刘备",
            "gender": "男",
            "grade": 10,
            "class": 1,
            "roleList": [
                "学生"
            ]
        },
        {
            "id": "zhiwei_06",
            "name": "单福",
            "roleList": [
                "管理员",
                "教师"
            ]
        },
        {
            "id": "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;" | 描述
|-
|id
|string
|学生的账户 ID
|-
|schoolId
|string
|学号。要求同一个学校内唯一
|-
|name
|string
|姓名
|-
|gender
|string
|性别，可选“男”、“女”或“”（空字符串）
|-
|grade
|int
|年级
|-
|class
|int
|班级。必须为纯整数，不能含有其他字符
|}

'''返回样例'''
<pre>
{
    "code": 0,
    "msg": "success",
    "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>

=== <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;" | 描述
|-
|id
|string
|管理员的账户 ID
|-
|name
|string
|姓名
|}

'''返回样例'''
<pre>
{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "id": "zhiwei_07",
            "name": "陈大文"
        },
        {
            "id": "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;" | 描述
|-
|id
|string
|教师的账户 ID
|-
|name
|string
|姓名
|}

<br/>
'''返回样例'''
<pre>
{
    "code": 0,
    "msg": "成功",
    "data": [
        {
            "id": "zhiwei_04",
            "name": "孔明"
        },
        {
            "id": "zhiwei_05",
            "name": "郭嘉"
        },
        {
            "id": "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;" | 描述
|-
|id
|string
|家长的账户 ID
|-
|name
|string
|姓名
|-
|studentList
|array
|家长关联的学生 ID数组
|}


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

== <p style="background:#6a9ee4;padding:8px 12px;color:#ffffff;">更新用户</p> ==
第三方平台修改用户信息后，主动推送被修改用户到成绩云进行修改。
;<span style="font-size:15px;">接口说明</span>
请求方式：<code>POST</code>  <br/>
接口方向:<code>第三方</code>→<code>成绩云</code><br/>
请求url: https://chengjiyun.com/vendor-api/update/user<br/>
请求参数:<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）
|-
|data
|string
|是
|以JSON结构编码的结果集字符串，使用时要先进行JSON解码
|-
|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生成说明]
|}

data参数（并非所有角色都支持全部参数的修改，例如班别信息对家长角色是无效的）:<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;" | 描述
|-
|id
|string
|是
|用户的唯一 id
|-
|name
|string
|否
|姓名
|-
|schoolId
|string
|否
|学号。要求同一个学校内唯一
|-
|gender
|string
|否
|性别，可选“男”、“女”或“”（空字符串）
|-
|grade
|int
|否
|年级，7表示初一，10表示高一，以此类推。
|-
|class
|int
|否
|班级。必须为纯整数，不能含有其他字符
|}

'''请求样例'''

POST数据如下（data是JSON结构的字符串，这里为了便于阅读，做了结构化的显示）：
<pre>
orgId=对接测试学校
timestamp=1547628034
sign=b4fb304c0cfcc43f933e433d72c4d276
data=[
        {
            "id": "zhiwei_01",
            "name": "刘备",
            "class": 2
        },
        {
            "id": "zhiwei_06",
            "name": "单福",
            "gender": "男"
        },
        {
            "id": "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>
{
 "chinese":"zhiwei_04", 
 "maths":"zhiwei_05",
 "english":"zhiwei_06"
}
</pre>
支持下列科目：
<br/>"chinese"（语文）
<br/>"maths" （数学)
<br/>"english" （英语）
<br/>"physics"  （物理）
<br/>"chemistry"  （化学）
<br/>"biology"  （生物）
<br/>"politics"  （政治）
<br/>"history"  （历史）
<br/>"geography"  （地理）
<br/>"pe" （体育）
|}

'''返回样例'''
<pre>
[
    {
        "year": 2018,
        "grade": 10,
        "class": 1,
        "head_uid": "zhiwei_04",
        "subject": 1,
        "courseTeacherList": {
            "chinese": "zhiwei_04",
            "maths": "zhiwei_05",
            "english": "zhiwei_06"
        }
    },
    {
        "year": 2018,
        "grade": 10,
        "class": 2,
        "head_uid": "zhiwei_05",
        "subject": 1,
        "courseTeacherList": {
            "chinese": "zhiwei_04",
            "maths": "zhiwei_05",
            "english": "zhiwei_06"
        }
    }
]
</pre>

== <p style="background:#6a9ee4;padding:8px 12px;color:#ffffff;">更新班级任教信息列表</p> ==

== <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>

----

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