飞书开放平台 Server API 文档

主题

创建或修改考勤组 ​

考勤组，是对部门或者员工在某个特定场所及特定时间段内的出勤情况（包括上下班、迟到、早退、病假、婚假、丧假、公休、工作时间、加班情况等）的一种规则设定。

通过设置考勤组，可以从部门、员工两个维度，来设定考勤方式、考勤时间、考勤地点等考勤规则。

对应功能同设置-假勤设置-考勤组的“新建”功能

Warning: 注意：此接口在修改时为数据覆盖，需要传入全部的考勤组信息

Tip: 出于安全考虑，如果传入操作人，该接口只允许修改操作人有权限的考勤组。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/attendance/v1/groups
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_id 的员工ID类型。如果没有后台管理权限，可使用通过手机号或邮箱获取用户 ID
示例值：employee_id
可选值有：
- employee_id: 员工 employee ID，即飞书管理后台 > 组织架构 > 成员与部门 > 成员详情中的用户 ID - employee_no: 员工工号，即飞书管理后台 > 组织架构 > 成员与部门 > 成员详情中的工号
dept_typestring是部门 ID 的类型
示例值：open_id
可选值有：
- open_id: 暂时只支持部门的 open_id。具体概念请参考部门资源介绍中的open_department_id

请求体 ​

名称类型必填描述
groupgroup是考勤组信息
  └ group_idstring否考勤组 ID（仅修改时提供）， 需要从按名称查询考勤组 或查询所有考勤组 接口中获取 groupId。如果不填的话，会创建新的考勤组。
示例值："6919358128597097404"
  └ group_namestring是考勤组名称
示例值："开心考勤"
  └ time_zonestring是时区
示例值："Asia/Shanghai"
  └ bind_dept_idsstring\[\]否绑定的部门 ID（与「need_punch_members」同时使用时，以当前字段为准）。对应dept_type
示例值：["od-fcb45c28a45311afd440b7869541fce8"]
  └ except_dept_idsstring\[\]否排除的部门 ID（该字段已下线）
示例值：["od-fcb45c28a45311afd440b7869541fce8"]
  └ bind_user_idsstring\[\]否绑定的用户 ID（与「need_punch_members」同时使用时，以当前字段为准），对应employee_type
示例值：["52aa1fa1"]
  └ except_user_idsstring\[\]否排除的用户 ID（该字段已下线）
示例值：["52aa1fa1"]
  └ group_leader_idsstring\[\]是考勤主负责人 ID 列表，必选字段（需至少拥有考勤组管理员权限），对应employee_type
示例值：["2bg4a9be"]
  └ sub_group_leader_idsstring\[\]否考勤子负责人 ID 列表，对应employee_type
示例值：["52aa1fa1"]
  └ allow_out_punchboolean否是否允许外勤打卡，默认为空
示例值：true
  └ out_punch_need_approvalboolean否外勤打卡需审批（需要允许外勤打卡才能设置生效），默认为空
示例值：true
  └ out_punch_need_post_approvalboolean否外勤打卡需审批，先打卡后审批（需要允许外勤打卡才能设置生效）
示例值：true
  └ out_punch_need_remarkboolean否外勤打卡需填写备注（需要允许外勤打卡才能设置生效），默认为空
示例值：true
  └ out_punch_need_photoboolean否外勤打卡需拍照（需要允许外勤打卡才能设置生效），默认为空
示例值：true
  └ out_punch_allowed_hide_addrboolean否外勤打卡允许员工隐藏详细地址（需要允许外勤打卡才能设置生效），默认为空
示例值：true
  └ out_punch_allowed_adjust_addrboolean否外勤打卡允许微调地址（需要允许外勤打卡才能设置生效）
示例值：true
  └ adjust_rangeint否微调范围，默认为 50 米
示例值：50
  └ allow_pc_punchboolean否是否允许 PC 端打卡，默认为空
示例值：true
  └ allow_remedyboolean否是否限制补卡，默认为空
示例值：true
  └ remedy_limitboolean否是否限制补卡次数，默认为空
示例值：true
  └ remedy_limit_countint否补卡次数，默认为空
示例值：3
  └ remedy_date_limitboolean否是否限制补卡时间，默认为空
示例值：true
  └ remedy_date_numint否补卡时间，几天内补卡，默认为空
示例值：3
  └ allow_remedy_type_lackboolean否允许缺卡补卡（需要允许补卡才能设置生效），默认为空
示例值：true
  └ allow_remedy_type_lateboolean否允许迟到补卡（需要允许补卡才能设置生效），默认为空
