查看“纪律星接口开发文档”的源代码

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

本文档针对需要对接纪律星模块的平台而编写。

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

然后提供一个接口URL前缀'''[platformBaseUrl]'''，后面所有的接口都基于这个前缀。凡是接口URL是'''[serverBaseUrl]'''前缀的，说明这个接口由第三方向纪律星发起请求。而如果接口URL前缀是'''[platformBaseUrl]'''，说明接口是由纪律星向第三方发起请求。

== <p style="background:#6a9ee4;padding:8px 12px;color:#ffffff;">推送考勤异常记录</p> ==
第三方平台生成考勤异常记录后，需要主动通知纪律星模块做扣分记录。

;<span style="font-size:15px;">接口说明</span>
请求方式：<code>POST</code>  <br/>
请求URL: '''[serverBaseUrl]'''/good-class/api/import?platform='''[platform]'''&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
|-
|timestamp
|int
|是
|时间戳（Unixtime），有效时长600秒
|-
|sign
|string
|是
|签名，只对platform和timestamp签名，不用对POST数据内容签名。详见[https://chengjiyun.com/wiki/index.php?title=%E7%BA%AA%E5%BE%8B%E6%98%9F%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:40px; text-align:center;" | 参数
| style="width:150px; text-align:center;" | 类型
| style="width:200px; text-align:center;" | 描述
|-
|id
|string
|记录ID，用于确认记录是否已经导入过。
|-
|grade
|string
|年级
|-
|className
|string
|班别
|-
|name
|string
|姓名
|-
|time
|int
|记录事件发生时间戳（Unixtime），相当于打卡时间。
|-
|event
|string
|事件。例如“异常”、“晚归“、“迟到”、“未到寝“。
|}

'''请求样例'''

POST数据如下：
<pre>
    [
        {
            "id": 100231,
            "grade": "高一",
            "className": "1",
            "name": "张三",
            "time": 1639016550,
            "event": “迟到”,
        },
        {
            "id": 100234,
            "grade": "高一",
            "className": "2",
            "name": "李四",
            "time": 1639016555,
            "event": "未到寝",
        },
    ]
</pre>
<br/>


'''返回样例'''
<pre>
{
    "code": 200,
    "msg": "ok"
}
</pre>

<pre>
{
    "code": 403,
    "msg": "未找到高二3班王武同学"
}
</pre>
<br/>

== <p style="background:#6a9ee4;padding:8px 12px;color:#ffffff;">查询考勤异常记录</p> ==

此接口由纪律星向第三方发起请求，获取考勤异常记录。此接口是对推送接口的一个补充，以防因为网络原因丢失推送记录，可以通过反向查询的方式确认。

;<span style="font-size:15px;">接口说明</span>
请求方式：<code>GET</code>  <br/>
请求URL:'''[platformBaseUrl]'''/query?platform='''[platform]'''&begintime='''[begintime]'''&endtime='''[endtime]'''&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;" | 描述
|-
|platform
|string
|是
|平台ID
|-
|begintime
|int
|是
|查询开始时间（Unixtime）
|-
|endtime
|int
|是
|查询结束时间（Unixtime）
|-
|timestamp
|int
|是
|防止重放攻击的时间戳（Unixtime）
|-
|sign
|string
|是
|签名。详见[https://chengjiyun.com/wiki/index.php?title=%E7%BA%AA%E5%BE%8B%E6%98%9F%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，用于确认记录是否已经导入过。
|-
|grade
|string
|年级
|-
|className
|string
|班别
|-
|name
|string
|姓名
|-
|time
|int
|记录事件发生时间戳（Unixtime），相当于打卡时间。
|-
|event
|string
|事件。例如“异常”、“晚归“、“迟到”、“未到寝“。
|}

'''返回样例'''
<pre>
{
    "code": 200,
    "msg": "ok",
    "data": [
        {
            "id": 100231,
            "grade": "高一",
            "className": "1",
            "name": "张三",
            "time": 1639016550,
            "event": “迟到”,
        },
        {
            "id": 100234,
            "grade": "高一",
            "className": "2",
            "name": "李四",
            "time": 1639016555,
            "event": "未到寝",
        },
    ]
}
</pre>
<br/>

== <p style="background:#6a9ee4;padding:8px 12px;color:#ffffff;">签名参数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(
   'begintime' => 1639016550,
   'endtime' => 1639016555,
   'timestamp' => 1639017000
);
$sign = sign($data, $key);
</pre>

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