获取打卡结果

调用本接口，获取企业内员工的实际打卡结果。

例如，企业给一个员工设定的排班是上午9点和下午6点各打一次卡，即使员工在这期间打了多次，本接口也只会返回两条记录，包括上午的打卡结果和下午的打卡结果。

image

重要

  • 本接口不支持查询半年以前的数据。

  • 如果需要获取打卡详细数据，例如打卡位置，可以使用获取打卡详情接口。

  • 考勤信息同步可能会出现延迟，可稍后再试。

  • 如果当天用户有排班，但是没有打卡操作，本接口会返回当天排班的卡点信息，不会返回空。

权限

服务端API是以应用维度授权的，在调用接口前，确保已经为应用添加了接口权限。

应用类型

是否支持调用

权限申请方式

API Explorer调试

企业内部应用

是

查询企业考勤数据权限

调试

第三方企业应用

是

查询企业考勤数据权限

调试

第三方个人应用

否

—

—

基本信息

请求方式：POST

请求地址：https://oapi.dingtalk.com/attendance/list

Query参数

名称

类型

是否必填

示例值

描述

access_token

String

是

6d1bxxxx

调用该接口的应用凭证。

Body参数

名称

类型

是否必填

示例值

描述

workDateFrom

String

是

2020-11-07 08:00:00

查询考勤打卡记录的起始工作日。格式为yyyy-MM-dd HH:mm:ss，HH:mm:ss可以使用00:00:00，将返回此日期从0点到24点的结果。

例如，参数传"2021-12-01 10:00"，获取的是12月1日一整天的考勤结果。

重要

workDateFrom和workDateTo参数

相隔最多7天（包含7天）。

workDateTo

String

是

2020-11-11 08:00:00

查询考勤打卡记录的结束工作日。格式为“yyyy-MM-dd HH:mm:ss”，HH:mm:ss可以使用00:00:00，将返回此日期从0点到24点的结果。

例如，参数传"2021-12-01 19:00"，获取的是12月1日一整天的考勤结果。

重要

workDateFrom和workDateTo参数

相隔最多7天（包含7天）。

userIdList

String[]

是

["manager4220"]

员工在企业内的userId列表，最大值50。

重要

务必确保userId参数的正确性，否则本接口获取信息为空。

offset

Number

是

0

表示获取考勤数据的起始点。第一次传0，如果还有多余数据，下次获取传的offset值为之前的offset+limit，0、1、2...依次递增。

limit

Number

是

50

表示获取考勤数据的条数，最大值50。

isI18n

Boolean

否

true

是否为海外企业使用：

  • true：海外平台使用

  • false（默认）：国内平台使用

返回参数

名称

类型

示例值

描述

recordresult

Recordresult[]

打卡记录。

sourceType

String

USER

数据来源：

  • ATM：考勤机打卡（指纹/人脸打卡）

  • BEACON：IBeacon

  • DING_ATM：钉钉考勤机（考勤机蓝牙打卡）

  • USER：用户打卡

  • BOSS：老板改签

  • APPROVE：审批系统

  • SYSTEM：考勤系统

  • AUTO_CHECK：自动打卡

baseCheckTime

Date

1599378660000

计算迟到和早退，基准时间。

userCheckTime

Date

1599378681000

实际打卡时间, 用户打卡时间的毫秒数。

procInstId

String

59f77e82-6625-4a31-b434

关联的审批实例ID，当该字段非空时，表示打卡记录与请假、加班等审批有关。

approveId

Number

2376620852

关联的审批ID，当该字段非空时，表示打卡记录与请假、加班等审批有关。

locationResult

String

Normal

位置结果：

  • Normal：范围内

  • Outside：范围外

  • NotSigned：未打卡

timeResult

String

Normal

打卡结果：

  • Normal：正常

  • Early：早退

  • Late：迟到

  • SeriousLate：严重迟到

  • Absenteeism：旷工迟到

  • NotSigned：未打卡

checkType

String

OnDuty

考勤类型：

  • OnDuty：上班

  • OffDuty：下班

userId

String

manager4220

打卡人的userId。

workDate

Date

1599321600000

工作日。

recordId

Number

43002777448

打卡记录ID。

planId

Number

145342017988

排班ID。

groupId

Number

685935028

考勤组ID。

id

Number

101135139831

唯一标识ID。

hasMore

Boolean

false

分页返回参数，表示是否还有更多数据。

  • true：有

  • false：没有

errmsg

String

ok

返回码描述。

errcode

Number

0

返回码。

示例

请求示例（HTTP）

POST https://oapi.dingtalk.com/attendance/list?access_token=ACCESS_TOKEN

请求正文

{
        "workDateFrom":"2020-09-06 00:00:00",
        "offset":0,
        "userIdList":["manager"],
        "limit":10,
        "isI18n":false,
        "workDateTo":"2020-09-07 00:00:00"
}

请求示例（JAVA SDK）

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/attendance/list");
OapiAttendanceListRequest req = new OapiAttendanceListRequest();
req.setWorkDateFrom("2020-11-07 08:00:00");
req.setWorkDateTo("2020-11-11 08:00:00");
req.setUserIdList(Arrays.asList("manager"));
req.setOffset(0L);
req.setLimit(10L);
req.setIsI18n(true);
OapiAttendanceListResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());

返回示例

{
    "errcode": 0,
    "recordresult": [
        {
            "checkType": "OnDuty",
            "locationResult": "Normal",
            "baseCheckTime": 1599372300000,
            "groupId": 685935028,
            "timeResult": "Normal",
            "userId": "manager4220",
            "recordId": 42833709096,
            "workDate": 1599321600000,
            "sourceType": "APPROVE",
            "userCheckTime": 1599372300000,
            "planId": 145583519353,
            "id": 100068640553
        },
        {
            "checkType": "OffDuty",   
            "locationResult": "Normal",
            "baseCheckTime": 1599373560000,
            "groupId": 685935028,
            "timeResult": "Normal",
            "userId": "manager4220",
            "recordId": 43003136655,
            "workDate": 1599321600000,
            "sourceType": "USER",
            "userCheckTime": 1599373608000,
            "planId": 144623724178,
            "id": 100375228689
        }
    ],
    "hasMore": false,
    "errmsg": "ok"
}