“成绩云接口开发文档”的版本间的差异

来自成绩云帮助中心
跳转至: 导航搜索
单点登录
 
(未显示4个用户的235个中间版本)
第5行: 第5行:
 
接入成绩云的平台需要先联系知未科技研发,获取2个基本参数:平台ID'''[platform]''',平台密钥'''[key]'''。这两个参数也可以反过来向知未科技提供。
 
接入成绩云的平台需要先联系知未科技研发,获取2个基本参数:平台ID'''[platform]''',平台密钥'''[key]'''。这两个参数也可以反过来向知未科技提供。
  
然后提供一个接口URL前缀'''[apiBaseUrl]''',后面所有的接口都基于这个前缀。
+
然后提供一个接口URL前缀'''[apiBaseUrl]''',后面所有的接口都基于这个前缀。凡是接口URL是https://chengjiyun.com前缀的,说明这个接口由第三方向成绩云发起请求。而如果接口URL前缀是'''[apiBaseUrl]''',说明接口是由成绩云向第三方发起请求。
  
 
为每一所接入学校向知未提供一个'''[orgId]'''。
 
为每一所接入学校向知未提供一个'''[orgId]'''。
第11行: 第11行:
 
== <p style="background:#6a9ee4;padding:8px 12px;color:#ffffff;">单点登录</p> ==
 
== <p style="background:#6a9ee4;padding:8px 12px;color:#ffffff;">单点登录</p> ==
 
[[文件:login.png]] <br/><br/><br/>
 
[[文件:login.png]] <br/><br/><br/>
;<p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">单点登录流程说明:</p><br/>
+
;<p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">单点登录流程说明</p><br/>
 
1. 第三方平台内添加成绩云访问单点登录链接,点击链接访问成绩云。<br/>
 
1. 第三方平台内添加成绩云访问单点登录链接,点击链接访问成绩云。<br/>
 
2. 成绩云接收来自第三方的的访问参数,查询站点信息。(成绩云是分学段建立站点的;如果一个学校包含了小学、初中、高中,那么成绩云中将分别建立小学、初中、高中三个站点。成绩云分学段建立的站点将使用第三方平台给定的学校唯一标识建立站点关联关系)。<br/>
 
2. 成绩云接收来自第三方的的访问参数,查询站点信息。(成绩云是分学段建立站点的;如果一个学校包含了小学、初中、高中,那么成绩云中将分别建立小学、初中、高中三个站点。成绩云分学段建立的站点将使用第三方平台给定的学校唯一标识建立站点关联关系)。<br/>
第17行: 第17行:
 
4. 第三方平台给定的学校包含多个学段,成绩云将会显示选择站点页面。选择站点页面将列举出访问用户可选择的站点。用户选择对应的站点后,则开始验证用户信息。<br/><br/>
 
4. 第三方平台给定的学校包含多个学段,成绩云将会显示选择站点页面。选择站点页面将列举出访问用户可选择的站点。用户选择对应的站点后,则开始验证用户信息。<br/><br/>
  
;<p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">接口说明:</p><br/>
+
;<p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">接口说明</p><br/>
 
请求方法:<code>GET</code><br/>
 
请求方法:<code>GET</code><br/>
 
接口方向:<code>第三方</code>→<code>成绩云</code><br/>
 
接口方向:<code>第三方</code>→<code>成绩云</code><br/>
请求url:[apiBaseUrl]?orgId=[学校ID]&account=[账号]&type=[角色]&timestamp=[当前时间戳]&sign=[签名]<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/>
 
访问参数:
 
访问参数:
  
第42行: 第43行:
 
|type
 
|type
 
|string
 
|string
|
+
|
|角色
+
|学段,可选值为“小学”、“初中”、“高中”。如果存在多学段且不填此字段,系统会让用户选择。
 
|-
 
|-
 
|timestamp
 
|timestamp
 
|int
 
|int
 
|是
 
|是
|时间戳time()
+
|时间戳(Unixtime),有效时长7200秒
 
|-
 
|-
 
|sign
 
|sign
 
|string
 
|string
 
|是
 
|是
|签名, 详见附录签名参数sign生成说明
+
|签名, 详见附录[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:#6a9ee4;padding:8px 12px;color:#ffffff;">查询用户</p> ==
  
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">查询所有用户列表:</p> ===
+
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">查询所有用户列表</p> ===
 +
此接口由成绩云向第三方发起请求,获取用户列表。
 +
 
 
成绩云仅需要4种用户角色:学生,教师,管理员,家长。<br/>
 
成绩云仅需要4种用户角色:学生,教师,管理员,家长。<br/>
此接口是下面其它接口的超集,后面的接口通过role参数查询子集。
+
此接口是下面其它接口的超集,后面的接口通过role参数查询子集。当指定了role参数后,返回结果中,可忽略用户的角色属性。<br/><br/>
  
;<p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">接口说明:</p>
+
;<span style="font-size:15px;">接口说明</span>
 
请求方式:<code>POST</code>  <br/>
 
请求方式:<code>POST</code>  <br/>
请求url: [apiBaseUrl]/queryUsers
+
请求URL:'''[apiBaseUrl]'''/queryUsers<br/>
 
请求参数:<br/>
 
请求参数:<br/>
 
{| class="wikitable"
 
{| class="wikitable"
第76行: 第79行:
 
|string
 
|string
 
|是
 
|是
|学校的唯一 id
+
|学校 ID
 +
|-
 +
|role
 +
|string
 +
|否
 +
|角色。可选值为“学生”、“教师”、“管理员、“家长”
 
|-
 
|-
 
|timestamp
 
|timestamp
 
|int
 
|int
 
|是
 
|是
|时间戳time()
+
|时间戳(Unixtime)
 
|-
 
|-
 
|sign
 
|sign
 
|string
 
|string
 
|是
 
|是
|签名。详见附录签名参数sign生成说明
+
|签名。详见附录[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生成说明]
 
|}
 
|}
  
第96行: 第104行:
 
| style="width:200px; text-align:center;" | 描述
 
| style="width:200px; text-align:center;" | 描述
 
|-
 
|-
|id
+
|account
 
|string
 
|string
|用户的唯一 id
+
|账号
 
|-
 
|-
 
|name
 
|name
第107行: 第115行:
 
|array
 
|array
 
|角色数组
 
|角色数组
 +
|-
 +
|studentId
 +
|string
 +
|学号。要求同一个学校内唯一
 +
|-
 +
|gender
 +
|string
 +
|性别,可选“男”、“女”或“”(空字符串)
 +
|-
 +
|grade
 +
|int
 +
|年级,7表示初一,10表示高一,以此类推。
 +
|-
 +
|class
 +
|string
 +
|班别名称
 
|}
 