示例值：true
  └ allow_remedy_type_earlyboolean否允许早退补卡（需要允许补卡才能设置生效），默认为空
示例值：true
  └ allow_remedy_type_normalboolean否允许正常补卡（需要允许补卡才能设置生效），默认为空
示例值：true
  └ show_cumulative_timeboolean否是否展示累计时长，默认为空
示例值：true
  └ show_over_timeboolean否是否展示加班时长，默认为空
示例值：true
  └ hide_staff_punch_timeboolean否是否隐藏员工打卡详情，默认为空
示例值：true
  └ hide_clock_in_ruleboolean否是否隐藏打卡规则（仅灰度租户有效，如需使用请联系技术支持）
示例值：false
  └ face_punchboolean否是否开启人脸识别打卡，默认为空
示例值：true
  └ face_punch_cfgint否人脸识别打卡规则，默认为空
可选值有： * 1：每次打卡均需人脸识别 * 2：疑似作弊打卡时需要人脸识别
示例值：1
  └ face_live_need_actionboolean否人脸打卡规则，默认为空
可选值有： * false：表示开启活体验证 * true：表示动作验证，仅在 face_punch_cfg = 1 时有效
示例值：false
  └ face_downgradeboolean否人脸识别失败时是否允许普通拍照打卡，默认为空
示例值：true
  └ replace_basic_picboolean否人脸识别失败时是否允许替换基准图片，默认为空
示例值：true
  └ anti_cheat_punch_configanti_cheat_config否防作弊打卡配置，不传入时默认关闭/不更新（仅灰度租户有效，如需使用请联系技术支持）
    └ intercept_suspected_cheat_punchboolean是是否拦截疑似作弊打卡，不传入时默认关闭/不更新；关闭时，其余防作弊开关都会关闭
示例值：true
    └ check_cheat_software_punchboolean否是否校验疑似作弊软件打卡，不传入时默认关闭/不更新
示例值：true
    └ check_buddy_punchboolean否是否校验疑似他人代打卡，不传入时默认关闭/不更新
示例值：true
    └ check_simulate_wifi_punchboolean否是否校验疑似模拟 Wi-Fi 打卡，不传入时默认关闭/不更新（仅灰度租户有效，如需使用请联系技术支持）
示例值：true
    └ check_change_device_punchboolean否是否校验更换设备打卡，不传入时默认关闭/不更新
示例值：true
    └ allow_change_device_numint否同一考勤人员最多可绑定打卡设备数量上限，开启校验更换设备打卡时必填
示例值：1
数据校验规则：
- 取值范围：1 ～ 3
    └ suspected_cheat_handle_methodint否疑似作弊打卡时的处理方式，开启拦截疑似作弊打卡时必填
示例值：1
可选值有：
- 1: 使用人脸识别打卡 - 2: 仅记录疑似作弊信息
数据校验规则：
- 取值范围：1 ～ 2
  └ machinesmachine\[\]否考勤机列表
    └ machine_snstring是考勤机序列号
示例值："FS0701"
    └ machine_namestring是考勤机名称
示例值："创实 9 楼"
  └ gps_rangeint否GPS 打卡的有效范围
示例值：300
  └ locationslocation\[\]否地址列表（仅追加，不会覆盖之前的列表）
    └ location_namestring是地址名称
示例值："浙江省杭州市余杭区五常街道木桥头西溪八方城"
    └ location_typeint是地址类型 可选值有： * 1：GPS * 2：Wi-Fi * 8：IP
示例值：1
    └ latitudenumber(float)否地址纬度（需配合gps_range使用）
示例值：30.28994
    └ longitudenumber(float)否地址经度（需配合gps_range使用）
示例值：120.04509
    └ ssidstring否Wi-Fi 名称
示例值："TP-Link-af12ca"
    └ bssidstring否Wi-Fi 的 MAC 地址
示例值："08:00:20:0A:8C:6D"
    └ map_typeint否地图类型，1：高德， 2：谷歌
示例值：1
    └ addressstring否地址名称
示例值："北京市海淀区中航广场"
    └ ipstring否IP 地址
示例值："122.224.123.146"
    └ featurestring否额外信息，例如：运营商信息
示例值："中国电信"
    └ gps_rangeint否GPS 打卡的有效范围（历史无效字段）
示例值：300
  └ group_typeint是考勤类型
可选值有： * 1：固定班制 * 2：排班制 * 3：自由班制
示例值：1
  └ punch_day_shift_idsstring\[\]是班次 ID 列表。当考勤类型参数（group_type）设置为固定班制时，必须填够 7 个（从周一至周日）。当考勤类型参数（group_type）设置为排班制或自由班制时，请传入空数组。班次 ID 可以通过查询所有班次 和按名称查询班次 获取。休息日填0
