按 ID 查询考勤组

通过考勤组 ID 获取考勤组详情。包含基本信息、考勤班次、考勤方式、考勤设置信息

请求

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

请求头

名称	类型	必填	描述
Authorization	string	是	tenant_access_token 值格式："Bearer access_token" 示例值："Bearer t-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token

路径参数

名称	类型	描述
group_id	string	考勤组 ID，获取方式：1）创建或修改考勤组 2）按名称查询考勤组 3）获取打卡结果 示例值："6919358128597097404"

查询参数

名称	类型	必填	描述
employee_type	string	是	请求体和响应体中的 user_id 和 creator_id 的员工id类型。如果没有后台管理权限，可使用通过手机号或邮箱获取用户 ID 示例值：employee_id 可选值有： - employee_id: 员工 employee ID，即飞书管理后台 > 组织架构 > 成员与部门 > 成员详情中的用户 ID - employee_no: 员工工号，即飞书管理后台 > 组织架构 > 成员与部门 > 成员详情中的工号
dept_type	string	是	部门 ID 的类型 示例值：open_id 可选值有： - open_id: 暂时只支持部门的 openid。具体概念请参考部门资源介绍中的open_department_id

响应

响应体

名称	类型	描述
code	int	错误码，非 0 表示失败
msg	string	错误描述
data	group	-
└ group_id	string	考勤组 ID
└ group_name	string	考勤组名称
└ time_zone	string	时区
└ bind_dept_ids	string\[\]	绑定的部门 ID（与「need_punch_members」同时使用时，以当前字段为准）。对应dept_type
└ except_dept_ids	string\[\]	排除的部门 ID（该字段已下线）
└ bind_user_ids	string\[\]	绑定的用户 ID（与「need_punch_members」同时使用时，以当前字段为准），对应employee_type
└ except_user_ids	string\[\]	排除的用户 ID（该字段已下线），对应employee_type
└ group_leader_ids	string\[\]	考勤主负责人 ID 列表，必选字段（需至少拥有考勤组管理员权限），对应employee_type
└ sub_group_leader_ids	string\[\]	考勤子负责人 ID 列表，对应employee_type
└ allow_out_punch	boolean	是否允许外勤打卡
└ out_punch_need_approval	boolean	外勤打卡需审批，先审批后打卡（需要允许外勤打卡才能设置生效）
└ out_punch_need_post_approval	boolean	外勤打卡需审批，先打卡后审批（需要允许外勤打卡才能设置生效）
└ out_punch_need_remark	boolean	外勤打卡需填写备注（需要允许外勤打卡才能设置生效）
└ out_punch_need_photo	boolean	外勤打卡需拍照（需要允许外勤打卡才能设置生效）
└ out_punch_allowed_hide_addr	boolean	外勤打卡允许员工隐藏详细地址（需要允许外勤打卡才能设置生效）
└ out_punch_allowed_adjust_addr	boolean	外勤打卡允许微调地址（需要允许外勤打卡才能设置生效）
└ adjust_range	int	微调范围，默认为 50 米
└ allow_pc_punch	boolean	是否允许 PC 端打卡
└ allow_remedy	boolean	是否限制补卡
└ remedy_limit	boolean	是否限制补卡次数
└ remedy_limit_count	int	补卡次数
└ remedy_date_limit	boolean	是否限制补卡时间
└ remedy_date_num	int	补卡时间，几天内补卡
└ allow_remedy_type_lack	boolean	允许缺卡补卡（需要允许补卡才能设置生效）
└ allow_remedy_type_late	boolean	允许迟到补卡（需要允许补卡才能设置生效）
└ allow_remedy_type_early	boolean	允许早退补卡（需要允许补卡才能设置生效）
└ allow_remedy_type_normal	boolean	允许正常补卡（需要允许补卡才能设置生效）
└ show_cumulative_time	boolean	是否展示累计时长
└ show_over_time	boolean	是否展示加班时长
└ hide_staff_punch_time	boolean	是否隐藏员工打卡详情
└ hide_clock_in_rule	boolean	是否隐藏打卡规则
└ face_punch	boolean	是否开启人脸识别打卡
└ face_punch_cfg	int	人脸识别打卡规则 可选值有： * 1：每次打卡均需人脸识别 * 2：疑似作弊打卡时需要人脸识别
└ face_live_need_action	boolean	人脸打卡规则。 可选值有： * false：开启活体验证 * true：动作验证，仅在 face_punch_cfg = 1 时有效
└ face_downgrade	boolean	人脸识别失败时是否允许普通拍照打卡
└ replace_basic_pic	boolean	人脸识别失败时是否允许替换基准图片
└ anti_cheat_punch_config	anti_cheat_config	防作弊打卡配置（仅灰度租户有效）
└ intercept_suspected_cheat_punch	boolean	是否拦截疑似作弊打卡总开关；关闭时，其余防作弊开关都为关闭状态
└ check_cheat_software_punch	boolean	是否校验疑似作弊软件打卡
└ check_buddy_punch	boolean	是否校验疑似他人代打卡
└ check_simulate_wifi_punch	boolean	Whether to check the suspected analog Wi-Fi clock in
└ check_change_device_punch	boolean	是否校验更换设备打卡
└ allow_change_device_num	int	同一考勤人员最多可绑定打卡设备数量上限
└ suspected_cheat_handle_method	int	疑似作弊打卡时的处理方式，开启拦截疑似作弊打卡时必填 可选值有： - 1: 使用人脸识别打卡 - 2: 仅记录疑似作弊信息
└ machines	machine\[\]	考勤机列表
└ machine_sn	string	考勤机序列号
└ machine_name	string	考勤机名称
└ gps_range	int	GPS 打卡的有效范围（不建议使用）
└ locations	location\[\]	地址列表（仅追加，不会覆盖之前的列表）
└ location_id	string	地址 ID，系统ID只透传，暂时无用
└ location_name	string	地址名称
└ location_type	int	地址类型 可选值有： * 1：GPS * 2：Wi-Fi * 8：IP
└ latitude	number(float)	地址纬度
└ longitude	number(float)	地址经度
└ ssid	string	Wi-Fi
└ bssid	string	Wi-Fi
└ map_type	int	地图类型，1：高德， 2：谷歌
└ address	string	地址名称
└ ip	string	IP 地址
└ feature	string	额外信息，例如：运营商信息
└ gps_range	int	GPS 打卡的有效范围
└ group_type	int	考勤类型，0：固定班制，2：排班制， 3：自由班制
└ punch_day_shift_ids	string\[\]	班次 ID 列表。仅当考勤类型为固定班制时，该参数有值。
└ free_punch_cfg	free_punch_cfg	配置自由班制
└ free_start_time	string	自由班制打卡开始时间
└ free_end_time	string	自由班制打卡结束时间
└ punch_day	int	打卡的时间，为 7 位数字，每一位依次代表周一到周日，0 为不上班，1 为上班。例如示例值1111100，代表从周一到周五上班，周六周日休息
└ work_day_no_punch_as_lack	boolean	工作日不打卡是否记为缺卡
└ work_hours_demand	boolean	工作日出勤是否需满足时长要求
└ work_hours	int	每日工作时长（分钟),范围[0,1440]
└ free_clock_setting	free_clock_setting	自由班制的打卡配置
└ clock_mode	int	打卡模式
└ clock_internal_hhmm	int	最小打卡间隔
└ calendar_id	int	国家日历 ID，0：不根据国家日历排休，1：中国大陆，2：美国，3：日本，4：印度，5：新加坡，默认 1
└ need_punch_special_days	punch_special_date_shift\[\]	必须打卡的特殊日期
└ punch_day	int	打卡日期
└ shift_id	string	班次 ID，可使用此id查询班次详情
└ no_need_punch_special_days	punch_special_date_shift\[\]	无需打卡的特殊日期
└ punch_day	int	打卡日期
└ shift_id	string	班次 ID
└ work_day_no_punch_as_lack	boolean	自由班制下工作日不打卡是否记为缺卡
└ remedy_period_type	int	补卡周期类型。1为按自然月，2为自定义周期 * 1：MONTH * 2：CUSTOM
└ remedy_period_custom_date	int	补卡自定义周期起始日期
└ punch_type	int	打卡类型，位运算。1：GPS 打卡，2：Wi-Fi 打卡，4：考勤机打卡，8：IP 打卡
└ effect_time	string	生效时间，精确到秒的时间戳
└ fixshift_effect_time	string	固定班次生效时间，精确到秒的时间戳
└ member_effect_time	string	参加考勤的人员、部门变动生效时间，精确到秒的时间戳
└ rest_clockIn_need_approval	boolean	休息日打卡需审批
└ clockIn_need_photo	boolean	每次打卡均需拍照
└ member_status_change	member_status_change	人员异动打卡设置
└ onboarding_on_no_need_punch	boolean	是否入职日上班无需打卡
└ onboarding_off_no_need_punch	boolean	是否入职日下班无需打卡
└ offboarding_on_no_need_punch	boolean	是否离职日上班无需打卡
└ offboarding_off_no_need_punch	boolean	是否离职日下班无需打卡
└ leave_need_punch	boolean	请假离岗或返岗是否需打卡
└ leave_need_punch_cfg	leave_need_punch_cfg	请假离岗或返岗打卡规则，单位：分钟
└ late_minutes_as_late	int	晚到超过多久记为迟到，单位：分钟
└ late_minutes_as_lack	int	晚到超过多久记为缺卡，单位：分钟
└ early_minutes_as_early	int	早走超过多久记为早退，单位：分钟
└ early_minutes_as_lack	int	早走超过多久记为缺卡，单位：分钟
└ not_during_shift	boolean	班次中间请假，无需在离岗前或返岗后打卡（仅灰度租户有效，如需使用请联系技术支持）
└ go_out_need_punch	int	外出期间是否需打卡
└ go_out_need_punch_cfg	leave_need_punch_cfg	外出期间打卡规则，单位：分钟
└ late_minutes_as_late	int	晚到超过多久记为迟到，单位：分钟
└ late_minutes_as_lack	int	晚到超过多久记为缺卡，单位：分钟
└ early_minutes_as_early	int	早走超过多久记为早退，单位：分钟
└ early_minutes_as_lack	int	早走超过多久记为缺卡，单位：分钟
└ not_during_shift	boolean	班次中间外出，无需在离岗前或返岗后打卡（仅灰度租户有效，如需使用请联系技术支持）
└ travel_need_punch	int	出差期间是否需打卡
└ travel_need_punch_cfg	leave_need_punch_cfg	出差期间打卡规则，单位：分钟
└ late_minutes_as_late	int	晚到超过多久记为迟到，单位：分钟
└ late_minutes_as_lack	int	晚到超过多久记为缺卡，单位：分钟
└ early_minutes_as_early	int	早走超过多久记为早退，单位：分钟
└ early_minutes_as_lack	int	早走超过多久记为缺卡，单位：分钟
└ not_during_shift	boolean	无需在出差离岗前或返岗后打卡（出差不生效）
└ need_punch_members	punch_member\[\]	需要打卡的人员集合（当「bind_dept_ids」和「bind_user_ids」不为空时，以「bind_dept_ids」和「bind_user_ids」为准）
└ rule_scope_type	int	圈人方式 可选值有： * 0 无 * 1 全部 * 2 自定义
└ scope_group_list	scope_group	圈人规则列表，返回的规则之间为且关系，或关系的规则暂不支持返回
└ scope_value_type	int	类型： * 1: 部门 * 2:人员 * 3: 国家地区 * 4: 员工类型 * 5: 工作城市 * 6: 职级 * 7: 序列 * 8: 职务（企业版） * 9: 工时制度（企业版） * 100: 自定义字段（企业版）
└ operation_type	int	范围类型（是否包含） * 1: 包含 * 2: 不包含 * 3: 相等 * 4: 小于等于 * 5: 大于等于 * 6: 大于 * 7: 小于 * 8: 不相等
└ right	scope_value\[\]	如果是人员/部门类型 不需要使用该字段
└ key	string	标识Key
└ name	string	名称
└ member_ids	string\[\]	部门/人员id列表（具体类型根据scope_value_type判断）
└ custom_field_ID	string	企业版自定义字段唯一键 ID, 需要从飞书人事获取
└ custom_field_obj_type	string	企业版自定义字段对象类型 * "Employment": 主数据对象，员工雇佣信息 * "Person": 主数据对象，个人
└ no_need_punch_members	punch_member\[\]	无需打卡的人员集合（当「bind_default_dept_ids」和「bind_default_user_ids」不为空时，以「bind_default_dept_ids」和「bind_default_user_ids」为准）
└ rule_scope_type	int	圈人方式 可选值有： * 0 无 * 1 全部 * 2 自定义
└ scope_group_list	scope_group	圈人规则列表，返回的规则之间为且关系，或关系的规则暂不支持返回
└ scope_value_type	int	类型： * 1: 部门 * 2:人员 * 3: 国家地区 * 4: 员工类型 * 5: 工作城市 * 6: 职级 * 7: 序列 * 8: 职务（企业版） * 9: 工时制度（企业版） * 100: 自定义字段（企业版）
└ operation_type	int	范围类型（是否包含） * 1: 包含 * 2: 不包含 * 3: 相等 * 4: 小于等于 * 5: 大于等于 * 6: 大于 * 7: 小于 * 8: 不相等
└ right	scope_value\[\]	如果是人员/部门类型 不需要使用该字段
└ key	string	标识Key
└ name	string	名称
└ member_ids	string\[\]	部门/人员id列表（具体类型根据scope_value_type判断）
└ custom_field_ID	string	企业版自定义字段唯一键 ID, 需要从飞书人事获取
└ custom_field_obj_type	string	企业版自定义字段对象类型 * "Employment": 主数据对象，员工雇佣信息 * "Person": 主数据对象，个人
└ save_auto_changes	boolean	是否允许保存有冲突人员的考勤组。如果 true，则冲突人员将被自动拉入到当前设置的考勤组中，并从原考勤组中移除；如果 false，则需手动调整冲突人员
└ org_change_auto_adjust	boolean	当有新员工入职或人员异动，符合条件的人员是否自动加入考勤组
└ bind_default_dept_ids	string\[\]	参与无需打卡的部门 ID 列表（与「no_need_punch_members」同时使用时，以当前字段为准）。对应dept_type
└ bind_default_user_ids	string\[\]	参与无需打卡的人员 ID 列表（与「no_need_punch_members」同时使用时，以当前字段为准）。对应employee_type
└ overtime_clock_cfg	overtime_clock_cfg	加班打卡规则
└ allow_punch_approval	boolean	是否允许在非打卡时段申请打卡（仅灰度租户可用）
└ need_clock_over_time_start_and_end	boolean	加班开始和结束需打卡(需灰度)
└ new_calendar_id	string	节假日id，（如果考勤组使用了自定义节假日，请用此参数传入节假日id）
└ allow_apply_punch	boolean	定位不准时是否允许申请打卡
└ clock_in_abnormal_settings	ClockInAbnormalSettings	异常卡豁免配置
└ ignore_until_latest_clockout	boolean	在最晚下班打卡之前忽略异常卡（仅灰度租户有效）

