飞书开放平台 Server API 文档

主题

创建班次 ​

该接口用于创建企业的考勤班次。

Tip: - 创建一个考勤组前，必须先创建一个或者多个班次。

  • 一个公司内的班次是共享的，你可以直接引用他人创建的班次，但是需要注意的是，若他人修改了班次，会影响到你的考勤组及其考勤结果。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/attendance/v1/shifts
HTTP MethodPOST
接口频率限制50 次/秒
支持的应用类型custom
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用attendance:rule 写入打卡管理规则

请求头 ​

名称类型必填描述
Authorizationstring是tenant_access_token 值格式："Bearer access_token" 示例值："Bearer t-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token
Content-Typestring是固定值："application/json; charset=utf-8"

查询参数 ​

名称类型必填描述
employee_typestring否请求体中的 user_ids 和响应体中的 user_id 的员工ID类型。如果没有后台管理权限，可使用通过手机号或邮箱获取用户 ID
示例值：employee_id
可选值有：
- employee_id: 员工 employee ID，即飞书管理后台 > 组织架构 > 成员与部门 > 成员详情中的用户 ID，或者通过手机号或邮箱获取用户 ID获取的user_id。 - employee_no: 员工工号，即飞书管理后台 > 组织架构 > 成员与部门 > 成员详情中的工号

请求体 ​

名称类型必填描述
shift_namestring是班次名称，不可重复
示例值："早班"
punch_timesint是打卡次数（历史字段，已无用，以punch_time_rule为准）
示例值：1
sub_shift_leader_idsstring\[\]否班次负责人，与employee_type类型对应
示例值：["456123"]
is_flexibleboolean否是否弹性打卡。true 为开启，false 为不开启。默认为 false。
示例值：false
flexible_minutesint否弹性打卡时间，单位为分钟。设置“上班最多可晚到”与“下班最多可早走”的时间。仅当 flexible_rule 参数未设置时，该参数生效。
示例值：60
flexible_ruleflexible_rule\[\]否弹性打卡时间设置
  └ flexible_early_minutesint是下班最多可早走，单位：分钟（上班早到几分钟，下班可早走几分钟）
示例值：60
  └ flexible_late_minutesint是上班最多可晚到，单位：分钟（上班晚到几分钟，下班须晚走几分钟）
示例值：60
no_need_offboolean否true为不需要打下班卡。默认为false，需要下班打卡
示例值：true
punch_time_rulepunch_time_rule\[\]是打卡规则
  └ on_timestring是上班时间
示例值："9:00"
  └ off_timestring是下班时间。如果下班时间跨天，则需要在 24 小时的基础上累加时间。例如，第二天凌晨 2 点取值为 26:00
示例值："18:00"
  └ late_minutes_as_lateint是晚到多久记为迟到。单位：分钟
示例值：30
  └ late_minutes_as_lackint是晚到多久记为缺卡。单位：分钟
示例值：60
  └ on_advance_minutesint是最早多久可打上班卡。最大值为 720。单位：分钟
示例值：60
  └ early_minutes_as_earlyint是早退多久记为早退。单位：分钟
示例值：30
  └ early_minutes_as_lackint是早退多久记为缺卡。单位：分钟
示例值：60
  └ off_delay_minutesint是最晚多久可打下班卡。最大值为 960。单位：分钟
示例值：60
  └ late_minutes_as_serious_lateint否晚到多久记为严重迟到。单位：分钟
示例值：40
  └ no_need_onboolean否true为不需要打上班卡，这里需要特别注意，第一段打卡规则须为false。后续可按需配置
示例值：true
  └ no_need_offboolean否true为不需要打下班卡。默认为false，需要下班打卡（优先级高于data.shift.no_need_off）
示例值：true
late_off_late_on_rulelate_off_late_on_rule\[\]否晚走晚到规则（仅飞书人事企业版可用）
  └ late_off_minutesint是晚走多久。单位：分钟
示例值：60
  └ late_on_minutesint是晚到多久。单位：分钟