示例值：["xxx","0","xxx","xxx","0","xxx","xxx","xxx"]
  └ free_punch_cfgfree_punch_cfg否配置自由班制
    └ free_start_timestring是自由班制打卡开始时间，格式为x点x分，注意这里小时如果小于10点，是不需要补零的
示例值："7:00"
    └ free_end_timestring是自由班制打卡结束时间，格式为x点x分，注意这里小时如果小于10点，是不需要补零的
示例值："18:00"
    └ punch_dayint是打卡的时间，为 7 位数字，每一位依次代表周一到周日，0 为不上班，1 为上班
示例值：1111100
    └ work_day_no_punch_as_lackboolean否工作日不打卡是否记为缺卡，默认为空
示例值：true
    └ work_hours_demandboolean否工作日出勤是否需满足时长要求，默认为空
示例值：false
    └ work_hoursint否每日工作时长（分钟），范围[0,1440]
示例值：480
  └ calendar_idint是国家日历 ID
可选值有： * 0：不根据国家日历排休 * 1：中国大陆 * 2：美国 * 3：日本 * 4：印度 * 5：新加坡
示例值：1
  └ need_punch_special_dayspunch_special_date_shift\[\]否必须打卡的特殊日期
    └ punch_dayint是打卡日期，格式为yyyyMMdd
示例值：20190101
    └ shift_idstring是班次 ID，可根据查询所有班次 和按名称查询班次 获得
示例值："6919668827865513935"
  └ no_need_punch_special_dayspunch_special_date_shift\[\]否无需打卡的特殊日期
    └ punch_dayint是打卡日期，格式为yyyyMMdd
示例值：20190101
    └ shift_idstring是班次 ID，可根据查询所有班次 和按名称查询班次 获得
示例值："6919668827865513935"
  └ work_day_no_punch_as_lackboolean否自由班制下工作日不打卡是否记为缺卡，默认为空
示例值：true
  └ effect_nowboolean否是否立即生效，默认 false
示例值：true
  └ remedy_period_typeint否补卡周期类型 * 1：按月 * 2：自定义
示例值：1
  └ remedy_period_custom_dateint否补卡自定义周期起始日期，范围0-28号
示例值：1
  └ punch_typeint否打卡类型。
位运算，即如需设置 1 和 2 两种打卡类型，则需要传入加和值 3。
可选值： * 1：GPS 打卡 * 2：Wi-Fi 打卡 * 4：考勤机打卡 * 8：IP 打卡
示例值：1
  └ rest_clockIn_need_approvalboolean否休息日打卡需审批。当设置 rest_clockIn_need_approval=true 时，休息日一天开始时间会被重置为 4:00。默认为空
示例值：true
  └ clockIn_need_photoboolean否每次打卡均需拍照，默认为空
示例值：true
  └ member_status_changemember_status_change否人员异动打卡设置
    └ onboarding_on_no_need_punchboolean否是否入职日上班无需打卡，默认为空
示例值：false
    └ onboarding_off_no_need_punchboolean否是否入职日下班无需打卡，默认为空
示例值：false
    └ offboarding_on_no_need_punchboolean否是否离职日上班无需打卡，默认为空
示例值：false
    └ offboarding_off_no_need_punchboolean否是否离职日下班无需打卡，默认为空
示例值：false
  └ leave_need_punchboolean否请假离岗或返岗是否需打卡，默认为空
示例值：false
  └ leave_need_punch_cfgleave_need_punch_cfg否请假离岗或返岗打卡规则，单位：分钟
    └ late_minutes_as_lateint否晚到超过多久记为迟到
示例值：0
    └ late_minutes_as_lackint否晚到超过多久记为缺卡
示例值：0
    └ early_minutes_as_earlyint否早走超过多久记为早退
示例值：0
    └ early_minutes_as_lackint否早走超过多久记为缺卡
示例值：0
    └ not_during_shiftboolean否班次中间请假，无需在离岗前或返岗后打卡（仅灰度租户有效，如需使用请联系技术支持）
示例值：false
  └ go_out_need_punchint否外出期间是否需打卡，默认为0。0:无需打卡，1:需在上下班时间打卡，2:需在离岗前或返岗后打卡
示例值：0
  └ go_out_need_punch_cfgleave_need_punch_cfg否外出期间打卡规则，单位：分钟
    └ late_minutes_as_lateint否晚到超过多久记为迟到
