“纪律星接口开发文档”的版本间的差异

2021年12月20日 (一) 16:27的最后版本

前言

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

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

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

推送考勤异常记录

第三方平台生成考勤异常记录后，需要主动通知纪律星模块做扣分记录。

接口说明

请求方式：POST
请求URL: [serverBaseUrl]/good-class/api/import?platform=[platform]&timestamp=[timestamp]&sign=[sign]
URL参数说明:

POST数据结构参数:

请求样例

POST数据如下：

    [
        {
            "id": 100231,
            "grade": "高一",
            "className": "1",
            "name": "张三",
            "time": 1639016550,
            "event": “迟到”,
        },
        {
            "id": 100234,
            "grade": "高一",
            "className": "2",
            "name": "李四",
            "time": 1639016555,
            "event": "未到寝",
        },
    ]

返回样例

{
    "code": 200,
    "msg": "ok"
}

{
    "code": 403,
    "msg": "未找到高二3班王武同学"
}

查询考勤异常记录

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

接口说明

请求方式：GET
请求URL:[platformBaseUrl]/query?platform=[platform]&begintime=[begintime]&endtime=[endtime]&timestamp=[timestamp]&sign=[sign]
请求参数:

返回参数:

返回样例

{
    "code": 200,
    "msg": "ok",
    "data": [
        {
            "id": 100231,
            "grade": "高一",
            "className": "1",
            "name": "张三",
            "time": 1639016550,
            "event": “迟到”,
        },
        {
            "id": 100234,
            "grade": "高一",
            "className": "2",
            "name": "李四",
            "time": 1639016555,
            "event": "未到寝",
        },
    ]
}

签名参数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(
   'begintime' => 1639016550,
   'endtime' => 1639016555,
   'timestamp' => 1639017000
);
$sign = sign($data, $key);

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