示例值：30
rest_time_rulerest_rule\[\]否休息规则
  └ rest_begin_timestring是休息开始
示例值："13:00"
  └ rest_end_timestring是休息结束
示例值："14:00"
overtime_ruleovertime_rule\[\]否加班时段（仅飞书人事企业版可用）
  └ on_overtimestring是开始时间
示例值："9:00"
  └ off_overtimestring是结束时间
示例值："18:00"
day_typeint否日期类型，【是否弹性打卡 = true】时，不可设置为“休息日” 可选值：1：工作日 2：休息日。默认值：1
示例值：1
overtime_rest_time_rulerest_rule\[\]否班外休息规则
  └ rest_begin_timestring是休息开始
示例值："13:00"
  └ rest_end_timestring是休息结束
示例值："14:00"
late_minutes_as_serious_lateint否晚到多久记为严重迟到。单位：分钟（优先级高于data.shift.punch_time_rule.late_minutes_as_serious_late）
示例值：40
shift_middle_time_ruleshift_middle_time_rule否半天分割规则（仅飞书人事企业版可用）
  └ middle_time_typeint否半天分割类型
示例值：0
可选值有：
- 0: 按全天班次时长（含休息）的中点分割 - 1: 按全天班次时长（不含休息）的中点分割 - 2: 按休息时间分割 - 3: 按固定时间点分割
默认值：0
  └ fixed_middle_timestring否固定分割时间点（middle_time_type 为 3 时有效）
示例值："12:00"
shift_attendance_time_configshift_attendance_time_config否应出勤配置（灰度中，暂未开放）
  └ attendance_timenumber(float)否应出勤时长
示例值：1
默认值：1
数据校验规则：
- 取值范围：0 ～ 3
  └ on_attendance_timenumber(float)否上半天应出勤时长
示例值：1
默认值：1
数据校验规则：
- 取值范围：0 ～ 3
  └ off_attendance_timenumber(float)否下半天应出勤时长
示例值：1
默认值：1
数据校验规则：
- 取值范围：0 ～ 3
late_off_late_on_settinglate_off_late_on_setting否晚走次日晚到配置规则
  └ late_off_base_on_time_typeint否当日晚走时间计算规则
示例值：0
可选值有：
- 0: 弹性规则 - 1: 固定规则
默认值：0
  └ late_on_base_on_time_typeint否次日晚到时间计算规则
示例值：0
可选值有：
- 0: 固定规则 - 1: 弹性规则
默认值：0
idstring否班次id(更新班次时需要传递)，获取方式：1）按名称查询班次 2）创建班次
示例值："6919358778597097404"
rest_time_flexible_configsrest_time_flexible_config\[\]否休息弹性设置
  └ need_flexibleboolean否是否开启休息弹性班次
示例值：false
  └ late_minsint否休息弹性向后弹的分钟数
示例值：0
数据校验规则：
- 取值范围：0 ～ 1500

请求体示例 ​