示例值：0
    └ late_minutes_as_lackint否晚到超过多久记为缺卡
示例值：0
    └ early_minutes_as_earlyint否早走超过多久记为早退
示例值：0
    └ early_minutes_as_lackint否早走超过多久记为缺卡
示例值：0
    └ not_during_shiftboolean否班次中间外出，无需在离岗前或返岗后打卡（仅灰度租户有效，如需使用请联系技术支持）
示例值：false
  └ travel_need_punchint否出差期间是否需打卡，默认为0。0:无需打卡，1:需在上了下班时间打卡，2:需在离岗前或返岗后打卡
示例值：0
  └ travel_need_punch_cfgleave_need_punch_cfg否出差期间打卡规则，单位：分钟
    └ late_minutes_as_lateint否晚到超过多久记为迟到
示例值：0
    └ late_minutes_as_lackint否晚到超过多久记为缺卡
示例值：0
    └ early_minutes_as_earlyint否早走超过多久记为早退
示例值：0
    └ early_minutes_as_lackint否早走超过多久记为缺卡
示例值：0
    └ not_during_shiftboolean否无需在出差离岗前或返岗后打卡（出差不生效）
示例值：false
  └ need_punch_memberspunch_member\[\]否需要打卡的人员集合（仅当不传「bind_dept_ids」和「bind_user_ids」时，才会使用该字段）
    └ rule_scope_typeint否圈人方式： * 0：无 * 1：全部 * 2：自定义
示例值：0
默认值：0
    └ scope_group_listscope_group否圈人规则列表
      └ scope_value_typeint否类型： * 1: 部门 * 2:人员 * 3: 国家地区 * 4: 员工类型 * 5: 工作城市 * 6: 职级 * 7: 序列 * 8: 职务（企业版） * 9: 工时制度（企业版） * 100: 自定义字段（企业版）
示例值：1
      └ operation_typeint否范围类型（是否包含） * 1: 包含 * 2: 不包含 * 3: 相等 * 4: 小于等于 * 5: 大于等于 * 6: 大于 * 7: 小于 * 8: 不相等
示例值：1
      └ rightscope_value\[\]否如果是人员/部门类型 不需要使用该字段
        └ keystring否标识Key
示例值："CH"
        └ namestring否名称
示例值："中国大陆"
      └ member_idsstring\[\]否部门/人员 ID 列表（根据 scope_value_type 判断为部门或人员）
示例值：["ec8ddg56"]
      └ custom_field_IDstring否企业版自定义字段唯一键 ID, 需要从飞书人事获取（暂不支持）
示例值："123213123"
      └ custom_field_obj_typestring否企业版自定义字段对象类型（暂不支持） * "Employment": 主数据对象，员工雇佣信息 * "Person": 主数据对象，个人
示例值："employment"
  └ no_need_punch_memberspunch_member\[\]否无需打卡的人员集合（仅当不传「bind_default_dept_ids」和「bind_default_user_ids」时，才会使用该字段）
    └ rule_scope_typeint否圈人方式： * 0：无 * 1：全部 * 2：自定义
示例值：0
默认值：0
    └ scope_group_listscope_group否圈人规则列表
      └ scope_value_typeint否类型： * 1: 部门 * 2:人员 * 3: 国家地区 * 4: 员工类型 * 5: 工作城市 * 6: 职级 * 7: 序列 * 8: 职务（企业版） * 9: 工时制度（企业版） * 100: 自定义字段（企业版）
示例值：1
      └ operation_typeint否范围类型（是否包含） * 1: 包含 * 2: 不包含 * 3: 相等 * 4: 小于等于 * 5: 大于等于 * 6: 大于 * 7: 小于 * 8: 不相等
示例值：1
      └ rightscope_value\[\]否如果是人员/部门类型 不需要使用该字段
        └ keystring否标识Key
示例值："CH"
        └ namestring否名称
示例值："中国大陆"
      └ member_idsstring\[\]否部门/人员 ID 列表（根据 scope_value_type 判断为部门或人员）
示例值：["ec8ddg56"]
      └ custom_field_IDstring否企业版自定义字段唯一键 ID, 需要从飞书人事获取（暂不支持）
示例值："123213123"
      └ custom_field_obj_typestring否企业版自定义字段对象类型（暂不支持） * "Employment": 主数据对象，员工雇佣信息 * "Person": 主数据对象，个人
示例值："employment"
  └ save_auto_changesboolean否是否允许保存有冲突人员的考勤组。如果 true，则冲突人员将被自动拉入到当前设置的考勤组中，并从原考勤组中移除；如果 false，则需手动调整冲突人员。默认为 false。