|}
  
第116行: 第140行:
 
     "data": [
 
     "data": [
 
         {
 
         {
             "id": "zhiwei_01",
+
             "account": "zhiwei_01",
 +
            "studentId": "20190101",
 
             "name": "刘备",
 
             "name": "刘备",
 +
            "gender": "男",
 +
            "grade": 10,
 +
            "class": "1",
 
             "roleList": [
 
             "roleList": [
 
                 "学生"
 
                 "学生"
第123行: 第151行:
 
         },
 
         },
 
         {
 
         {
             "id": "zhiwei_06",
+
             "account": "zhiwei_06",
 
             "name": "单福",
 
             "name": "单福",
 
             "roleList": [
 
             "roleList": [
第131行: 第159行:
 
         },
 
         },
 
         {
 
         {
             "id": "parent_01",
+
             "account": "parent_01",
 
             "name": "费曼",
 
             "name": "费曼",
 
             "roleList": [
 
             "roleList": [
第142行: 第170行:
 
<br/>
 
<br/>
  
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">查询学生列表:</p> ===
+
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">查询学生列表</p> ===
 +
此接口由成绩云向第三方发起请求,获取学生用户列表。
  
;<p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">接口说明:</p>
+
;<p style="font-size:15px;">接口说明</p>
 
请求方式:<code>POST</code> <br/>
 
请求方式:<code>POST</code> <br/>
请求url:  [apiBaseUrl]/queryStudents<br/>
+
请求URL'''[apiBaseUrl]'''/queryUsers<br/>
 
请求参数:
 
请求参数:
 
{| class="wikitable"
 
{| class="wikitable"
第158行: 第187行:
 
|string
 
|string
 
|是
 
|是
|学校的唯一 id
+
|学校 ID
 +
|-
 +
|role
 +
|string
 +
|是
 +
|填“学生”
 
|-
 
|-
 
|timestamp
 
|timestamp
 
|int
 
|int
 
|是
 
|是
|时间戳time()
+
|时间戳(Unixtime)
 
|-
 
|-
 
|sign
 
|sign
 
|string
 
|string
 
|是
 
|是
|签名。详见附录签名参数sign生成说明
+
|签名。详见附录[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生成说明]
 
|}
 
|}
  
第178行: 第212行:
 
| style="width:300px; text-align:center;" | 描述
 
| style="width:300px; text-align:center;" | 描述
 
|-
 
|-
|id
+
|account
 
|string
 
|string
|学生的唯一 id
+
|账号
 
|-
 
|-
|schoolId
+
|studentId
 
|string
 
|string
 
|学号。要求同一个学校内唯一
 
|学号。要求同一个学校内唯一
第191行: 第225行:
 
|-
 
|-
 
|gender
 
|gender
|enum ("男", "女")
+
|string
|性别
+
|性别,可选“男”、“女”或“”(空字符串)
 
|-
 
|-
 
|grade
 
|grade
第199行: 第233行:
 
|-
 
|-
 
|class
 
|class
|int
+
|string
|班级。必须为纯整数,不能含有其他字符
+
|班别名称
 
|}
 
|}
  
第210行: 第244行:
 
     "data": [
 
     "data": [
 
         {
 
         {
             "id": "zhiwei_01",
+
             "account": "zhiwei_01",
             "schoolId": "20190101",
+
             "studentId": "20190101",
 
             "name": "刘备",
 
             "name": "刘备",
 
             "gender": "男",
 
             "gender": "男",
 
             "grade": 10,
 
             "grade": 10,
             "class": 1
+
             "class": "1"
 
         },
 
         },
 
         {
 
         {
             "id": "zhiwei_02",
+
             "account": "zhiwei_02",
             "schoolId": "20190102",
+
             "studentId": "20190102",
 
             "name": "关羽",
 
             "name": "关羽",
 
             "gender": "男",
 
             "gender": "男",
 
             "grade": 11,
 
             "grade": 11,
             "class": 2
+
             "class": "2"
 
         },
 
         },
 
         {
 
         {
             "id": "zhiwei_03",
+
             "account": "zhiwei_03",
             "schoolId": "20190103",
+
             "studentId": "20190103",
 
             "name": "张飞",
 
             "name": "张飞",
 
             "gender": "男",
 
             "gender": "男",
 
             "grade": 12,
 
             "grade": 12,
             "class": 3
+
             "class": "3"
 
         }
 
         }
 
     ]
 
     ]
第237行: 第271行:
 
</pre>
 
</pre>
  
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">查询管理员列表:</p> ===
+
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">查询管理员列表</p> ===
 
+
此接口由成绩云向第三方发起请求,获取管理员用户列表。
;<p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">接口说明:</p>
+
;<p style="font-size:15px;">接口说明</p>
 
请求方式:<code>POST</code>  <br/>
 
请求方式:<code>POST</code>  <br/>
请求url:  [apiBaseUrl]/queryAdmins <br/>
+
请求url:  '''[apiBaseUrl]'''/queryUsers<br/>
 
请求参数:
 
请求参数:
 
{| class="wikitable"
 
{| class="wikitable"
第253行: 第287行:
 
|string
 
|string
 
|是
 
|是
|学校的唯一 id
+
|学校 ID
 +
|-
 +
|role
 +
|string
 +
|是
 +
|填“管理员”
 
|-
 
|-
 
|timestamp
 
|timestamp
 
|int
 
|int
 
|是
 
|是
|时间戳time()
+
|时间戳(Unixtime)
 
|-
 
|-
 
|sign
 
|sign
 
|string
 
|string
 
|是
 
|是
|签名。详见附录签名参数sign生成说明
+
|签名。详见附录[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生成说明]
 
|}
 
|}
  
第273行: 第312行:
 
| style="width:150px; text-align:center;" | 描述
 
| style="width:150px; text-align:center;" | 描述
 
|-
 
|-
|id
+
|account
 
|string
 
|string
|管理员的唯一 id
+
|账号
 
|-
 
|-
 
|name
 
|name
第289行: 第328行:
 
     "data": [
 
     "data": [
 
         {
 
         {
             "id": "zhiwei_07",
+
             "account": "zhiwei_07",
 
             "name": "陈大文"
 
             "name": "陈大文"
 
         },
 
         },
 
         {
 
         {
             "id": "zhiwei_08",
+
             "account": "zhiwei_08",
 
             "name": "张伟"
 
             "name": "张伟"
 
         },
 
         },
 
         {
 
         {
             "id": "zhiwei_09",
+
             "account": "zhiwei_09",
 
             "name": "杨红"
 
             "name": "杨红"
 
         }
 
         }
第305行: 第344行:
 
<br/>
 
<br/>
  
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">查询教师列表:</p> ===
+
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">查询教师列表</p> ===
 
+
此接口由成绩云向第三方发起请求,获取教师用户列表。
;<p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">接口说明:</p>
+
;<p style="font-size:15px;">接口说明</p>
 
请求方式:<code>POST</code>  <br/>
 
请求方式:<code>POST</code>  <br/>
请求url: [apiBaseUrl]/queryTeachers <br/>
+
请求url: '''[apiBaseUrl]'''/queryUsers<br/>
 
请求参数:
 
请求参数:
 
{| class="wikitable"
 
{| class="wikitable"
第321行: 第360行:
 
|string
 
|string
 
|是
 
|是
|学校的唯一 id
+
|学校 ID
 +
|-
 +
|role
 +
|string
 +
|是
 +
|填“教师”
 
|-
 
|-
 
|timestamp
 
|timestamp
 
|int
 
|int
 
|是
 
|是
|时间戳time()
+
|时间戳(Unixtime)
 
|-
 
|-
 
|sign
 
|sign
 
|string
 
|string
 
|是
 
|是
|签名。详见附录签名参数sign生成说明
+
|签名。详见附录[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生成说明]
 
|}
 
|}
  
第341行: 第385行:
 
| style="width:150px; text-align:center;" | 描述
 
| style="width:150px; text-align:center;" | 描述
 
|-
 
|-
|id
+
|account
 
|string
 
|string
|教师的唯一 id
+
|教师的账户
 
|-
 
|-
 
|name
 
|name
第358行: 第402行:
 
     "data": [
 
     "data": [
 
         {
 
         {
             "id": "zhiwei_04",
+
             "account": "zhiwei_04",
 
             "name": "孔明"
 
             "name": "孔明"
 
         },
 
         },
 
         {
 
         {
             "id": "zhiwei_05",
+
             "account": "zhiwei_05",
 
             "name": "郭嘉"
 
             "name": "郭嘉"
 
         },
 
         },
 
         {
 
         {
             "id": "zhiwei_06",
+
             "account": "zhiwei_06",
 
             "name": "单福"
 
             "name": "单福"
 
         }
 
         }
第373行: 第417行:
 
</pre>
 
</pre>
  
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">查询家长列表:</p> ===
+
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">查询家长列表</p> ===
 
+
此接口由成绩云向第三方发起请求,获取家长用户列表。
;<p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">接口说明:</p>
+
;<p style="font-size:15px;">接口说明</p>
 
请求方式:<code>POST</code> <br/>
 
请求方式:<code>POST</code> <br/>
请求url:  [apiBaseUrl]/queryParents <br/>
+
请求url:  '''[apiBaseUrl]'''/queryUsers<br/>
 
请求参数:
 
请求参数:
 
{| class="wikitable"
 
{| class="wikitable"
第389行: 第433行:
 
|string
 
|string
 
|是
 
|是
|学校的唯一 id
+
|学校 ID
 +
|-
 +
|role
 +
|string
 +
|是
 +
|填“家长”
 
|-
 
|-
 
|timestamp
 
|timestamp
 
|int
 
|int
 
|是
 
|是
|时间戳time()
+
|时间戳(Unixtime)
 
|-
 
|-
 
|sign
 
|sign
 
|string
 
|string
 
|是
 
|是
|签名。详见附录签名参数sign生成说明
+
|签名。详见附录[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生成说明]
 
|}
 
|}
  
第409行: 第458行:
 
| style="width:180px; text-align:center;" | 描述
 
| style="width:180px; text-align:center;" | 描述
 
|-
 
|-
|id
+
|account
 
|string
 
|string
|家长的唯一 id
+
|账号
 
|-
 
|-
 
|name
 
|name
第419行: 第468行:
 
|studentList
 
|studentList
 
|array
 
|array
|家长关联的学生 id数组
+
|家长关联的学生 ID数组
 
|}
 
|}
  
第430行: 第479行:
 
     "data": [
 
     "data": [
 
         {
 
         {
             "id": "parent_01",
+
             "account": "parent_01",
 
             "name": "费曼",
 
             "name": "费曼",
 
             "studentList": [
 
             "studentList": [
第437行: 第486行:
 
         },
 
         },
 
         {
 
         {
             "id": "parent_02",
+
             "account": "parent_02",
 
             "name": "图灵",
 
             "name": "图灵",
 
             "studentList": [
 
             "studentList": [
第445行: 第494行:
 
         },
 
         },
 
         {
 
         {
             "id": "parent_03",
+
             "account": "parent_03",
 
             "name": "香侬",
 
             "name": "香侬",
 
             "studentList": [
 
             "studentList": [
第457行: 第506行:
 
</pre>
 
</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;">新增用户</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
 +
|是
 +
|姓名
 +
|-
 +
|studentId
 +
|string
 +
|否
 +
|学号。要求同一个学校内唯一
 +
|-
 +
|gender
 +
|string
 +
|否
 +
|性别,可选“男”、“女”或“”(空字符串)
 +
|-
 +
|grade
 +
|int
 +
|否
 +
|年级,7表示初一,10表示高一,以此类推。
 +
|-
 +
|class
 +
|string
 +
|否
 +
|班别名称
 +
|}
 +
 
 +
'''请求样例'''
 +
 
 +
POST数据如下:
 +
<pre>
 +
    [
 +
        {
 +
            "account": "zhiwei_01",
 +
            "name": "刘备",
 +
            "class": "2",
 +
            "roleList": [
 +
                "管理员",
 +
                "教师",
 +
            ]
 +
        },
 +
        {
 +
            "account": "zhiwei_06",
 +
            "name": "单福",
 +
            "gender": "男",
 +
            "roleList": [
 +
                "教师",
 +
            ]
 +
        },
 +
        {
 +
            "account": "student_01",
 +
            "name": "费曼",
 +
            "grade": 7,
 +
            "class": "1",
 +
            "roleList": [
 +
                "教师",
 +
            ]
 +
        }
 +
    ]
 +
</pre>
 +
<br/>
 +
 
 +
 
 +
'''返回样例'''
 +
<pre>
 +
{
 +
    "code": 0,
 +
    "msg": "成功",
 +
}
 +
</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": "成功",
 +
}
 +
</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
 +
|否
 +
|姓名
 +
|-
 +
|studentId
 +
|string
 +
|否
 +
|学号。要求同一个学校内唯一
 +
|-
 +
|gender
 +
|string
 +
|否
 +
|性别,可选“男”、“女”或“”(空字符串)
 +
|-
 +
|grade
 +
|int
 +
|否
 +
|年级,7表示初一,10表示高一,以此类推。
 +
|-
 +
|class
 +
|string
 +
|否
 +
|班别名称
 +
|-
 +
|status
 +
|int
 +
|否
 +
|账号状态。可不携带该属性,代表不更新用户状态;若携带该属性,0代表禁用状态,1代表活跃状态。
 +
|-
 +
|}
 +
 
 +
'''请求样例'''
 +
 
 +
POST数据如下:
 +
<pre>
 +
    [
 +
        {
 +
            "account": "zhiwei_01",
 +
            "name": "刘备",
 +
            "class": "2",
 +
            "status": 1
 +
        },
 +
        {
 +
            "account": "zhiwei_06",
 +
            "name": "单福",
 +
            "gender": "男",
 +
            "status": 0
 +
        },
 +
        {
 +
            "account": "parent_01",
 +
            "name": "费曼"
 +
        },
 +
    ]
 +
</pre>
 +
<br/>
 +
 
 +
 
 +
'''返回样例'''
 +
<pre>
 +
{
 +
    "code": 0,
 +
    "msg": "成功",
 +
}
 +
</pre>
 +
<br/>
  
 
== <p style="background:#6a9ee4;padding:8px 12px;color:#ffffff;">查询班级任教信息列表</p> ==
 
== <p style="background:#6a9ee4;padding:8px 12px;color:#ffffff;">查询班级任教信息列表</p> ==
 +
成绩云向第三方平台发起请求,查询班级任教信息。
 +
<p style="font-size:15px;">'''接口说明'''</p>
 +
请求方式:<code>POST</code> <br/>
 +
请求url:  '''[apiBaseUrl]'''/queryClassStatus<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生成说明]
 +
|}
  
== <p style="background:#6a9ee4;padding:8px 12px;color:#ffffff;">更新班级任教信息列表</p> ==
+
'''返回参数''':<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
 +
|string
 +
|班别名称
 +
|-
 +
|headTeacher
 +
|string
 +
|班主任的账户 ID
 +
|-
 +
|courseTeacherList
 +
|object
 +
|科目任教信息. 以科目的中文名为属性名, 教师的账户 ID 为 属性值的结构对象
 +
例如:
 +
<pre>
 +
{
 +
"语文":"zhiwei_04",
 +
"数学":"zhiwei_05",
 +
"英语":"zhiwei_06"
 +
}
 +
</pre>
 +
|}
 +
 
 +
'''返回样例'''
 +
<pre>
 +
{
 +
    "code": 0,
 +
    "msg": "成功",
 +
    "data": [
 +
        {
 +
            "year": 2018,
 +
            "grade": 10,
 +
            "class": "1",
 +
            "headTeacher": "zhiwei_04",
 +
            "courseTeacherList": {
 +
                "语文": "zhiwei_04",
 +
                "数学": "zhiwei_05",
 +
                "英语": "zhiwei_06"
 +
            }
 +
        },
 +
        {
 +
            "year": 2018,
 +
            "grade": 10,
 +
            "class": "2",
 +
            "headTeacher": "zhiwei_05",
 +
            "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/updateClassStatus?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生成说明]
 +
|}
 +
 
 +
== <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</code>  <br/>
 +
请求URL:  '''[apiBaseUrl]'''/queryExam<br/>
 +
返回格式:<code>Content-Type:application/json</code><br/>
 +
请求参数:<br/>
 +
{| class="wikitable"
 +
|-
 +
| style="text-align:center;" | 参数
 +
| style="text-align:center;" | 类型
 +
| style="text-align:center;" | 是否必填
 +
| style="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;" | 是否必填
 +
| 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)
 +
|}
 +
 
 +
 
 +
'''返回样例'''
 +
<pre>
 +
{
 +
    "code": 0,
 +
    "msg": "成功",
 +
    "data": [
 +
        {
 +
            "examId": "233",
 +
            "title": "考试标题",
 +
            "grade": 11 // 年级值11表示高二
 +
        },
 +
        {
 +
            "examId": "234",
 +
            "title": "考试标题",
 +
            "grade": 12 // 年级值12表示高三
 +
        }
 +
    ]
 +
}
 +
</pre>
 +
 
 +
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">查询单次考试总分成绩</p> ===
 +
成绩云向第三方平台发起请求,获取单次考试详细成绩数据。
 +
;<span style="font-size:15px;">接口说明</span>
 +
请求方式:<code>POST</code>  <br/>
 +
请求url:  '''[apiBaseUrl]'''/queryExamDetail<br/>
 +
返回格式:<code>Content-Type:application/json</code><br/>
 +
请求参数:<br/>
 +
{| class="wikitable"
 +
|-
 +
| style="text-align:center;" | 参数
 +
| style="text-align:center;" | 类型
 +
| style="text-align:center;" | 是否必填
 +
| style="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;" | 描述
 +
|-
 +
|studentId
 +
|string
 +
|学生学号
 +
|-
 +
|scores
 +
|array
 +
|科目成绩
 +
|}
 +
 
 +
 
 +
'''返回样例'''
 +
<pre>
 +
{
 +
    "code": 0,
 +
    "msg": "成功",
 +
    "data": [
 +
        {
 +
            "studentId": "20180101",
 +
            "scores": {
 +
                "语文": 120,
 +
                "数学": 118,
 +
                "英语": 121,
 +
                "物理": 89,
 +
                "化学": 78,
 +
                "生物": 88,
 +
                "政治": 78,
 +
                "历史": 85,
 +
                "地理": 83
 +
            }
 +
        },
 +
        {
 +
            "studentId": "20180102",
 +
            "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>POST</code>  <br/>
 +
请求url:  '''[apiBaseUrl]'''/queryQuestionList<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": "成功",
 +
    "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>POST</code> <br/>
 +
请求url:  '''[apiBaseUrl]'''/queryQuestionStructure<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
 +
|否
 +
|题号
 +
|-
 +
|answerType
 +
|enum("主观题","客观题")
 +
|否
 +
|类型
 +
|-
 +
|score
 +
|float
 +
|否
 +
|满分值
 +
|-
 +
|scroll
 +
|enum("一卷","二卷")
 +
|否
 +
|卷别
 +
|-
 +
|group
 +
|string
 +
|是
 +
| 选做题分组
 +
|-
 +
|questionType
 +
|string
 +
|是
 +
|题型
 +
|-
 +
|knowledge
 +
|string
 +
|是
 +
|知识点
 +
|-
 +
|ability
 +
|string
 +
|是
 +
|能力
 +
|}
 +
 
 +
'''返回样例'''
 +
<pre>
 +
{
 +
    "code": 0,
 +
    "msg": "成功",
 +
    "data": [
 +
        {
 +
            "number": "1",
 +
            "answerType": "客观题",
 +
            "score": 5,
 +
            "scroll": "一卷",
 +
            "group": "A1",
 +
            "questionType": "基础选择",
 +
            "knowledge": "语文基础知识",
 +
            "ability": "掌握"
 +
        },
 +
        {
 +
            "number": "2",
 +
            "answerType": "主观题",
 +
            "score": 10,
 +
            "scroll": "二卷",
 +
            "group": null,
 +
            "questionType": "现代文阅读",
 +
            "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>POST</code> <br/>
 +
请求url:  '''[apiBaseUrl]'''/queryQuestionScore<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;" | 描述
 +
|-
 +
|studentId
 +
|string
 +
|否
 +
|学生学号
 +
|-
 +
|scores
 +
|hash
 +
|是
 +
|题号: 分数。分数为 null 时, 表示学生缺答
 +
|}
 +
 
 +
'''返回样例'''
 +
<pre>
 +
{
 +
    "code": 0,
 +
    "msg": "成功",
 +
    "data": [
 +
        {
 +
            "studentId": "20210101",
 +
            "scores": {
 +
                "1": 5,
 +
                "2": 8,
 +
                "3.a": 4.5,
 +
                "3.b": 3
 +
            }
 +
        },
 +
        {
 +
            "studentId": "20210102",
 +
            "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> ==
第467行: 第1,395行:
 
== <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> ===
+
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">签名参数sign生成说明</p> ===
 
<code>第一步:</code>对传入的参数按照键名排序<br/>
 
<code>第一步:</code>对传入的参数按照键名排序<br/>
 
<code>第二步:</code>使用URL键值对的格式(即key1=value1&key2=value2…)拼接成字符串stringA <br/>
 
<code>第二步:</code>使用URL键值对的格式(即key1=value1&key2=value2…)拼接成字符串stringA <br/>
第483行: 第1,411行:
  
 
$data = array(
 
$data = array(
   'orgId'=> 2345,
+
   'orgId'=>'testapi',
   'account'=> 4567,
+
   'account'=> 'zhiwei_01',
   'type'=> 1,
+
   'type'=> '高中',
 
   'timestamp'  => time(),
 
   'timestamp'  => time(),
 
);
 
);
 
$sign = sign($data, $key);
 
$sign = sign($data, $key);
 
</pre>
 
</pre>
 +
 +
注意:一般接口会有一个timestamp参数,如无特别说明,timestamp的有效时间为600秒(登录接口有效时常为7200秒),超过该时长请求无效,以降低受到重放攻击的风险。此时长在实际使用中可能会做出调整,请尽可能地使用实时时间。
  
 
----
 
----
  
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">返回结果:</p> ===
+
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">返回结果</p> ===
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
第516行: 第1,446行:
 
<pre>
 
<pre>
 
{
 
{
     "code": "10000",
+
     "code": 0,
 
     "msg": "成功",
 
     "msg": "成功",
 
     "data": [
 
     "data": [
 
         {
 
         {
 
             "userName": "成绩云",
 
             "userName": "成绩云",
             "schoolId": 101,
+
             "studentId": 101,
 
         }
 
         }
 
     ]
 
     ]
第529行: 第1,459行:
 
----
 
----
  
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">公共返回码:</p>  ===
+
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">公共返回码</p>  ===
 
开发者每次调用接口时,可能获得正确或错误的返回码,开发者可以根据返回码信息调试接口,排查错误。
 
开发者每次调用接口时,可能获得正确或错误的返回码,开发者可以根据返回码信息调试接口,排查错误。
 
返回码如下:
 
返回码如下:

2022年6月27日 (一) 10:00的最后版本

前言

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

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

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

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

单点登录

Login.png


单点登录流程说明


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

接口说明


请求方法:GET
接口方向:第三方成绩云
PC版登录URL:https://chengjiyun.com/portal/[platform]?orgId=[orgId]&account=[account]&timestamp=[timestamp]&sign=[sign]
移动版登录URL:https://chengjiyun.com/mobile-portal/[platform]?orgId=[orgId]&account=[account]&timestamp=[timestamp]&sign=[sign]
访问参数:

参数 类型 是否必填 描述
orgId string 学校ID
account string 账号
type string 学段,可选值为“小学”、“初中”、“高中”。如果存在多学段且不填此字段,系统会让用户选择。
timestamp int 时间戳(Unixtime),有效时长7200秒
sign string 签名, 详见附录签名参数sign生成说明

查询用户

查询所有用户列表

此接口由成绩云向第三方发起请求,获取用户列表。

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

接口说明

请求方式:POST
请求URL:[apiBaseUrl]/queryUsers
请求参数:

参数 类型 是否必填 描述
orgId string 学校 ID
role string 角色。可选值为“学生”、“教师”、“管理员、“家长”
timestamp int 时间戳(Unixtime)
sign string 签名。详见附录签名参数sign生成说明

返回参数:

参数 类型 描述
account string 账号
name string 姓名
roleList array 角色数组
studentId string 学号。要求同一个学校内唯一
gender string 性别,可选“男”、“女”或“”(空字符串)
grade int 年级,7表示初一,10表示高一,以此类推。
class string 班别名称

返回样例

{
    "code": 0,
    "msg": "成功",
    "data": [
        {
            "account": "zhiwei_01",
            "studentId": "20190101",
            "name": "刘备",
            "gender": "男",
            "grade": 10,
            "class": "1",
            "roleList": [
                "学生"
            ]
        },
        {
            "account": "zhiwei_06",
            "name": "单福",
            "roleList": [
                "管理员",
                "教师"
            ]
        },
        {
            "account": "parent_01",
            "name": "费曼",
            "roleList": [
                "家长"
            ]
        },
    ]
}


查询学生列表

此接口由成绩云向第三方发起请求,获取学生用户列表。

接口说明

请求方式:POST
请求URL: [apiBaseUrl]/queryUsers
请求参数:

参数 类型 是否必填 描述
orgId string 学校 ID
role string 填“学生”
timestamp int 时间戳(Unixtime)
sign string 签名。详见附录签名参数sign生成说明

返回参数:

参数 类型 描述
account string 账号
studentId string 学号。要求同一个学校内唯一
name string 姓名
gender string 性别,可选“男”、“女”或“”(空字符串)
grade int 年级
class string 班别名称

返回样例

{
    "code": 0,
    "msg": "成功",
    "data": [
        {
            "account": "zhiwei_01",
            "studentId": "20190101",
            "name": "刘备",
            "gender": "男",
            "grade": 10,
            "class": "1"
        },
        {
            "account": "zhiwei_02",
            "studentId": "20190102",
            "name": "关羽",
            "gender": "男",
            "grade": 11,
            "class": "2"
        },
        {
            "account": "zhiwei_03",
            "studentId": "20190103",
            "name": "张飞",
            "gender": "男",
            "grade": 12,
            "class": "3"
        }
    ]
}

查询管理员列表

此接口由成绩云向第三方发起请求,获取管理员用户列表。

接口说明

请求方式:POST
请求url: [apiBaseUrl]/queryUsers
请求参数:

参数 类型 是否必填 描述
orgId string 学校 ID
role string 填“管理员”
timestamp int 时间戳(Unixtime)
sign string 签名。详见附录签名参数sign生成说明

返回参数:

参数 类型 描述
account string 账号
name string 姓名

返回样例

{
    "code": 0,
    "msg": "成功",
    "data": [
        {
            "account": "zhiwei_07",
            "name": "陈大文"
        },
        {
            "account": "zhiwei_08",
            "name": "张伟"
        },
        {
            "account": "zhiwei_09",
            "name": "杨红"
        }
    ]
}


查询教师列表

此接口由成绩云向第三方发起请求,获取教师用户列表。

接口说明

请求方式:POST
请求url: [apiBaseUrl]/queryUsers
请求参数:

参数 类型 是否必填 描述
orgId string 学校 ID
role string 填“教师”
timestamp int 时间戳(Unixtime)
sign string 签名。详见附录签名参数sign生成说明

返回参数:

参数 类型 描述
account string 教师的账户
name string 姓名


返回样例

{
    "code": 0,
    "msg": "成功",
    "data": [
        {
            "account": "zhiwei_04",
            "name": "孔明"
        },
        {
            "account": "zhiwei_05",
            "name": "郭嘉"
        },
        {
            "account": "zhiwei_06",
            "name": "单福"
        }
    ]
}

查询家长列表

此接口由成绩云向第三方发起请求,获取家长用户列表。

接口说明

请求方式:POST
请求url: [apiBaseUrl]/queryUsers
请求参数:

参数 类型 是否必填 描述
orgId string 学校 ID
role string 填“家长”
timestamp int 时间戳(Unixtime)
sign string 签名。详见附录签名参数sign生成说明

返回参数:

参数 类型 描述
account string 账号
name string 姓名
studentList array 家长关联的学生 ID数组


返回样例

{
    "code": 0,
    "msg": "成功",
    "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"
            ]
        }
    ]
}

管理用户

新增用户

第三方平台新增用户信息后,主动推送新增的用户到成绩云,通知成绩云新增相应用户。

接口说明

请求方式:POST(Content-Type:application/json)
接口方向:第三方成绩云
请求url: https://chengjiyun.com/vendor-api/addUser?platform=[platform]&orgId=[orgId]&timestamp=[timestamp]&sign=[sign]
URL参数说明(并非所有角色都支持全部参数):

参数 类型 是否必填 描述
platform string 平台ID
orgId string 学校ID
timestamp int 时间戳(Unixtime),有效时长600秒
sign string 签名,只对orgId和timestamp签名,不用对POST数据内容签名。详见附录签名参数sign生成说明

POST数据结构参数:

参数 类型 是否必填 描述
account string 账号
roleList array 角色(支持管理员、教师、学生)
name string 姓名
studentId string 学号。要求同一个学校内唯一
gender string 性别,可选“男”、“女”或“”(空字符串)
grade int 年级,7表示初一,10表示高一,以此类推。
class string 班别名称

请求样例

POST数据如下:

    [
        {
            "account": "zhiwei_01",
            "name": "刘备",
            "class": "2",
            "roleList": [
                 "管理员",
                 "教师",
            ]
        },
        {
            "account": "zhiwei_06",
            "name": "单福",
            "gender": "男",
            "roleList": [
                 "教师",
            ]
        },
        {
            "account": "student_01",
            "name": "费曼",
            "grade": 7,
            "class": "1",
            "roleList": [
                 "教师",
            ]
        }
    ]



返回样例

{
    "code": 0,
    "msg": "成功",
}


删除用户

第三方平台删除用户信息后,主动推送删除的用户到成绩云,通知成绩云进行删除。

接口说明

请求方式:POST(Content-Type:application/json)
接口方向:第三方成绩云
请求url: https://chengjiyun.com/vendor-api/deleteUser?platform=[platform]&orgId=[orgId]&timestamp=[timestamp]&sign=[sign]
URL参数说明:

参数 类型 是否必填 描述
platform string 平台ID
orgId string 学校ID
timestamp int 时间戳(Unixtime),有效时长600秒
sign string 签名,只对orgId和timestamp签名,不用对POST数据内容签名。详见附录签名参数sign生成说明

POST数据结构参数:

参数 类型 是否必填 描述
account string 账号

请求样例

POST数据如下:

   [
      "zhiwei_01",
      "zhiwei_06",
      "parent_01"
   ]



返回样例

{
    "code": 0,
    "msg": "成功",
}


更新用户

第三方平台修改用户信息后,主动推送被修改用户到成绩云进行修改。

接口说明

请求方式:POST(Content-Type:application/json)
接口方向:第三方成绩云
请求url: https://chengjiyun.com/vendor-api/updateUser?platform=[platform]&orgId=[orgId]&timestamp=[timestamp]&sign=[sign]
URL参数说明:

参数 类型 是否必填 描述
platform string 平台ID
orgId string 学校ID
timestamp int 时间戳(Unixtime),有效时长600秒
sign string 签名,只对orgId和timestamp签名,不用对POST数据内容签名。详见附录签名参数sign生成说明

POST数据结构参数(并非所有角色都支持全部参数的修改,例如班别信息对家长角色是无效的):

参数 类型 是否必填 描述
account string 账号
name string 姓名
studentId string 学号。要求同一个学校内唯一
gender string 性别,可选“男”、“女”或“”(空字符串)
grade int 年级,7表示初一,10表示高一,以此类推。
class string 班别名称
status int 账号状态。可不携带该属性,代表不更新用户状态;若携带该属性,0代表禁用状态,1代表活跃状态。

请求样例

POST数据如下:

    [
        {
            "account": "zhiwei_01",
            "name": "刘备",
            "class": "2",
            "status": 1
        },
        {
            "account": "zhiwei_06",
            "name": "单福",
            "gender": "男",
            "status": 0
        },
        {
            "account": "parent_01",
            "name": "费曼"
        },
    ]



返回样例

{
    "code": 0,
    "msg": "成功",
}


查询班级任教信息列表

成绩云向第三方平台发起请求,查询班级任教信息。

接口说明

请求方式:POST
请求url: [apiBaseUrl]/queryClassStatus
请求参数

参数 类型 是否必填 描述
orgId string 学校 ID
timestamp int 时间戳(Unixtime)
sign string 签名。详见附录签名参数sign生成说明

返回参数:

参数 类型 描述
year int 入学年份
grade int 年级
class string 班别名称
headTeacher string 班主任的账户 ID
courseTeacherList object 科目任教信息. 以科目的中文名为属性名, 教师的账户 ID 为 属性值的结构对象

例如:

{
 "语文":"zhiwei_04", 
 "数学":"zhiwei_05",
 "英语":"zhiwei_06"
}

返回样例

{
    "code": 0,
    "msg": "成功",
    "data": [
        {
            "year": 2018,
            "grade": 10,
            "class": "1",
            "headTeacher": "zhiwei_04",
            "courseTeacherList": {
                "语文": "zhiwei_04",
                "数学": "zhiwei_05",
                "英语": "zhiwei_06"
            }
        },
        {
            "year": 2018,
            "grade": 10,
            "class": "2",
            "headTeacher": "zhiwei_05",
            "courseTeacherList": {
                "语文": "zhiwei_04",
                "数学": "zhiwei_05",
                "英语": "zhiwei_06"
            }
        }
    ]
}

通知更新班级任教信息列表

第三方平台修改班级任教相关的数据后,需要主动通知成绩云重新读取第三方平台的数据更新。此接口无需传入更新的数据,只需通知成绩云即可。

接口说明

请求方式:GET
接口方向:第三方成绩云
请求URL: https://chengjiyun.com/vendor-api/updateClassStatus?platform=[platform]&orgId=[orgId]&timestamp=[timestamp]&sign=[sign]
URL参数说明:

参数 类型 是否必填 描述
platform string 平台ID
orgId string 学校ID
timestamp int 时间戳(Unixtime),有效时长600秒
sign string 签名,只对orgId和timestamp签名,不用对POST数据内容签名。详见附录签名参数sign生成说明

查询考试成绩

查询考试列表

成绩云向第三方平台发起请求,获取考试列表。

接口说明

请求方式:POST
请求URL: [apiBaseUrl]/queryExam
返回格式:Content-Type:application/json
请求参数:

参数 类型 是否必填 描述
orgId string 学校ID
timestamp int 时间戳(Unixtime),有效时长600秒
sign string 签名。详见附录签名参数sign生成说明

返回参数:

参数 类型 是否必填 描述
examId string 考试ID
title string 考试标题
grade int 年级(可取值1,2,3,4,5,6,7,8,9,10,11,12)


返回样例

{
    "code": 0,
    "msg": "成功",
    "data": [
        {
            "examId": "233",
            "title": "考试标题",
            "grade": 11 // 年级值11表示高二
        },
        {
            "examId": "234",
            "title": "考试标题",
            "grade": 12 // 年级值12表示高三
        }
    ]
}

查询单次考试总分成绩

成绩云向第三方平台发起请求,获取单次考试详细成绩数据。

接口说明

请求方式:POST
请求url: [apiBaseUrl]/queryExamDetail
返回格式:Content-Type:application/json
请求参数:

参数 类型 是否必填 描述
orgId string 学校ID
examId string 考试ID
timestamp int 时间戳(Unixtime),有效时长600秒
sign string 签名。详见附录签名参数sign生成说明

返回参数:

参数 类型 描述
studentId string 学生学号
scores array 科目成绩


返回样例

{
    "code": 0,
    "msg": "成功",
    "data": [
        {
            "studentId": "20180101",
            "scores": {
                "语文": 120,
                "数学": 118,
                "英语": 121,
                "物理": 89,
                "化学": 78,
                "生物": 88,
                "政治": 78,
                "历史": 85,
                "地理": 83
            }
        },
        {
            "studentId": "20180102",
            "scores": {
                "语文": 118,
                "数学": 136,
                "英语": 98
            }
        }
    ]
}

查询单次考试小题分科目列表

成绩云向第三方平台发起请求,获取考试小题分列表。

接口说明

请求方式:POST
请求url: [apiBaseUrl]/queryQuestionList
返回格式:Content-Type:application/json
请求参数:

参数 类型 是否必填 描述
orgId string 学校ID
examId string 考试ID
timestamp int 时间戳(Unixtime),有效时长600秒
sign string 签名。详见附录签名参数sign生成说明

返回参数:

参数 类型 是否允许为 null 描述
examId string 考试ID
courses array 有分析小题分的科目集合


返回样例

{
    "code": 0,
    "msg": "成功",
    "data": 
        {
            "examId": "233",
            "courses": [
               "语文",
               "数学",
            ],
        }
}

查询单次考试小题分试卷结构

成绩云向第三方平台发起请求,获取单次考试某一科目小题分试卷结构。

接口说明

请求方式:POST
请求url: [apiBaseUrl]/queryQuestionStructure
请求参数

参数 类型 是否必填 描述
orgId string 学校 ID
examId string 考试 ID
course string 科目的中文名
timestamp int 时间戳(Unixtime)
sign string 签名。详见附录签名参数sign生成说明

返回参数:
下面参数的具体定义,请阅读理解 试卷结构

参数 类型 是否允许为 null 描述
number string 题号
answerType enum("主观题","客观题") 类型
score float 满分值
scroll enum("一卷","二卷") 卷别
group string 选做题分组
questionType string 题型
knowledge string 知识点
ability string 能力

返回样例

{
    "code": 0,
    "msg": "成功",
    "data": [
        {
            "number": "1",
            "answerType": "客观题",
            "score": 5,
            "scroll": "一卷",
            "group": "A1",
            "questionType": "基础选择",
            "knowledge": "语文基础知识",
            "ability": "掌握"
        },
        {
            "number": "2",
            "answerType": "主观题",
            "score": 10,
            "scroll": "二卷",
            "group": null,
            "questionType": "现代文阅读",
            "knowledge": null,
            "ability": null
        }
    ]
}

查询单次考试小题分成绩

成绩云向第三方平台发起请求,获取单次考试某一科目小题分所有学生分数。

接口说明

请求方式:POST
请求url: [apiBaseUrl]/queryQuestionScore
请求参数

参数 类型 是否必填 描述
orgId string 学校 ID
examId string 考试 ID
course string 科目的中文名
timestamp int 时间戳(Unixtime)
sign string 签名。详见附录签名参数sign生成说明

返回参数:
下面参数的具体定义,请阅读理解 试卷结构

参数 类型 是否允许为 null 描述
studentId string 学生学号
scores hash 题号: 分数。分数为 null 时, 表示学生缺答

返回样例

{
    "code": 0,
    "msg": "成功",
    "data": [
        {
            "studentId": "20210101",
            "scores": {
                "1": 5,
                "2": 8,
                "3.a": 4.5,
                "3.b": 3
            }
        },
        {
            "studentId": "20210102",
            "scores": {
                "1": 5,
                "2": 2,
                "3.a": null,
                "3.b": 4
            }
        }
    ]
}


常见问题

附录

签名参数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'=>'testapi',
   'account'=> 'zhiwei_01',
   'type'=> '高中',
   'timestamp'  => time(),
);
$sign = sign($data, $key);

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


返回结果

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

返回示例:

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

公共返回码

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

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