# 创建班次
该接口用于创建企业的考勤班次。
**注意事项**：- 创建一个考勤组前，必须先创建一个或者多个班次。
- 一个公司内的班次是共享的，你可以直接引用他人创建的班次，但是需要注意的是，若他人修改了班次，会影响到你的考勤组及其考勤结果。
## 请求
基本 |
---|---
HTTP URL | https://open.feishu.cn/open-apis/attendance/v1/shifts
HTTP Method | POST
接口频率限制 | [50 次/秒](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
支持的应用类型 | Custom App
权限要求
**调用该 API 所需的权限。开启其中任意一项权限即可调用** | 写入打卡管理规则(attendance:rule)
### 请求头
名称 | 类型 | 必填 | 描述
---|---|---|---
Authorization | string | 是 | `tenant_access_token`
**值格式**："Bearer `access_token`"
**示例值**："Bearer t-7f1bcd13fc57d46bac21793a18e560"
[了解更多：如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use)
Content-Type | string | 是 | **固定值**："application/json; charset=utf-8"
### 查询参数
名称 | 类型 | 必填 | 描述
---|---|---|---
employee_type | string | 否 | 请求体中的 user_ids 和响应体中的 user_id 的员工ID类型。如果没有后台管理权限，可使用[通过手机号或邮箱获取用户 ID](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/user/batch_get_id)
**示例值**：employee_id
**可选值有**：
- employee_id：员工 employee ID，即[飞书管理后台](https://example.feishu.cn/admin/contacts/departmentanduser) > 组织架构 > 成员与部门 > 成员详情中的用户 ID，或者[通过手机号或邮箱获取用户 ID](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/user/batch_get_id)获取的user_id。
- employee_no：员工工号，即[飞书管理后台](https://example.feishu.cn/admin/contacts/departmentanduser) > 组织架构 > 成员与部门 > 成员详情中的工号
### 请求体
名称 | 类型 | 必填 | 描述
---|---|---|---
shift_name | string | 是 | 班次名称，不可重复
**示例值**："早班"
punch_times | int | 是 | 打卡次数（历史字段，已无用，以punch_time_rule为准）
**示例值**：1
sub_shift_leader_ids | string\[\] | 否 | 班次负责人，与employee_type类型对应
**示例值**：["456123"]
is_flexible | boolean | 否 | 是否弹性打卡。true 为开启，false 为不开启。默认为 false。
**示例值**：false
flexible_minutes | int | 否 | 弹性打卡时间，单位为分钟。设置“上班最多可晚到”与“下班最多可早走”的时间。仅当 flexible_rule 参数未设置时，该参数生效。
**示例值**：60
flexible_rule | flexible_rule\[\] | 否 | 弹性打卡时间设置
flexible_early_minutes | int | 是 | 下班最多可早走，单位：分钟（上班早到几分钟，下班可早走几分钟）
**示例值**：60
flexible_late_minutes | int | 是 | 上班最多可晚到，单位：分钟（上班晚到几分钟，下班须晚走几分钟）
**示例值**：60
no_need_off | boolean | 否 | true为不需要打下班卡。默认为false，需要下班打卡
**示例值**：true
punch_time_rule | punch_time_rule\[\] | 是 | 打卡规则
on_time | string | 是 | 上班时间
**示例值**："9:00"
off_time | string | 是 | 下班时间。如果下班时间跨天，则需要在 24 小时的基础上累加时间。例如，第二天凌晨 2 点取值为 26:00
**示例值**："18:00"
late_minutes_as_late | int | 是 | 晚到多久记为迟到。单位：分钟
**示例值**：30
late_minutes_as_lack | int | 是 | 晚到多久记为缺卡。单位：分钟
**示例值**：60
on_advance_minutes | int | 是 | 最早多久可打上班卡。最大值为 720。单位：分钟
**示例值**：60
early_minutes_as_early | int | 是 | 早退多久记为早退。单位：分钟
**示例值**：30
early_minutes_as_lack | int | 是 | 早退多久记为缺卡。单位：分钟
**示例值**：60
off_delay_minutes | int | 是 | 最晚多久可打下班卡。最大值为 960。单位：分钟
**示例值**：60
late_minutes_as_serious_late | int | 否 | 晚到多久记为严重迟到。单位：分钟
**示例值**：40
no_need_on | boolean | 否 | true为不需要打上班卡，这里需要特别注意，第一段打卡规则须为false。后续可按需配置
**示例值**：true
no_need_off | boolean | 否 | true为不需要打下班卡。默认为false，需要下班打卡（优先级高于data.shift.no_need_off）
**示例值**：true
late_off_late_on_rule | late_off_late_on_rule\[\] | 否 | 晚走晚到规则（仅飞书人事企业版可用）
late_off_minutes | int | 是 | 晚走多久。单位：分钟
**示例值**：60
late_on_minutes | int | 是 | 晚到多久。单位：分钟
**示例值**：30
rest_time_rule | rest_rule\[\] | 否 | 休息规则
rest_begin_time | string | 是 | 休息开始
**示例值**："13:00"
rest_end_time | string | 是 | 休息结束
**示例值**："14:00"
overtime_rule | overtime_rule\[\] | 否 | 加班时段（仅飞书人事企业版可用）
on_overtime | string | 是 | 开始时间
**示例值**："9:00"
off_overtime | string | 是 | 结束时间
**示例值**："18:00"
day_type | int | 否 | 日期类型，【是否弹性打卡 = true】时，不可设置为“休息日” 可选值：1：工作日 2：休息日。默认值：1
**示例值**：1
overtime_rest_time_rule | rest_rule\[\] | 否 | 班外休息规则
rest_begin_time | string | 是 | 休息开始
**示例值**："13:00"
rest_end_time | string | 是 | 休息结束
**示例值**："14:00"
late_minutes_as_serious_late | int | 否 | 晚到多久记为严重迟到。单位：分钟（优先级高于data.shift.punch_time_rule.late_minutes_as_serious_late）
**示例值**：40
shift_middle_time_rule | shift_middle_time_rule | 否 | 半天分割规则（仅飞书人事企业版可用）
middle_time_type | int | 否 | 半天分割类型
**示例值**：0
**可选值有**：
- 0：按全天班次时长（含休息）的中点分割
- 1：按全天班次时长（不含休息）的中点分割
- 2：按休息时间分割
- 3：按固定时间点分割
**默认值**：`0`
fixed_middle_time | string | 否 | 固定分割时间点（middle_time_type 为 3 时有效）
**示例值**："12:00"
shift_attendance_time_config | shift_attendance_time_config | 否 | 应出勤配置（灰度中，暂未开放）
attendance_time | number(float) | 否 | 应出勤时长
**示例值**：1
**默认值**：`1`
**数据校验规则**：
- 取值范围：`0` ～ `3`
on_attendance_time | number(float) | 否 | 上半天应出勤时长
**示例值**：1
**默认值**：`1`
**数据校验规则**：
- 取值范围：`0` ～ `3`
off_attendance_time | number(float) | 否 | 下半天应出勤时长
**示例值**：1
**默认值**：`1`
**数据校验规则**：
- 取值范围：`0` ～ `3`
late_off_late_on_setting | late_off_late_on_setting | 否 | 晚走次日晚到配置规则
late_off_base_on_time_type | int | 否 | 当日晚走时间计算规则
**示例值**：0
**可选值有**：
- 0：弹性规则
- 1：固定规则
**默认值**：`0`
late_on_base_on_time_type | int | 否 | 次日晚到时间计算规则
**示例值**：0
**可选值有**：
- 0：固定规则
- 1：弹性规则
**默认值**：`0`
id | string | 否 | 班次id(更新班次时需要传递)，获取方式：1）[按名称查询班次](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/attendance-v1/shift/query) 2）[创建班次](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/attendance-v1/shift/create)
**示例值**："6919358778597097404"
rest_time_flexible_configs | rest_time_flexible_config\[\] | 否 | 休息弹性设置
need_flexible | boolean | 否 | 是否开启休息弹性班次
**示例值**：false
late_mins | int | 否 | 休息弹性向后弹的分钟数
**示例值**：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
}
]
}
```
## 响应
### 响应体
名称 | 类型 | 描述
---|---|---
code | int | 错误码，非 0 表示失败
msg | string | 错误描述
data | \- | \-
shift | shift | 班次
shift_id | string | 班次 ID，调用本接口系统自动生成
shift_name | string | 班次名称，对应入参的班次名称
punch_times | int | 打卡次数
sub_shift_leader_ids | string\[\] | 班次负责人，与employee_type类型对应
is_flexible | boolean | 是否弹性打卡
flexible_minutes | int | 弹性打卡时间，单位：分钟，设置【上班最多可晚到】与【下班最多可早走】时间，如果不设置flexible_rule则生效
flexible_rule | flexible_rule\[\] | 弹性打卡时间设置
flexible_early_minutes | int | 下班最多可早走，单位：分钟（上班早到几分钟，下班可早走几分钟）
flexible_late_minutes | int | 上班最多可晚到，单位：分钟（上班晚到几分钟，下班须晚走几分钟）
no_need_off | boolean | 不需要打下班卡
punch_time_rule | punch_time_rule\[\] | 打卡规则
on_time | string | 上班时间
off_time | string | 下班时间
late_minutes_as_late | int | 晚到多久记为迟到，单位：分钟
late_minutes_as_lack | int | 晚到多久记为缺卡，单位：分钟
on_advance_minutes | int | 最早多久可打上班卡，单位：分钟
early_minutes_as_early | int | 早退多久记为早退，单位：分钟
early_minutes_as_lack | int | 早退多久记为缺卡，单位：分钟
off_delay_minutes | int | 最晚多久可打下班卡，单位：分钟
late_minutes_as_serious_late | int | 晚到多久记为严重迟到。单位：分钟
no_need_on | boolean | 是否不需要打上班卡
no_need_off | boolean | 是否不需要打下班卡（优先级高于data.shift.no_need_off）
late_off_late_on_rule | late_off_late_on_rule\[\] | 晚走晚到规则
late_off_minutes | int | 晚走多久，单位：分钟
late_on_minutes | int | 晚到多久，单位：分钟
rest_time_rule | rest_rule\[\] | 休息规则
rest_begin_time | string | 休息开始
rest_end_time | string | 休息结束
overtime_rule | overtime_rule\[\] | 打卡规则（暂不支持）
on_overtime | string | 上班时间
off_overtime | string | 下班时间
day_type | int | 日期类型，【是否弹性打卡 = true】时，不可设置为“休息日” 可选值：1：工作日 2：休息日。默认值：1
overtime_rest_time_rule | rest_rule\[\] | 班外休息规则
rest_begin_time | string | 休息开始
rest_end_time | string | 休息结束
late_minutes_as_serious_late | int | 晚到多久记为严重迟到。单位：分钟（优先级高于data.shift.punch_time_rule.late_minutes_as_serious_late）
shift_middle_time_rule | shift_middle_time_rule | 半天分割规则
middle_time_type | int | 半天分割类型
**可选值有**：
- 0：按全天班次时长（含休息）的中点分割
- 1：按全天班次时长（不含休息）的中点分割
- 2：按休息时间分割
- 3：按固定时间点分割
fixed_middle_time | string | 固定分割时间点（middle_time_type 为 3 时有效）
shift_attendance_time_config | shift_attendance_time_config | 应出勤配置（灰度中，暂未开放）
attendance_time | number(float) | 应出勤时长
on_attendance_time | number(float) | 上半天应出勤时长
off_attendance_time | number(float) | 下半天应出勤时长
late_off_late_on_setting | late_off_late_on_setting | 晚走次日晚到配置规则
late_off_base_on_time_type | int | 当日晚走时间计算规则
**可选值有**：
- 0：弹性规则
- 1：固定规则
late_on_base_on_time_type | int | 次日晚到时间计算规则
**可选值有**：
- 0：固定规则
- 1：弹性规则
id | string | 班次id(更新班次时需要传递)
rest_time_flexible_configs | rest_time_flexible_config\[\] | 休息弹性设置
need_flexible | boolean | 是否开启休息弹性班次
late_mins | int | 休息弹性向后弹的分钟数
### 响应体示例
```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状态码 | 错误码 | 描述 | 排查建议
---|---|---|---
400 | 1220001 | Invalid parameter | 入参校验失败，请根据具体返回的信息检查入参。例如“employee_type invalid”代表人员类型异常。如仍无法解决可联系 [技术支持](https://applink.feishu.cn/TLJpeNdW)
400 | 1220002 | Tenant does not exist | 请检查入参中的 tenant_access_token是否正确
400 | 1220005 | No permission | 请前往[考勤管理后台](https://oa.feishu.cn/attendance/manage/member/list)检查数据权限范围
500 | 1225000 | System error | 请参考实际返回的错误信息排查问题。例如“internal server error”代表内部服务异常。如仍无法解决可联系 [技术支持](https://applink.feishu.cn/TLJpeNdW)
500 | 1226000 | Shift service system error | 班次服务异常错误码，请参考实际返回的错误信息排查问题。例如“internal server error”代表内部服务异常。如仍无法解决可联系 [技术支持](https://applink.feishu.cn/TLJpeNdW)
400 | 1226001 | Shift has been used | -
400 | 1226002 | Shift name has been used | -
400 | 1220600 | General error message | See the error message for details