示例值：false
  └ org_change_auto_adjustboolean否当有新员工入职或人员异动，符合条件的人员是否自动加入考勤组。默认为空
示例值：false
  └ bind_default_dept_idsstring\[\]否参与无需打卡的部门 ID 列表（与「no_need_punch_members」同时使用时，以当前字段为准），对应dept_type
示例值：["od-fcb45c28a45311afd440b7869541fce8"]
  └ bind_default_user_idsstring\[\]否参与无需打卡的人员 ID 列表（与「no_need_punch_members」同时使用时，以当前字段为准），对应employee_type
示例值：["dd31248a"]
  └ overtime_clock_cfgovertime_clock_cfg否加班打卡规则
    └ allow_punch_approvalboolean否是否允许在非打卡时段申请打卡（仅灰度租户有效，如需使用请联系技术支持）
示例值：false
    └ need_clock_over_time_start_and_endboolean否加班开始和结束需打卡（仅灰度租户有效，如需使用请联系技术支持）
示例值：false
  └ new_calendar_idstring否节假日id，（如果考勤组使用了自定义节假日，请用此参数传入节假日id，可在假勤设置-节假日模块页面路径获取）
示例值："7302191700771358252"
  └ allow_apply_punchboolean否定位不准时是否允许申请打卡
示例值：true
  └ clock_in_abnormal_settingsClockInAbnormalSettings否异常卡豁免配置
    └ ignore_until_latest_clockoutboolean否在最晚下班打卡之前忽略异常卡（仅灰度租户有效，如需使用请联系技术支持）
示例值：false
operator_idstring否操作人uid，对应employee_type，如果您未操作考勤管理后台“API 接入”流程，则此字段为必填字段
示例值："dd31248a"

请求体示例 ​

