飞书开放平台 Server API 文档

主题

查询打卡结果 ​

获取企业内员工的实际打卡结果，包括： * 打卡任务列表 * 打卡记录id * 用户信息 * 考勤组ID * 班次 ID * 考勤记录 * 上班记录 * 下班记录 * 上班打卡结果 * 下班打卡结果 * 上班打卡结果补充 * 下班打卡结果补充 * 上班打卡时间 * 下班打卡时间 * 无效用户 ID 列表 * 没有权限用户ID列表

Tip: - 如果企业给一个员工设定的班次是上午 9 点和下午 6 点各打一次上下班卡，即使员工在这期间打了多次卡，该接口也只会返回 1 条记录。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/attendance/v1/user_tasks/query
HTTP MethodPOST
接口频率限制50 次/秒
支持的应用类型custom
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用attendance:task:readonly 导出打卡数据

请求头 ​

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

查询参数 ​

名称类型必填描述
employee_typestring是员工ID类型。如果没有后台管理权限，可使用通过手机号或邮箱获取用户 ID
示例值：employee_id
可选值有：
- employee_id: 员工 employee ID，即飞书管理后台 > 组织架构 > 成员与部门 > 成员详情中的用户 ID - employee_no: 员工工号，即飞书管理后台 > 组织架构 > 成员与部门 > 成员详情中的工号
ignore_invalid_usersboolean否是否忽略无效和没有权限的用户，对应employee_type。如果 true，则返回有效用户的信息，并告知无效和没有权限的用户信息；如果 false，且 user_ids 中存在无效或没有权限的用户，则返回错误
示例值：true
include_terminated_userboolean否由于新入职员工可以复用已离职员工的 employee_no/employee_id，对应employee_type。如果 true，则返回 employee_no/employee_id 对应的所有在职 + 离职员工的数据；如果 false，则只返回 employee_no/employee_id 对应的在职或最近一个离职员工的数据
示例值：true

请求体 ​

名称类型必填描述
user_idsstring\[\]是employee_no 或 employee_id 列表，对应employee_type，长度不超过 50
示例值：["abd754f7"]
check_date_fromint是查询的起始工作日，格式为yyyyMMdd
示例值：20190817
check_date_toint是查询的结束工作日，格式为yyyyMMdd
示例值：20190820
need_overtime_resultboolean否是否需要加班班段打卡结果；当need_overtime_result=true时，会返回加班班段，加班班段通过task_shift_type=1标识，加班班段上下班与正常班段相连时会出现共用record_id情况。例如：9-18为正常班次，18-19为加班班次，打卡结果中records 会出现两段，分别为9-18，18-19 且两段上下班record_id相同（check_in_record_id和check_out_record_id相同）。非相连加班班次正常分段返回。当need_overtime_result=false时，仅返回正常班段且task_shift_type=0。
示例值：true

请求体示例 ​