响应体示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "group_id": "6919358128597097404",
        "group_name": "开心考勤",
        "time_zone": "Asia/Shanghai",
        "bind_dept_ids": [
            "od-fcb45c28a45311afd440b7869541fce8"
        ],
        "except_dept_ids": [
            "od-fcb45c28a45311afd440b7869541fce8"
        ],
        "bind_user_ids": [
            "52aa1fa1"
        ],
        "except_user_ids": [
            "4fasdtc2"
        ],
        "group_leader_ids": [
            "52aa1fa1"
        ],
        "sub_group_leader_ids": [
            "4fasdtc2"
        ],
        "allow_out_punch": true,
        "out_punch_need_approval": true,
        "out_punch_need_post_approval": true,
        "out_punch_need_remark": true,
        "out_punch_need_photo": true,
        "out_punch_allowed_hide_addr": true,
        "out_punch_allowed_adjust_addr": true,
        "adjust_range": 50,
        "allow_pc_punch": true,
        "allow_remedy": true,
        "remedy_limit": true,
        "remedy_limit_count": 3,
        "remedy_date_limit": true,
        "remedy_date_num": 3,
        "allow_remedy_type_lack": true,
        "allow_remedy_type_late": true,
        "allow_remedy_type_early": true,
        "allow_remedy_type_normal": true,
        "show_cumulative_time": true,
        "show_over_time": true,
        "hide_staff_punch_time": true,
        "hide_clock_in_rule": false,
        "face_punch": true,
        "face_punch_cfg": 1,
        "face_live_need_action": true,
        "face_downgrade": true,
        "replace_basic_pic": true,
        "anti_cheat_punch_config": {
            "intercept_suspected_cheat_punch": true,
            "check_cheat_software_punch": true,
            "check_buddy_punch": true,
            "check_simulate_wifi_punch": true,
            "check_change_device_punch": true,
            "allow_change_device_num": 1,
            "suspected_cheat_handle_method": 1
        },
        "machines": [
            {
                "machine_sn": "FS0701",
                "machine_name": "创实 9 楼"
            }
        ],
        "gps_range": 300,
        "locations": [
            {
                "location_id": "6921213751454744578",
                "location_name": "浙江省杭州市余杭区五常街道木桥头西溪八方城",
                "location_type": 1,
                "latitude": 30.28994,
                "longitude": 120.04509,
                "ssid": "TP-Link-af12ca",
                "bssid": "08:00:20:0A:8C:6D",
                "map_type": 1,
                "address": "北京市海淀区中航广场",
                "ip": "122.224.123.146",
                "feature": "中国电信",
                "gps_range": 300
            }
        ],
        "group_type": 0,
        "punch_day_shift_ids": [
            "xxx"
        ],
        "free_punch_cfg": {
            "free_start_time": "7:00",
            "free_end_time": "18:00",
            "punch_day": 1111100,
            "work_day_no_punch_as_lack": true,
            "work_hours_demand": false,
            "work_hours": 480
           
        },
        "calendar_id": 1,
        "need_punch_special_days": [
            {
                "punch_day": 20190101,
                "shift_id": "6919668827865513935"
            }
        ],
        "no_need_punch_special_days": [
            {
                "punch_day": 20190101,
                "shift_id": "6919668827865513935"
            }
        ],
        "work_day_no_punch_as_lack": true,
        "remedy_period_type": 1,
        "remedy_period_custom_date": 1,
        "punch_type": 1,
        "effect_time": "1611476284",
        "fixshift_effect_time": "1611476284",
        "member_effect_time": "1611476284",
        "rest_clockIn_need_approval": true,
        "clockIn_need_photo": true,
        "member_status_change": {
            "onboarding_on_no_need_punch": false,
            "onboarding_off_no_need_punch": false,
            "offboarding_on_no_need_punch": false,
            "offboarding_off_no_need_punch": false
        },
        "leave_need_punch": false,
        "leave_need_punch_cfg": {
            "late_minutes_as_late": 0,
            "late_minutes_as_lack": 0,
            "early_minutes_as_early": 0,
            "early_minutes_as_lack": 0,
            "not_during_shift": false
        },
        "go_out_need_punch": 0,
        "go_out_need_punch_cfg": {
            "late_minutes_as_late": 0,
            "late_minutes_as_lack": 0,
            "early_minutes_as_early": 0,
            "early_minutes_as_lack": 0,
            "not_during_shift": false
        },
        "travel_need_punch": 0,
        "travel_need_punch_cfg": {
            "late_minutes_as_late": 0,
            "late_minutes_as_lack": 0,
            "early_minutes_as_early": 0,
            "early_minutes_as_lack": 0,
            "not_during_shift": false
        },
        "need_punch_members": [
            {
                "rule_scope_type": 0,
                "scope_group_list": {
                    "scope_value_type": 1,
                    "operation_type": 1,
                    "right": [
                        {
                            "key": "CH",
                            "name": "中国大陆"
                        }
                    ],
                    "member_ids": [
                        "ec8ddg56"
                    ],
                    "custom_field_ID": "123213123",
                    "custom_field_obj_type": "employment"
                }
            }
        ],
        "no_need_punch_members": [
            {
                "rule_scope_type": 0,
                "scope_group_list": {
                    "scope_value_type": 1,
                    "operation_type": 1,
                    "right": [
                        {
                            "key": "CH",
                            "name": "中国大陆"
                        }
                    ],
                    "member_ids": [
                        "ec8ddg56"
                    ],
                    "custom_field_ID": "123213123",
                    "custom_field_obj_type": "employment"
                }
            }
        ],
        "save_auto_changes": false,
        "org_change_auto_adjust": false,
        "bind_default_dept_ids": [
            "od-fcb45c28a45311afd440b7869541fce8"
        ],
        "bind_default_user_ids": [
            "dd31248a"
        ],
        "overtime_clock_cfg": {
            "allow_punch_approval": false,
            "need_clock_over_time_start_and_end": false
        },
        "new_calendar_id": "通过查询考勤组接口获取的new_calendar_id，例如7302191700771358252",
        "allow_apply_punch": true,
        "clock_in_abnormal_settings": {
            "ignore_until_latest_clockout": false
        }
    }
}

错误码

HTTP状态码	错误码	描述	排查建议
400	1220001	param is invalid	入参校验失败，请根据具体返回的信息检查入参。例如“employee_type invalid”代表人员类型异常。如仍无法解决可联系 技术支持
400	1220002	tenant_id is empty	请检查入参中的 tenant_access_token是否正确
400	1220003	user_id type is not employee_id or employee_no	employee_type只支持取值为 employee_id或者employee_no
500	1225000	param is invalid	请参考实际返回的错误信息排查问题。例如“internal server error”代表内部服务异常。如仍无法解决可联系 技术支持
500	1227000	历史错误码，不再使用	-
400	1220600	通用错误信息	通用错误信息包含多条，详细的错误信息以及处理建议可参见 错误信息