考勤列表

  • 可以查询指定学生或班级的考勤记录,支持筛选指定日期等。
  • 单个学生可以在指定教室创建考勤记录(学生刷卡考勤)

可用 API

1、学生考勤列表

GET https://open.seiue.com/api/v1/students/:id/attendances?semester_id=1

Parameters

参数名 类型 描述
id integer 学生id
semester_id integer 学期ID,可省略,默认当前正在进行的学期

Response 200

考勤记录列表,按考勤时间倒序排列

每个考勤记录的字段有:

字段名 类型 描述
id integer 记录ID
status string 结果状态, 定义见下方
klass object 班级详情,包含 klass.name, klass.teachers[0].reflection.name, klass.classroom.name
created_date string 考勤日期 YYYY-MM-DD
created_time string 考勤时间 HH:MM
created_date_label string 中文时间描述,比如 今天,上周等,如果时间过久,可能为空字符串

考勤状态定义(对所有考勤对象通用):

  • normal 正常
  • absent 缺席
  • lated 迟到
  • early_left 早退
  • absent_from_duty 缺勤

响应示例:

[
    {
        "id": 16,
        "status": "lated",
        "status_label": "迟到",
        "checked_at": "2017-09-05",
        "lesson": 5,
        "created_date": "2017-09-05",
        "created_time": "14:07",
        "created_date_label": "昨天",
        "klass": {
            "id": 1,
            "csin": "PH101",
            "name": "语文",
            "class_name": "2班",
            "teachers": [
                {
                    "id": 123,
                    "usin": "F0001",
                    "name": "张老师",
                    "pinyin": "Zhang laoshi",
                    "avatar_url": "https://platform.seiue.com/files/someone.jpg",
                    "gender": "u",
                    "status": 1,
                    "gender_label": null,
                    "status_label": "正常",
                }
            ],
            "classroom": {
                "id": 3020,
                "name": "140"
            }
        }
    },
]

其中 klass 是班级信息,结构和课表里的班级都是一样的

  • 可以显示 klass.name + klass.class_name 作为班级名
  • klass.teachers 代表教师列表
  • klass.classroom 代表所在教室

2、班级考勤详情

查询某一节课的考勤,请务必加上date, lesson 参数

GET https://open.seiue.com/api/v1/classes/:id/attendances?semester_id=1

Parameters

参数名 类型 描述
id integer 班级ID
semester_id integer 学期ID,可省略,默认当前正在进行的学期
date string 只看指定日期的课表,格式为YYYY-MM-DD,可以是字符串now,表示今天
lesson integer 指定上课节次, 1-N

Response 200

返回的是一个对象,包含考勤数据统计,班级成员考勤列表等。

{
    "statistics": {
        "attendance_rate": 16,
        "normal": 2,
        "late": 7,
        "absent": 1
    },
    "list": [
        {
            "id": 15,
            "status": "absent_from_duty",
            "status_label": "缺席",
            "checked_at": "2016-09-08",
            "lesson": 5,
            "created_date": "2016-09-08",
            "created_time": "14:07",
            "created_date_label": null,
            "student": {
                "id": 30683,
                "usin": "20190001",
                "name": "小明",
                "pinyin": "Xiao ming",
                "avatar_url": "https://platform.seiue.com/files/someone.jpg",
                "gender": "f",
                "status": 1,
                "gender_label": "男",
                "status_label": "归档",
                "graduates_label": "2019届"
            }
        },
    ]
}

响应的字段主要有:

  • statistics - Obejct 班级某节课的考勤统计
    • attendance_rate 出勤率 0到100
    • normal 正常人数
    • late 迟到/早退人数
    • absent 缺勤人数
  • list - Array 考勤列表
    • 每个考勤对象和上面学生考勤列表一样

3. 班级批量考勤

以教学班为基础,通过指定的时间和节次进行批量考勤。

PUT https://open.seiue.com/api/v1/classes/:id/attendances?checked_at=2018-08-09&lesson=1

Parameters