json
{
    "user_ids": [
        "abd754f7"
    ],
    "check_date_from": 20190817,
    "check_date_to": 20190820,
    "need_overtime_result": true
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ user_task_resultsuser_task\[\]打卡任务列表
    └ result_idstring打卡记录 ID
    └ user_idstring用户 ID，对应employee_type
    └ employee_namestring用户姓名
    └ dayint日期，格式为yyyyMMdd
    └ group_idstring考勤组 ID（特别说明：1代表未加入考勤组），可用于按 ID 查询考勤组
    └ shift_idstring班次 ID（特别说明：9代表默认班次），可用于按 ID 查询班次
    └ recordstask_result\[\]用户考勤记录
      └ check_in_record_idstring上班打卡记录 ID
      └ check_in_recorduser_flow上班打卡记录
        └ user_idstring用户 ID，对应employee_type
        └ creator_idstring记录创建者 ID，对应employee_type
        └ location_namestring打卡位置名称信息
        └ check_timestring打卡时间，精确到秒的时间戳
        └ commentstring打卡备注
        └ record_idstring考勤内部的打卡记录ID（导入时此参数无效）
        └ ssidstring打卡 Wi-Fi 的 SSID
        └ bssidstring打卡 Wi-Fi 的 MAC 地址
        └ is_fieldboolean是否为外勤打卡
        └ is_wifiboolean是否为 Wi-Fi 打卡
        └ typeint记录生成方式
可选值有：
- 0: 用户打卡 - 1: 管理员修改 - 2: 用户补卡 - 3: 系统自动生成 - 4: 下班免打卡 - 5: 考勤机 - 6: 极速打卡 - 7: 考勤开放平台导入
        └ photo_urlsstring\[\]打卡照片列表
        └ device_idstring打卡设备ID（只支持小程序打卡，导入时无效）
        └ check_resultstring打卡结果。目前仅返回 PendingApproval，表示待生效。如需获取上班打卡结果，请使用 check_in_result 参数。
可选值有：
- NoNeedCheck: 无需打卡 - SystemCheck: 系统打卡（已弃用） - Normal: 正常 - Early: 早退 - Late: 迟到 - SeriousLate: 严重迟到 - Lack: 缺卡 - Invalid: 无效 - None: 无状态 - Todo: 尚未打卡
        └ external_idstring用户导入的外部打卡记录ID
        └ idempotent_idstring唯一幂等键
      └ check_out_record_idstring下班打卡记录 ID
      └ check_out_recorduser_flow下班打卡记录
        └ user_idstring用户 ID，对应employee_type
        └ creator_idstring记录创建者 ID，对应employee_type
        └ location_namestring打卡位置名称信息
        └ check_timestring打卡时间，精确到秒的时间戳
        └ commentstring打卡备注
        └ record_idstring考勤内部的打卡记录ID（导入时此参数无效）
        └ ssidstring打卡 Wi-Fi 的 SSID
        └ bssidstring打卡 Wi-Fi 的 MAC 地址
        └ is_fieldboolean是否为外勤打卡
        └ is_wifiboolean是否为 Wi-Fi 打卡
        └ typeint记录生成方式
可选值有：
- 0: 用户打卡 - 1: 管理员修改 - 2: 用户补卡 - 3: 系统自动生成 - 4: 下班免打卡 - 5: 考勤机 - 6: 极速打卡 - 7: 考勤开放平台导入
        └ photo_urlsstring\[\]打卡照片列表
        └ device_idstring打卡设备ID（只支持小程序打卡，导入时无效）
        └ check_resultstring打卡结果。目前仅返回 PendingApproval，表示待生效。如需获取下班打卡结果，请使用 check_out_result 参数。
可选值有：
- NoNeedCheck: 无需打卡 - SystemCheck: 系统打卡（已弃用） - Normal: 正常 - Early: 早退 - Late: 迟到 - SeriousLate: 严重迟到 - Lack: 缺卡 - Invalid: 无效 - None: 无状态 - Todo: 尚未打卡
        └ external_idstring用户导入的外部打卡记录ID
        └ idempotent_idstring唯一幂等键
      └ check_in_resultstring上班打卡结果
可选值有：
- NoNeedCheck: 无需打卡 - SystemCheck: 系统打卡（已弃用） - Normal: 正常 - Early: 早退 - Late: 迟到 - Lack: 缺卡 - Todo: 未打卡
      └ check_out_resultstring下班打卡结果
可选值有：
- NoNeedCheck: 无需打卡 - SystemCheck: 系统打卡（已弃用） - Normal: 正常 - Early: 早退 - Late: 迟到 - Lack: 缺卡 - Todo: 未打卡
      └ check_in_result_supplementstring上班打卡结果补充
可选值有：
- None: 无 - ManagerModification: 管理员修改 - CardReplacement: 补卡通过 - ShiftChange: 换班 - Travel: 出差 - Leave: 请假 - GoOut: 外出 - CardReplacementApplication: 补卡申请中 - FieldPunch: 外勤打卡
      └ check_out_result_supplementstring下班打卡结果补充
可选值有：
- None: 无 - ManagerModification: 管理员修改 - CardReplacement: 补卡通过 - ShiftChange: 换班 - Travel: 出差 - Leave: 请假 - GoOut: 外出 - CardReplacementApplication: 补卡申请中 - FieldPunch: 外勤打卡
      └ check_in_shift_timestring上班打卡时间，秒级时间戳
      └ check_out_shift_timestring下班打卡时间，秒级时间戳
      └ task_shift_typeint班次类型，0正常，1加班班次
  └ invalid_user_idsstring\[\]无效用户 ID 列表，对应employee_type
  └ unauthorized_user_idsstring\[\]没有权限用户 ID 列表，对应employee_type

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "user_task_results": [
            {
                "result_id": "6709359313699356941",
                "user_id": "abd754f7",
                "employee_name": "张三",
                "day": 20190819,
                "group_id": "6737202939523236110",
                "shift_id": "6753520403404030215",
                "records": [
                    {
                        "check_in_record_id": "6709359313699356941",
                        "check_in_record": {
                            "user_id": "abd754f7",
                            "creator_id": "abd754f7",
                            "location_name": "西溪八方城",
                            "check_time": "1611476284",
                            "comment": "上班打卡",
                            "record_id": "6709359313699356941",
                            "ssid": "b0:b8:67:5c:1d:72",
                            "bssid": "b0:b8:67:5c:1d:72",
                            "is_field": true,
                            "is_wifi": true,
                            "type": 7,
                            "photo_urls": [
                                "https://time.clockin.biz/manage/download/6840389754748502021"
                            ],
                            "device_id": "99e0609ee053448596502691a81428654d7ded64c7bd85acd982d26b3636c37d",
                            "check_result": "Invalid",
                            "external_id": "record_123",
                            "idempotent_id": "****_***"
                        },
                        "check_out_record_id": "6709359313699356942",
                        "check_out_record": {
                            "user_id": "abd754f7",
                            "creator_id": "abd754f7",
                            "location_name": "西溪八方城",
                            "check_time": "1611476284",
                            "comment": "上班打卡",
                            "record_id": "6709359313699356941",
                            "ssid": "b0:b8:67:5c:1d:72",
                            "bssid": "b0:b8:67:5c:1d:72",
                            "is_field": true,
                            "is_wifi": true,
                            "type": 7,
                            "photo_urls": [
                                "https://time.clockin.biz/manage/download/6840389754748502021"
                            ],
                            "device_id": "99e0609ee053448596502691a81428654d7ded64c7bd85acd982d26b3636c37d",
                            "check_result": "Invalid",
                            "external_id": "record_123",
                            "idempotent_id": "****_***"
                        },
                        "check_in_result": "SystemCheck",
                        "check_out_result": "SystemCheck",
                        "check_in_result_supplement": "None",
                        "check_out_result_supplement": "None",
                        "check_in_shift_time": "1609722000",
                        "check_out_shift_time": "1609754400",
                        "task_shift_type": 0
                    }
                ]
            }
        ],
        "invalid_user_ids": [
            "abd754f7"
        ],
        "unauthorized_user_ids": [
            "abd754f7"
        ]
    }
}

错误码 ​

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

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

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