json
{
    "shift_name": "早班",
    "punch_times": 1,
    "sub_shift_leader_ids": [
        "456123"
    ],
    "is_flexible": false,
    "flexible_minutes": 60,
    "flexible_rule": [
        {
            "flexible_early_minutes": 60,
            "flexible_late_minutes": 60
        }
    ],
    "no_need_off": true,
    "punch_time_rule": [
        {
            "on_time": "9:00",
            "off_time": "18:00",
            "late_minutes_as_late": 30,
            "late_minutes_as_lack": 60,
            "on_advance_minutes": 60,
            "early_minutes_as_early": 30,
            "early_minutes_as_lack": 60,
            "off_delay_minutes": 60,
            "late_minutes_as_serious_late": 40,
            "no_need_on": true,
            "no_need_off": true
        }
    ],
    "late_off_late_on_rule": [
        {
            "late_off_minutes": 60,
            "late_on_minutes": 30
        }
    ],
    "rest_time_rule": [
        {
            "rest_begin_time": "13:00",
            "rest_end_time": "14:00"
        }
    ],
    "overtime_rule": [
        {
            "on_overtime": "9:00",
            "off_overtime": "18:00"
        }
    ],
    "day_type": 1,
    "overtime_rest_time_rule": [
        {
            "rest_begin_time": "13:00",
            "rest_end_time": "14:00"
        }
    ],
    "late_minutes_as_serious_late": 40,
    "shift_middle_time_rule": {
        "middle_time_type": 0,
        "fixed_middle_time": "12:00"
    },
    "shift_attendance_time_config": {
        "attendance_time": 1,
        "on_attendance_time": 1,
        "off_attendance_time": 1
    },
    "late_off_late_on_setting": {
        "late_off_base_on_time_type": 0,
        "late_on_base_on_time_type": 0
    },
    "id": "6919358778597097404",
    "rest_time_flexible_configs": [
        {
            "need_flexible": false,
            "late_mins": 0
        }
    ]
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ shiftshift班次
    └ shift_idstring班次 ID，调用本接口系统自动生成
    └ shift_namestring班次名称，对应入参的班次名称
    └ punch_timesint打卡次数
    └ sub_shift_leader_idsstring\[\]班次负责人，与employee_type类型对应
    └ is_flexibleboolean是否弹性打卡
    └ flexible_minutesint弹性打卡时间，单位：分钟，设置【上班最多可晚到】与【下班最多可早走】时间，如果不设置flexible_rule则生效
    └ flexible_ruleflexible_rule\[\]弹性打卡时间设置
      └ flexible_early_minutesint下班最多可早走，单位：分钟（上班早到几分钟，下班可早走几分钟）
      └ flexible_late_minutesint上班最多可晚到，单位：分钟（上班晚到几分钟，下班须晚走几分钟）
    └ no_need_offboolean不需要打下班卡
    └ punch_time_rulepunch_time_rule\[\]打卡规则
      └ on_timestring上班时间
      └ off_timestring下班时间
      └ late_minutes_as_lateint晚到多久记为迟到，单位：分钟
      └ late_minutes_as_lackint晚到多久记为缺卡，单位：分钟
      └ on_advance_minutesint最早多久可打上班卡，单位：分钟
      └ early_minutes_as_earlyint早退多久记为早退，单位：分钟
      └ early_minutes_as_lackint早退多久记为缺卡，单位：分钟
      └ off_delay_minutesint最晚多久可打下班卡，单位：分钟
      └ late_minutes_as_serious_lateint晚到多久记为严重迟到。单位：分钟
      └ no_need_onboolean是否不需要打上班卡
      └ no_need_offboolean是否不需要打下班卡（优先级高于data.shift.no_need_off）
    └ late_off_late_on_rulelate_off_late_on_rule\[\]晚走晚到规则
      └ late_off_minutesint晚走多久，单位：分钟
      └ late_on_minutesint晚到多久，单位：分钟
    └ rest_time_rulerest_rule\[\]休息规则
      └ rest_begin_timestring休息开始
      └ rest_end_timestring休息结束
    └ overtime_ruleovertime_rule\[\]打卡规则（暂不支持）
      └ on_overtimestring上班时间
      └ off_overtimestring下班时间
    └ day_typeint日期类型，【是否弹性打卡 = true】时，不可设置为“休息日” 可选值：1：工作日 2：休息日。默认值：1
    └ overtime_rest_time_rulerest_rule\[\]班外休息规则
      └ rest_begin_timestring休息开始
      └ rest_end_timestring休息结束
    └ late_minutes_as_serious_lateint晚到多久记为严重迟到。单位：分钟（优先级高于data.shift.punch_time_rule.late_minutes_as_serious_late）
    └ shift_middle_time_ruleshift_middle_time_rule半天分割规则
      └ middle_time_typeint半天分割类型
可选值有：
- 0: 按全天班次时长（含休息）的中点分割 - 1: 按全天班次时长（不含休息）的中点分割 - 2: 按休息时间分割 - 3: 按固定时间点分割
      └ fixed_middle_timestring固定分割时间点（middle_time_type 为 3 时有效）
    └ shift_attendance_time_configshift_attendance_time_config应出勤配置（灰度中，暂未开放）
      └ attendance_timenumber(float)应出勤时长
      └ on_attendance_timenumber(float)上半天应出勤时长
      └ off_attendance_timenumber(float)下半天应出勤时长
    └ late_off_late_on_settinglate_off_late_on_setting晚走次日晚到配置规则
      └ late_off_base_on_time_typeint当日晚走时间计算规则
可选值有：
- 0: 弹性规则 - 1: 固定规则
      └ late_on_base_on_time_typeint次日晚到时间计算规则
可选值有：
- 0: 固定规则 - 1: 弹性规则
    └ idstring班次id(更新班次时需要传递)
    └ rest_time_flexible_configsrest_time_flexible_config\[\]休息弹性设置
      └ need_flexibleboolean是否开启休息弹性班次
      └ late_minsint休息弹性向后弹的分钟数

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "shift": {
            "shift_id": "6919358778597097404",
            "shift_name": "早班",
            "punch_times": 1,
            "sub_shift_leader_ids": [
                "456123"
            ],
            "is_flexible": false,
            "flexible_minutes": 60,
            "flexible_rule": [
                {
                    "flexible_early_minutes": 60,
                    "flexible_late_minutes": 60
                }
            ],
            "no_need_off": true,
            "punch_time_rule": [
                {
                    "on_time": "9:00",
                    "off_time": "18:00， 第二天凌晨2点， 26:00",
                    "late_minutes_as_late": 30,
                    "late_minutes_as_lack": 60,
                    "on_advance_minutes": 60,
                    "early_minutes_as_early": 30,
                    "early_minutes_as_lack": 60,
                    "off_delay_minutes": 60,
                    "late_minutes_as_serious_late": 40,
                    "no_need_on": true,
                    "no_need_off": true
                }
            ],
            "late_off_late_on_rule": [
                {
                    "late_off_minutes": 60,
                    "late_on_minutes": 30
                }
            ],
            "rest_time_rule": [
                {
                    "rest_begin_time": "13:00",
                    "rest_end_time": "14:00"
                }
            ],
            "overtime_rule": [
                {
                    "on_overtime": "9:00",
                    "off_overtime": "18:00"
                }
            ],
            "day_type": 1,
            "overtime_rest_time_rule": [
                {
                    "rest_begin_time": "13:00",
                    "rest_end_time": "14:00"
                }
            ],
            "late_minutes_as_serious_late": 40,
            "shift_middle_time_rule": {
                "middle_time_type": 0,
                "fixed_middle_time": "12:00"
            },
            "shift_attendance_time_config": {
                "attendance_time": 1,
                "on_attendance_time": 1,
                "off_attendance_time": 1
            },
            "late_off_late_on_setting": {
                "late_off_base_on_time_type": 0,
                "late_on_base_on_time_type": 0
            },
            "id": "6919358778597097404",
            "rest_time_flexible_configs": [
                {
                    "need_flexible": false,
                    "late_mins": 0
                }
            ]
        }
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
4001220001Invalid parameter入参校验失败，请根据具体返回的信息检查入参。例如“employee_type invalid”代表人员类型异常。如仍无法解决可联系 技术支持
4001220002Tenant does not exist请检查入参中的 tenant_access_token是否正确
4001220005No permission请前往考勤管理后台检查数据权限范围
5001225000System error请参考实际返回的错误信息排查问题。例如“internal server error”代表内部服务异常。如仍无法解决可联系 技术支持
5001226000Shift service system error班次服务异常错误码，请参考实际返回的错误信息排查问题。例如“internal server error”代表内部服务异常。如仍无法解决可联系 技术支持
4001226001Shift has been used-
4001226002Shift name has been used-
4001220600General error messageSee the error message for details

内容来源：飞书开放平台 · 自动爬取整理

本镜像仅供学习与查阅，文档版权归飞书所有