# 查询打卡结果
获取企业内员工的实际打卡结果，包括：
* 打卡任务列表
* 打卡记录id
* 用户信息
* 考勤组id
* 班次id
* 考勤记录
* 上班记录
* 下班记录
* 上班打卡结果
* 下班打卡结果
* 上班打卡结果补充
* 下班打卡结果补充
* 上班打卡时间
* 下班打卡时间
* 无效用户id列表
* 没有权限用户ID列表
**注意事项**：- 如果企业给一个员工设定的班次是上午 9 点和下午 6 点各打一次上下班卡，即使员工在这期间打了多次卡，该接口也只会返回 1 条记录。
- 如果要获取打卡的详细数据，如打卡位置等信息，可使用[查询打卡流水](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/attendance-v1/user_flow/get)或[批量查询打卡流水](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/attendance-v1/user_flow/query)的接口
## 请求
基本 |
---|---
HTTP URL | https://open.feishu.cn/open-apis/attendance/v1/user_tasks/query
HTTP Method | POST
接口频率限制 | [50 次/秒](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
支持的应用类型 | Custom App
权限要求
**调用该 API 所需的权限。开启其中任意一项权限即可调用** | 导出打卡数据(attendance:task:readonly)
### 请求头
名称 | 类型 | 必填 | 描述
---|---|---|---
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 | 是 | 员工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
- employee_no：员工工号，即[飞书管理后台](https://example.feishu.cn/admin/contacts/departmentanduser) > 组织架构 > 成员与部门 > 成员详情中的工号
ignore_invalid_users | boolean | 否 | 是否忽略无效和没有权限的用户，对应employee_type。如果 true，则返回有效用户的信息，并告知无效和没有权限的用户信息；如果 false，且 user_ids 中存在无效或没有权限的用户，则返回错误
**示例值**：true
include_terminated_user | boolean | 否 | 由于新入职员工可以复用已离职员工的 employee_no/employee_id，对应employee_type。如果 true，则返回 employee_no/employee_id 对应的所有在职 + 离职员工的数据；如果 false，则只返回 employee_no/employee_id 对应的在职或最近一个离职员工的数据
**示例值**：true
### 请求体
名称 | 类型 | 必填 | 描述
---|---|---|---
user_ids | string\[\] | 是 | employee_no 或 employee_id 列表，对应employee_type，长度不超过 50
**示例值**：["abd754f7"]
check_date_from | int | 是 | 查询的起始工作日，格式为yyyyMMdd
**示例值**：20190817
check_date_to | int | 是 | 查询的结束工作日，格式为yyyyMMdd
**示例值**：20190820
need_overtime_result | boolean | 否 | 是否需要加班班段打卡结果；当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
}
```
## 响应
### 响应体
名称 | 类型 | 描述
---|---|---
code | int | 错误码，非 0 表示失败
msg | string | 错误描述
data | \- | \-
user_task_results | user_task\[\] | 打卡任务列表
result_id | string | 打卡记录 ID
user_id | string | 用户 ID，对应employee_type
employee_name | string | 用户姓名
day | int | 日期，格式为yyyyMMdd
group_id | string | 考勤组 ID（特别说明：1代表未加入考勤组），可用于[按 ID 查询考勤组](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/attendance-v1/group/get)
shift_id | string | 班次 ID（特别说明：9代表默认班次），可用于[按 ID 查询班次](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/attendance-v1/shift/get)
records | task_result\[\] | 用户考勤记录
check_in_record_id | string | 上班打卡记录 ID
check_in_record | user_flow | 上班打卡记录
user_id | string | 用户 ID，对应employee_type
creator_id | string | 记录创建者 ID，对应employee_type
location_name | string | 打卡位置名称信息
check_time | string | 打卡时间，精确到秒的时间戳
comment | string | 打卡备注
record_id | string | 考勤内部的打卡记录ID（导入时此参数无效）
ssid | string | 打卡 Wi-Fi 的 SSID
bssid | string | 打卡 Wi-Fi 的 MAC 地址
is_field | boolean | 是否为外勤打卡
is_wifi | boolean | 是否为 Wi-Fi 打卡
type | int | 记录生成方式
**可选值有**：
- 0：用户打卡
- 1：管理员修改
- 2：用户补卡
- 3：系统自动生成
- 4：下班免打卡
- 5：考勤机
- 6：极速打卡
- 7：考勤开放平台导入
photo_urls | string\[\] | 打卡照片列表
device_id | string | 打卡设备ID（只支持小程序打卡，导入时无效）
check_result | string | 打卡结果。目前仅返回 `PendingApproval`，表示待生效。如需获取上班打卡结果，请使用 `check_in_result` 参数。
**可选值有**：
- NoNeedCheck：无需打卡
- SystemCheck：系统打卡（已弃用）
- Normal：正常
- Early：早退
- Late：迟到
- SeriousLate：严重迟到
- Lack：缺卡
- Invalid：无效
- None：无状态
- Todo：尚未打卡
external_id | string | 用户导入的外部打卡记录ID
idempotent_id | string | 唯一幂等键
check_out_record_id | string | 下班打卡记录 ID
check_out_record | user_flow | 下班打卡记录
user_id | string | 用户 ID，对应employee_type
creator_id | string | 记录创建者 ID，对应employee_type
location_name | string | 打卡位置名称信息
check_time | string | 打卡时间，精确到秒的时间戳
comment | string | 打卡备注
record_id | string | 考勤内部的打卡记录ID（导入时此参数无效）
ssid | string | 打卡 Wi-Fi 的 SSID
bssid | string | 打卡 Wi-Fi 的 MAC 地址
is_field | boolean | 是否为外勤打卡
is_wifi | boolean | 是否为 Wi-Fi 打卡
type | int | 记录生成方式
**可选值有**：
- 0：用户打卡
- 1：管理员修改
- 2：用户补卡
- 3：系统自动生成
- 4：下班免打卡
- 5：考勤机
- 6：极速打卡
- 7：考勤开放平台导入
photo_urls | string\[\] | 打卡照片列表
device_id | string | 打卡设备ID（只支持小程序打卡，导入时无效）
check_result | string | 打卡结果。目前仅返回 `PendingApproval`，表示待生效。如需获取下班打卡结果，请使用 `check_out_result` 参数。
**可选值有**：
- NoNeedCheck：无需打卡
- SystemCheck：系统打卡（已弃用）
- Normal：正常
- Early：早退
- Late：迟到
- SeriousLate：严重迟到
- Lack：缺卡
- Invalid：无效
- None：无状态
- Todo：尚未打卡
external_id | string | 用户导入的外部打卡记录ID
idempotent_id | string | 唯一幂等键
check_in_result | string | 上班打卡结果
**可选值有**：
- NoNeedCheck：无需打卡
- SystemCheck：系统打卡（已弃用）
- Normal：正常
- Early：早退
- Late：迟到
- Lack：缺卡
- Todo：未打卡
check_out_result | string | 下班打卡结果
**可选值有**：
- NoNeedCheck：无需打卡
- SystemCheck：系统打卡（已弃用）
- Normal：正常
- Early：早退
- Late：迟到
- Lack：缺卡
- Todo：未打卡
check_in_result_supplement | string | 上班打卡结果补充
**可选值有**：
- None：无
- ManagerModification：管理员修改
- CardReplacement：补卡通过
- ShiftChange：换班
- Travel：出差
- Leave：请假
- GoOut：外出
- CardReplacementApplication：补卡申请中
- FieldPunch：外勤打卡
check_out_result_supplement | string | 下班打卡结果补充
**可选值有**：
- None：无
- ManagerModification：管理员修改
- CardReplacement：补卡通过
- ShiftChange：换班
- Travel：出差
- Leave：请假
- GoOut：外出
- CardReplacementApplication：补卡申请中
- FieldPunch：外勤打卡
check_in_shift_time | string | 上班打卡时间，秒级时间戳
check_out_shift_time | string | 下班打卡时间，秒级时间戳
task_shift_type | int | 班次类型，0正常，1加班班次
invalid_user_ids | string\[\] | 无效用户 ID 列表，对应employee_type
unauthorized_user_ids | string\[\] | 没有权限用户 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状态码 | 错误码 | 描述 | 排查建议
---|---|---|---
400 | 1220001 | param is invalis | 入参校验失败，请根据具体返回的信息检查入参。例如“employee_type invalid”代表人员类型异常。如仍无法解决可联系 [技术支持](https://applink.feishu.cn/TLJpeNdW)
400 | 1220002 | tenant_id is empty | 请检查入参中的 tenant_access_token是否正确
400 | 1220004 | param is invalis | 请参考实际返回的错误信息排查问题。例如“user_id is not exist or does not have permission”代表入参传入的用户id不存在或者没有权限。如仍无法解决可联系 [技术支持](https://applink.feishu.cn/TLJpeNdW)
400 | 1220005 | 没有权限 | 请前往[考勤管理后台](https://oa.feishu.cn/attendance/manage/member/list)检查数据权限范围
500 | 1225000 | param is invalis | 请参考实际返回的错误信息排查问题。例如“internal server error”代表内部服务异常。如仍无法解决可联系 [技术支持](https://applink.feishu.cn/TLJpeNdW)
500 | 1226500 | 历史错误码，不再使用 | -
500 | 1227500 | param is invalis | 班次服务异常错误码，请参考实际返回的错误信息排查问题。例如“[BatchGetLarkIDByOpenID] not find user larkID”代表没有找到对应lark uid。如仍无法解决可联系 [技术支持](https://applink.feishu.cn/TLJpeNdW)
400 | 1220600 | 通用错误信息 | 通用错误信息包含多条，详细的错误信息以及处理建议可参见[错误信息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/attendance-v1/attendance-development-guidelines)。