参数名 类型 描述
id integer 教学班级ID
checked_at string 考勤日期,格式为YYYY-MM-DD
lesson integer 指定上课节次, 1-N

Body

[
    {
        "rid": 2, // 指定学生ID
        "result": "absent",
    },
    {
        "usin": "A123", // 指定学号
        "result": "normal",
    }
]

在 body 中传递一个或多个考勤的结果,每一条记录是一个学生的考勤结果,包含两部分信息:

  1. 唯一标志一个学生的 rid 或者 usin
  2. 考勤结果 result 字段,result 目前支持如下四种类型:normal 正常, absent 缺席, lated 迟到 和 early_left 早退

注意
因为学号存在变化的可能,如果使用学号作为标志学生的字段,需要确保使用方的学号信息与希悦保持同步。

Response 204

成功后该 API 返回 204

4. 在线实时刷卡考勤

学生在某个教室实时刷卡考勤,系统会根据教室ID找到当前上课的班级,并计入该班级的考勤,此 API 适用于实时在线刷卡考勤,API 返回的结果应该实时反馈给学生。

POST /api/v1/students/:student_id/attendances

classroom_id=112

Parameters

参数名 类型 描述 参数类型
student_id number 学生ID(reflection ID) 拼接在请求地址上
classroom_id number 教室ID(classroom ID) POST发送的参数

Response 200

返回的是考勤结果对象,包括考勤失败

字段名称 类型 描述 示例
status string 结果状态,参见下表 success
title string 错误或成功考勤的标题 考勤成功
message string 错误或成功考勤的消息,可直接显示给用户 考勤时间: 2017-01-01 12:30:40
reflection object 学生卡绑定的学生资料 参见 3. 读取卡片ID并获取学生资料
klass object 当前考勤的班级信息,考勤失败时可能为空 参见 课表管理里班级对象的描述

各个状态的含义:

  • success 考勤成功
  • exists 已有存在的考勤
  • lated 已经迟到
  • finished 停止考勤
  • invalid 考勤无效(不在当前班级等)

响应示例:

{
    "status": "invalid",
    "title": "考勤无效",
    "message": "当前没有上课中的班级",
    "reflection": {
        "id": 248672,
        "usin": "T003",
        "name": "测试3带头像",
        "pinyin": "Ce Shi3daitouxiang",
        "avatar_url": "https://platform.seiue.com/files/someone.jpg",
        "gender": "m",
        "status": 1,
        "gender_label": "男",
        "status_label": "正常",
        "graduates_label": "0届"
    }
}

5. 离线刷卡考勤记录同步

此 API 是学生刷卡考勤的批量离线版本,主要用于后台离线数据同步,可多次更新,数据以最后提交的为准。

POST /api/v1/classrooms/:id/attendance-logs

Parameters

参数名 类型 描述 参数类型
id number 教室ID 拼接在请求地址上

Body

{
    [
        rid: 1, // 指定学生 rid
        created_at: '2018-10-10 10:00:00',
    ],
    [
        usin: 'A123', // 指定学生 usin,后台自动匹配
        created_at: '2018-10-10 10:00:00',
    ],
    ...
}

在 body 中传递一个或多个刷卡记录,每一条记录包含刷卡学生(rid 或者 usin)和刷卡时间(created_at)两部分信息。

注意
因为学号存在变化的可能,如果使用学号作为标志学生的字段,需要确保使用方的学号信息与希悦保持同步。

Response 200

该 API 返回一个数组,每个元素是该刷卡记录对应的考勤结果

6. 获取考勤设置

在用 学生在教室记录考勤 接口进行打卡考勤时,系统会根据考勤设置进行自动的状态判断,该接口可获得这些配置。

GET /api/v1/classroompad/attendance-settings

Parameters

Response 200

返回结果为对象, 具体字段如下:

字段名称 类型 描述 示例
first_start_duration string 第一节课考勤提前时间 30
before_start_normal string 上课前多少分钟可以考勤 17
after_start_lated string 上课后多少分钟考勤算迟到 2
after_start_stop string 上课后多少分钟停止考勤 15

results matching ""

    No results matching ""