json
{
    "group": {
        "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": [
            "52aa1fa1"
        ],
        "group_leader_ids": [
            "2bg4a9be"
        ],
        "sub_group_leader_ids": [
            "52aa1fa1"
        ],
        "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": false,
        "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_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": 1,
        "punch_day_shift_ids": [
            "xxx",
            "0",
            "xxx",
            "xxx",
            "0",
            "xxx",
            "xxx",
            "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,
        "effect_now": true,
        "remedy_period_type": 1,
        "remedy_period_custom_date": 1,
        "punch_type": 1,
        "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": "7302191700771358252",
        "allow_apply_punch": true,
        "clock_in_abnormal_settings": {
            "ignore_until_latest_clockout": false
        }
    },
    "operator_id": "dd31248a"
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ groupgroup考勤组信息
    └ group_idstring考勤组 ID，可用于按 ID 查询考勤组
    └ group_namestring考勤组名称
    └ time_zonestring时区
    └ bind_dept_idsstring\[\]绑定的部门 ID（与「need_punch_members」同时使用时，以当前字段为准）。对应dept_type
    └ except_dept_idsstring\[\]排除的部门 ID（该字段已下线）
    └ bind_user_idsstring\[\]绑定的用户 ID（与「need_punch_members」同时使用时，以当前字段为准），对应employee_type
    └ except_user_idsstring\[\]排除的用户 ID（该字段已下线）
    └ group_leader_idsstring\[\]考勤主负责人 ID 列表，必选字段（需至少拥有考勤组管理员权限），对应employee_type
    └ sub_group_leader_idsstring\[\]考勤子负责人 ID 列表，对应employee_type
    └ allow_out_punchboolean是否允许外勤打卡
    └ out_punch_need_approvalboolean外勤打卡需审批（需要允许外勤打卡才能设置生效）
    └ out_punch_need_post_approvalboolean外勤打卡需审批，先打卡后审批（需要允许外勤打卡才能设置生效）
    └ out_punch_need_remarkboolean外勤打卡需填写备注（需要允许外勤打卡才能设置生效）
    └ out_punch_need_photoboolean外勤打卡需拍照（需要允许外勤打卡才能设置生效）
    └ out_punch_allowed_hide_addrboolean外勤打卡允许员工隐藏详细地址（需要允许外勤打卡才能设置生效）
    └ out_punch_allowed_adjust_addrboolean外勤打卡允许微调地址（需要允许外勤打卡才能设置生效）
    └ adjust_rangeint微调范围，默认为 50 米
    └ allow_pc_punchboolean是否允许 PC 端打卡
    └ allow_remedyboolean是否限制补卡
    └ remedy_limitboolean是否限制补卡次数
    └ remedy_limit_countint补卡次数
    └ remedy_date_limitboolean是否限制补卡时间
    └ remedy_date_numint补卡时间，几天内补卡
    └ allow_remedy_type_lackboolean允许缺卡补卡（需要允许补卡才能设置生效）
    └ allow_remedy_type_lateboolean允许迟到补卡（需要允许补卡才能设置生效）
    └ allow_remedy_type_earlyboolean允许早退补卡（需要允许补卡才能设置生效）
    └ allow_remedy_type_normalboolean允许正常补卡（需要允许补卡才能设置生效）
    └ show_cumulative_timeboolean是否展示累计时长
    └ show_over_timeboolean是否展示加班时长
    └ hide_staff_punch_timeboolean是否隐藏员工打卡详情
    └ hide_clock_in_ruleboolean是否隐藏打卡规则（仅灰度租户有效，如需使用请联系技术支持）
    └ face_punchboolean是否开启人脸识别打卡
    └ face_punch_cfgint人脸识别打卡规则
可选值有： * 1：每次打卡均需人脸识别 * 2：疑似作弊打卡时需要人脸识别
    └ face_live_need_actionboolean人脸打卡规则， false：开启活体验证 true：0动作验证，仅在 face_punch_cfg = 1 时有效
    └ face_downgradeboolean人脸识别失败时是否允许普通拍照打卡
    └ replace_basic_picboolean人脸识别失败时是否允许替换基准图片
    └ anti_cheat_punch_configanti_cheat_config防作弊打卡配置
      └ intercept_suspected_cheat_punchboolean是否拦截疑似作弊打卡，默认关闭；关闭时，其余防作弊开关都为关闭
      └ check_cheat_software_punchboolean是否校验疑似作弊软件打卡
      └ check_buddy_punchboolean是否校验疑似他人代打卡
      └ check_simulate_wifi_punchboolean是否校验疑似模拟 Wi-Fi 打卡
      └ check_change_device_punchboolean是否校验更换设备打卡
      └ allow_change_device_numint同一考勤人员最多可绑定打卡设备数量上限，开启校验更换设备打卡时必填
      └ suspected_cheat_handle_methodint疑似作弊打卡时的处理方式，开启拦截疑似作弊打卡时必填
可选值有：
- 1: 使用人脸识别打卡 - 2: 仅记录疑似作弊信息
    └ machinesmachine\[\]考勤机列表
      └ machine_snstring考勤机序列号
      └ machine_namestring考勤机名称
    └ gps_rangeintGPS 打卡的有效范围（不建议使用）
    └ locationslocation\[\]地址列表（仅追加，不会覆盖之前的列表）
      └ location_idstring地址 ID
      └ location_namestring地址名称
      └ location_typeint地址类型
可选值有： * 1：GPS * 2：Wi-Fi * 8：IP
      └ latitudenumber(float)地址纬度
      └ longitudenumber(float)地址经度
      └ ssidstringWi-Fi 名称
      └ bssidstringWi-Fi 的 MAC 地址
      └ map_typeint地图类型，1：高德， 2：谷歌
      └ addressstring地址名称
      └ ipstringIP 地址
      └ featurestring额外信息，例如：运营商信息
      └ gps_rangeintGPS 打卡的有效范围
    └ group_typeint考勤类型
可选值有： * 0：固定班制 * 2：排班制 * 3：自由班制
    └ punch_day_shift_idsstring\[\]固定班制返回，可用于按 ID 查询班次
    └ free_punch_cfgfree_punch_cfg配置自由班制
      └ free_start_timestring自由班制打卡开始时间
      └ free_end_timestring自由班制打卡结束时间
      └ punch_dayint打卡的时间，为 7 位数字，每一位依次代表周一到周日，0 为不上班，1 为上班
      └ work_day_no_punch_as_lackboolean工作日不打卡是否记为缺卡
      └ work_hours_demandboolean工作日出勤是否需满足时长要求
      └ work_hoursint每日工作时长（分钟),范围[0,1440]
    └ calendar_idint国家日历 ID
可选值有： * 0：不根据国家日历排休 * 1：中国大陆 * 2：美国 * 3：日本 * 4：印度 * 5：新加坡
    └ need_punch_special_dayspunch_special_date_shift\[\]必须打卡的特殊日期
      └ punch_dayint打卡日期
      └ shift_idstring班次 ID，可用于按 ID 查询班次
    └ no_need_punch_special_dayspunch_special_date_shift\[\]无需打卡的特殊日期
      └ punch_dayint打卡日期
      └ shift_idstring班次 ID，可用于按 ID 查询班次
    └ work_day_no_punch_as_lackboolean自由班制下工作日不打卡是否记为缺卡
    └ effect_nowboolean是否立即生效，默认 false
    └ remedy_period_typeint补卡周期类型
    └ remedy_period_custom_dateint补卡自定义周期起始日期
    └ punch_typeint打卡类型。
位运算，即如果设置了 1 和 2 两种打卡类型，则对应的参数加和值为 3。
可选值： * 1：GPS 打卡 * 2：Wi-Fi 打卡 * 4：考勤机打卡 * 8：IP 打卡
    └ effect_timestring生效时间，精确到秒的时间戳
    └ fixshift_effect_timestring固定班次生效时间，精确到秒的时间戳
    └ member_effect_timestring参加考勤的人员、部门变动生效时间，精确到秒的时间戳
    └ rest_clockIn_need_approvalboolean休息日打卡需审批
    └ clockIn_need_photoboolean每次打卡均需拍照
    └ member_status_changemember_status_change人员异动打卡设置
      └ onboarding_on_no_need_punchboolean是否入职日上班无需打卡
      └ onboarding_off_no_need_punchboolean是否入职日下班无需打卡
      └ offboarding_on_no_need_punchboolean是否离职日上班无需打卡
      └ offboarding_off_no_need_punchboolean是否离职日下班无需打卡
    └ leave_need_punchboolean请假离岗或返岗是否需打卡
    └ leave_need_punch_cfgleave_need_punch_cfg请假离岗或返岗打卡规则，单位：分钟
      └ late_minutes_as_lateint晚到超过多久记为迟到
      └ late_minutes_as_lackint晚到超过多久记为缺卡
      └ early_minutes_as_earlyint早走超过多久记为早退
      └ early_minutes_as_lackint早走超过多久记为缺卡
      └ not_during_shiftboolean班次中间请假，无需在离岗前或返岗后打卡（仅灰度租户有效，如需使用请联系技术支持）
    └ go_out_need_punchint外出期间是否需打卡
    └ go_out_need_punch_cfgleave_need_punch_cfg外出期间打卡规则，单位：分钟
      └ late_minutes_as_lateint晚到超过多久记为迟到
      └ late_minutes_as_lackint晚到超过多久记为缺卡
      └ early_minutes_as_earlyint早走超过多久记为早退
      └ early_minutes_as_lackint早走超过多久记为缺卡
      └ not_during_shiftboolean班次中间外出，无需在离岗前或返岗后打卡（仅灰度租户有效，如需使用请联系技术支持）
    └ travel_need_punchint出差期间是否需打卡
    └ travel_need_punch_cfgleave_need_punch_cfg出差期间打卡规则，单位：分钟
      └ late_minutes_as_lateint晚到超过多久记为迟到
      └ late_minutes_as_lackint晚到超过多久记为缺卡
      └ early_minutes_as_earlyint早走超过多久记为早退
      └ early_minutes_as_lackint早走超过多久记为缺卡
      └ not_during_shiftboolean无需在出差离岗前或返岗后打卡（出差不生效）
    └ need_punch_memberspunch_member\[\]需要打卡的人员集合（仅当不传「bind_dept_ids」和「bind_user_ids」时，才会使用该字段）
      └ rule_scope_typeint圈人方式：0 无 1全部 2自定义
      └ scope_group_listscope_group圈人规则列表
        └ scope_value_typeint类型： * 1: 部门 * 2:人员 * 3: 国家地区 * 4: 员工类型 * 5: 工作城市 * 6: 职级 * 7: 序列 * 8: 职务（企业版） * 9: 工时制度（企业版） * 100: 自定义字段（企业版）
        └ operation_typeint范围类型（是否包含） * 1: 包含 * 2: 不包含 * 3: 相等 * 4: 小于等于 * 5: 大于等于 * 6: 大于 * 7: 小于 * 8: 不相等
        └ rightscope_value\[\]如果是人员/部门类型 不需要使用该字段
          └ keystring标识Key
          └ namestring名称
        └ member_idsstring\[\]部门/人员 ID 列表（根据 scope_value_type 判断为部门或人员）
        └ custom_field_IDstring企业版自定义字段唯一键 ID, 需要从飞书人事那边获取
        └ custom_field_obj_typestring企业版自定义字段对象类型 * "Employment": 主数据对象，员工雇佣信息 * "Person": 主数据对象，个人
    └ no_need_punch_memberspunch_member\[\]无需打卡的人员集合（仅当不传「bind_default_dept_ids」和「bind_default_user_ids」时，才会使用该字段）
      └ rule_scope_typeint圈人方式：0 无 1全部 2自定义
      └ scope_group_listscope_group圈人规则列表
        └ scope_value_typeint类型： * 1: 部门 * 2:人员 * 3: 国家地区 * 4: 员工类型 * 5: 工作城市 * 6: 职级 * 7: 序列 * 8: 职务（企业版） * 9: 工时制度（企业版） * 100: 自定义字段（企业版）
        └ operation_typeint范围类型（是否包含） * 1: 包含 * 2: 不包含 * 3: 相等 * 4: 小于等于 * 5: 大于等于 * 6: 大于 * 7: 小于 * 8: 不相等
        └ rightscope_value\[\]如果是人员/部门类型 不需要使用该字段
          └ keystring标识Key
          └ namestring名称
        └ member_idsstring\[\]部门/人员id列表（具体类型根据scope_value_type判断）
        └ custom_field_IDstring企业版自定义字段唯一键 ID, 需要从飞书人事那边获取
        └ custom_field_obj_typestring企业版自定义字段对象类型 * "Employment": 主数据对象，员工雇佣信息 * "Person": 主数据对象，个人
    └ save_auto_changesboolean是否允许保存有冲突人员的考勤组。如果 true，则冲突人员将被自动拉入到当前设置的考勤组中，并从原考勤组中移除；如果 false，则需手动调整冲突人员。默认为 false。
    └ org_change_auto_adjustboolean当有新员工入职或人员异动，符合条件的人员是否自动加入考勤组
    └ bind_default_dept_idsstring\[\]参与无需打卡的部门 ID 列表（与「no_need_punch_members」同时使用时，以当前字段为准），对应dept_type
    └ bind_default_user_idsstring\[\]参与无需打卡的人员 ID 列表（与「no_need_punch_members」同时使用时，以当前字段为准），对应employee_type
    └ overtime_clock_cfgovertime_clock_cfg加班打卡规则
      └ allow_punch_approvalboolean是否允许在非打卡时段申请打卡（仅灰度租户有效，如需使用请联系技术支持）
      └ need_clock_over_time_start_and_endboolean加班开始和结束需打卡（仅灰度租户有效，如需使用请联系技术支持）
    └ new_calendar_idstring节假日id，（如果考勤组使用了自定义节假日，请用此参数传入节假日id，可在假勤设置-节假日模块页面路径获取）
    └ allow_apply_punchboolean定位不准时是否允许申请打卡
    └ clock_in_abnormal_settingsClockInAbnormalSettings异常卡豁免配置
      └ ignore_until_latest_clockoutboolean在最晚下班打卡之前忽略异常卡（仅灰度租户有效，如需使用请联系技术支持）

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "group": {
            "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": [
                "52aa1fa1"
            ],
            "group_leader_ids": [
                "2bg4a9be"
            ],
            "sub_group_leader_ids": [
                "52aa1fa1"
            ],
            "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": false,
            "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",
                "0",
                "xxx",
                "xxx",
                "0",
                "xxx",
                "xxx",
                "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,
            "effect_now": true,
            "remedy_period_type": 0,
            "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": "7302191700771358252",
            "allow_apply_punch": true,
            "clock_in_abnormal_settings": {
                "ignore_until_latest_clockout": false
            }
        }
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
4001220001param is invalid入参校验失败，请根据具体返回的信息检查入参。例如“employee_type invalid”代表人员类型异常。如仍无法解决可联系 技术支持
4001220002tenant_id is empty请检查入参中的 tenant_access_token是否正确
4001220003user_id type is not employee_id or employee_noemployee_type只支持取值为 employee_id或者employee_no
4001220004param is invalid请参考实际返回的错误信息排查问题。例如“user_id is not exist or does not have permission”代表入参传入的用户id不存在或者没有权限。如仍无法解决可联系 技术支持
4001220005没有权限请前往考勤管理后台检查数据权限范围
4001220600通用错误信息通用错误信息包含多条，详细的错误信息以及处理建议可参见错误信息。
5001225000param is invalid请参考实际返回的错误信息排查问题。例如“internal server error”代表内部服务异常。如仍无法解决可联系 技术支持
4001227500param is invalid班次服务异常错误码，请参考实际返回的错误信息排查问题。例如“[BatchGetLarkIDByOpenID] not find user larkID”代表没有找到对应lark uid。如仍无法解决可联系 技术支持
4001227000param is invalid请参考实际返回的错误信息排查问题，如仍无法解决可联系 技术支持

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

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