钉钉开发文档

企业考勤排班详情

更新时间: 2019-2-15

企业考勤排班详情

在钉钉考勤应用中,设置考勤组规则后,会生成每天的排班信息,包括工作日、周末、节假日等。如果企业想查询某天的排班情况,可使用此接口查询某天的考勤排班全量信息。

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/topapi/attendance/listschedule?access_token=ACCESS_TOKEN
参数说明

名称 类型 是否必须 示例值 描述
workDate Date 必须 2016-03-09 11:11:11 排班时间,只取年月日部分
offset Number 可选 0 偏移位置,从0开始,后续传offset+size的值。当返回结果中的has_more为false时,表示没有多余的数据了。
size Number 可选 200 分页大小,最大200,默认值:200

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/attendance/listschedule");
OapiAttendanceListscheduleRequest request = new OapiAttendanceListscheduleRequest();
request.setWorkDate(new Date());
request.setOffset(0L);
request.setSize(100L);
OapiAttendanceListscheduleResponse execute = client.execute(request,accessToken);

返回结果

{
    "result":{
        "schedules":[
            {
                    "plan_id":1,
                    "check_type":"OnDuty",
                    "approve_id":1,
                    "userid":"0001",
                    "class_id":1,
                    "class_setting_id":1,
                    "plan_check_time":"2017-04-11 11:11:11",
                    "group_id":1
            }
        ],
        "has_more":false
    },
    "errmsg":"ok",
    "errcode":0
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
result
└ schedules 排班列表
└ plan_id 排班id
└ check_type 打卡类型,OnDuty表示上班打卡,OffDuty表示下班打卡
└ approve_id 审批id,结果集中没有的话表示没有审批单
└ userid userId
└ class_id 考勤班次id
└ class_setting_id 班次配置id,结果集中没有的话表示使用全局班次配置
└ plan_check_time 打卡时间
└ group_id 考勤组id
└ has_more 分页用,表示是否还有下一页

企业考勤组详情

在钉钉考勤应用中,考勤组是一类具有相同的班次、考勤位置等考勤规则的人或部门的组合,企业可根据实际业务设置多个考勤组。如果企业想获取企业的考勤组与企业业务系统对接,可使用此接口查询所有的考勤组详情信息。

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/topapi/attendance/getsimplegroups?access_token=ACCESS_TOKEN
参数说明

名称 类型 是否必须 示例值 描述
offset Number 可选 0 偏移位置,从0、1、2...依次递增,默认值:0
size Number 可选 10 分页大小,最大10,默认值:10

SDK请求示例(JAVA)

DefaultDingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/attendance/getsimplegroups");
OapiAttendanceGetsimplegroupsRequest request = new OapiAttendanceGetsimplegroupsRequest();
OapiAttendanceGetsimplegroupsResponse execute = client.execute(request,accessToken);

返回结果

{
    "errcode":0,
    "errmsg":"ok",
    "result":{
        "has_more":true,
        "groups":[
            {
                    "group_id":20015047,
                    "is_default":false,
                    "group_name":"固定排班",
                    "selected_class":[
                        {
                                "setting":{
                                    "class_setting_id":1,
                                    "rest_begin_time":{
                                        "check_time":"2017-04-11 11:11:11"
                                    },
                                    "permit_late_minutes":10,
                                    "work_time_minutes":-1,
                                    "rest_end_time":{
                                        "check_time":"2017-04-11 11:11:11"
                                    },
                                    "absenteeism_late_minutes":30,
                                    "serious_late_minutes":20,
                                    "is_off_duty_free_check":"Y"
                                },
                                "class_id":20008010,
                                "sections":[
                                    {
                                            "times":[
                                                {
                                                        "check_time":"2017-04-11 11:11:11",
                                                        "check_type":"OnDuty",
                                                        "across":0
                                                }
                                            ]
                                    }
                                ],
                                "class_name":"A"
                        }
                    ],
                    "type":"FIXED",
                    "member_count":1,
                    "default_class_id":111,
                    "work_day_list":"1",
                    "classes_list":"周一、二 班次A:09:00-18:00, 周六、周日 休息",
                    "manager_list":"1,2",
                    "dept_name_list":"部门1,部门2"

            }
        ]
    }
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
result
└ has_more 分页用,表示是否还有下一页
└ groups 考勤组列表
└ group_id 考勤组id
└ is_default 是否默认考勤组
└ group_name 考勤组名称
└ selected_class 考勤组对应的考勤班次列表
└ setting 考勤组班次配置
└ class_setting_id 考勤组班次id
└ rest_begin_time 休息开始时间,只有一个时间段的班次有
└ check_time 开始时间
└ permit_late_minutes 允许迟到时长,单位分钟
└ work_time_minutes 工作时长,单位分钟,-1表示关闭该功能
└ rest_end_time 休息结束时间,只有一个时间段的班次有
└ check_time 结束时间
└ absenteeism_late_minutes 旷工迟到时长,单位分钟
└ serious_late_minutes 严重迟到时长,单位分钟
└ is_off_duty_free_check Y表示下班不强制打卡,N表示下班强制打卡
└ class_id 考勤班次id
└ sections 班次打卡时间段
└ times 时间段列表
└ check_time 打卡时间
└ check_type 打卡类型枚举(Onduty和OffDuty)
└ across 打卡时间跨度
 class_name 考勤班次名称
 type 考勤类型,FIXED为固定排班,TURN为轮班排班,NONE为无班次
└ member_count 成员人数
└ default_class_id 默认班次id
└ work_day_list 固定班次的工作日班次
└ classes_list 一周的班次时间展示列表
└ manager_list 考勤组负责人
└ dept_name_list 关联的部门

获取打卡详情

该接口用于返回企业内员工的实际打卡记录。比如,企业给一个员工设定的排班是上午9点和下午6点各打一次卡,但是员工在这期间打了多次,该接口会把所有的打卡记录都返回。
如果只要获取打卡结果数据,不需要详情数据,可使用获取打卡结果接口。

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/attendance/listRecord?access_token=ACCESS_TOKEN
请求包结构体

{
    "userIds": ["001","002"],
    "checkDateFrom": "yyyy-MM-dd hh:mm:ss",
    "checkDateTo": "yyyy-MM-dd hh:mm:ss",
    "isI18n":"false"
}

参数说明

参数
参数类型
必须
说明
access_token
String
调用接口凭证
userIds
List
企业内的员工id列表,最多不能超过50个
checkDateFrom
String
查询考勤打卡记录的起始工作日。格式为“yyyy-MM-dd hh:mm:ss”。
checkDateTo
String
查询考勤打卡记录的结束工作日。格式为“yyyy-MM-dd hh:mm:ss”。注意,起始与结束工作日最多相隔7天
isI18n
String
是否为海外企业使用,
true:海外平台使用
false:国内平台使用,默认

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/attendance/listRecord");
OapiAttendanceListRecordRequest request = new OapiAttendanceListRecordRequest();
request.setCheckDateFrom("2018-05-01 00:00:00");
request.setCheckDateTo("2018-05-05 00:00:00");
request.setUserIds(Arrays.asList("123"));
OapiAttendanceListRecordResponse execute = client.execute(request,accessToken);

返回结果

{
  "errmsg": "ok",
  "recordresult": [
    {
      "gmtModified": 1492594486000,
      "isLegal": "N",
      "baseCheckTime": 1492568460000,
      "id": 933202551,
      "userAddress": "北京市朝阳区崔各庄镇阿里中心.望京A座阿里巴巴绿地中心",
      "userId": "manager7078",
      "checkType": "OnDuty",
      "timeResult": "Normal",
      "deviceId": "cb7ace07d52fe9be14f4d8bec5e1ba79",
      "corpId": "ding7536bfee6fb1fa5a35c2f4657eb6378f",
      "sourceType": "USER",
      "workDate": 1492531200000,
      "planCheckTime": 1492568497000,
      "gmtCreate": 1492594486000,
      "locationMethod": "MAP",
      "locationResult": "Outside",
      "userLongitude": 116.486888,
      "planId": 4550269081,
      "groupId": 121325603,
      "userAccuracy": 65,
      "userCheckTime": 1492568497000,
      "userLatitude": 39.999946,
      "procInstId": "cb992267-9b70"
    },
    {
      "gmtModified": 1492574948000,
      "isLegal": "N",
      "baseCheckTime": 1492568460000,
      "id": 991197412,
      "userAddress": "北京市朝阳区崔各庄镇阿里中心.望京A座阿里巴巴绿地中心",
      "userId": "manager7078",
      "checkType": "OnDuty",
      "timeResult": "Normal",
      "deviceId": "cb7ace07d52fe9be14f4d8bec5e1ba79",
      "corpId": "ding7536bfee6fb1fa5a35c2f4657eb6378f",
      "sourceType": "USER",
      "workDate": 1492531200000,
      "planCheckTime": 1492568497000,
      "gmtCreate": 1492574948000,
      "locationMethod": "MAP",
      "locationResult": "Outside",
      "userLongitude": 116.486888,
      "planId": 4556390053,
      "groupId": 121325603,
      "userAccuracy": 65,
      "userCheckTime": 1492568497000,
      "userLatitude": 39.999946,
      "procInstId": "cb992267-9b70"
    }
  ],
  "errcode": 0
}
参数
说明
errcode
返回码
errmsg
对返回码的文本描述内容
id
唯一标示ID
groupId
考勤组ID
planId
排班ID
workDate
工作日
userId
用户ID
checkType
考勤类型,
OnDuty:上班
OffDuty:下班
sourceType
数据来源,
ATM:考勤机;
BEACON:IBeacon;
DING_ATM:钉钉考勤机;
USER:用户打卡;
BOSS:老板改签;
APPROVE:审批系统;
SYSTEM:考勤系统;
AUTO_CHECK:自动打卡
timeResult
时间结果,
Normal:正常;
Early:早退;
Late:迟到;
SeriousLate:严重迟到;
Absenteeism:旷工迟到;
NotSigned:未打卡
locationResult
位置结果,
Normal:范围内
Outside:范围外,外勤打卡时为这个值
approveId
关联的审批id,当该字段非空时,表示打卡记录与请假、加班等审批有关
procInstId
关联的审批实例id,当该字段非空时,表示打卡记录与请假、加班等审批有关。可以与 获取单个审批数据配合使用
baseCheckTime
计算迟到和早退,基准时间;也可作为排班打卡时间
userCheckTime
实际打卡时间
classId
考勤班次id,没有的话表示该次打卡不在排班内
isLegal
是否合法,当timeResult和locationResult都为Normal时,该值为Y;否则为N
locationMethod
定位方法
deviceId
设备id
userAddress
用户打卡地址
userLongitude
用户打卡经度
userLatitude
用户打卡纬度
userAccuracy
用户打卡定位精度
userSsid
用户打卡wifi SSID
userMacAddr
用户打卡wifi Mac地址
planCheckTime
排班打卡时间
baseAddress
基准地址
baseLongitude
基准经度
baseLatitude
基准纬度
baseAccuracy
基准定位精度
baseSsid
基准wifi ssid
baseMacAddr
基准 Mac 地址
outsideRemark
打卡备注

获取打卡结果

该接口用于返回企业内员工的实际打卡结果。比如,企业给一个员工设定的排班是上午9点和下午6点各打一次卡,即使员工在这期间打了多次,该接口也只会返回两条记录,包括上午的打卡结果和下午的打卡结果。
如果要获取打卡详细数据,比如打卡位置,可使用获取打卡详情接口。

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/attendance/list?access_token=ACCESS_TOKEN
请求包结构体

{
    "workDateFrom": "yyyy-MM-dd HH:mm:ss",
    "workDateTo": "yyyy-MM-dd HH:mm:ss",
    "userIdList":["员工UserId列表"],    // 必填,与offset和limit配合使用
    "offset":0,    // 必填,第一次传0,如果还有多余数据,下次传之前的offset加上limit的值
    "limit":1,     // 必填,表示数据条数,最大不能超过50条
}

参数说明

参数
参数类型
必须
说明
access_token
String
调用接口凭证
workDateFrom
String
查询考勤打卡记录的起始工作日。格式为“yyyy-MM-dd HH:mm:ss”,HH:mm:ss可以使用00:00:00,具体查询的时候不会起作用,最后将返回此日期从0点到24点的结果
workDateTo
String
查询考勤打卡记录的结束工作日。格式为“yyyy-MM-dd HH:mm:ss”,HH:mm:ss可以使用00:00:00,具体查询的时候不会起作用,最后将返回此日期从0点到24点的结果。注意,起始与结束工作日最多相隔7天
userIdList
List
员工在企业内的UserID列表,企业用来唯一标识用户的字段。最多不能超过50个
offset
Long
表示获取考勤数据的起始点,第一次传0,如果还有多余数据,下次获取传的offset值为之前的offset+limit,0、1、2...依次递增
limit
Long
表示获取考勤数据的条数,最大不能超过50条
isI18n
String
是否为海外企业使用 true: 海外平台使用 false: 国内平台使用,默认

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/attendance/list");
OapiAttendanceListRequest request = new OapiAttendanceListRequest();
request.setWorkDateFrom("2018-05-01 00:00:00");
request.setWorkDateTo("2018-05-05 00:00:00");
request.setUserIdList(Arrays.asList("1226682231742708"));
request.setOffset(0L);
request.setLimit(1L);
OapiAttendanceListResponse response = client.execute(request,accessToken);

返回结果

{
  "errcode": 0,
  "errmsg": "ok",
  "hasMore": false,
  "recordresult": [
    {
      "baseCheckTime": 1463392800000,
      "checkType": "OffDuty",
      "corpId": "ding53a2fb0458ba9639",
      "groupId": 20451893,
      "id": 60714703,
      "locationResult": "Normal",
      "planId": 210071562,
      "recordId": 30068312,
      "timeResult": "Early",
      "userCheckTime": 1463392235000,
      "userId": "manager6699",
      "workDate": 1463328000000,
      "procInstId": "cb992267-9b70"
    },
    {
      "baseCheckTime": 1463360400000,
      "checkType": "OnDuty",
      "corpId": "ding53a2fb0458ba9639",
      "groupId": 20451893,
      "id": 60716532,
      "locationResult": "NotSigned",
      "planId": 210071561,
      "timeResult": "NotSigned",
      "userCheckTime": 1463360400000,
      "userId": "manager6699",
      "workDate": 1463328000000,
      "procInstId": "cb992267-9b70"
    }
  ]
}
参数
说明
errcode
返回码
errmsg
对返回码的文本描述内容
hasMore
分页返回参数,表示是否还有更多数据
id
唯一标示ID
groupId
考勤组ID
planId
排班ID
recordId
打卡记录ID
workDate
工作日
userId
用户ID
checkType
考勤类型
OnDuty:上班
OffDuty:下班
timeResult
时间结果
Normal:正常;
Early:早退;
Late:迟到;
SeriousLate:严重迟到;
Absenteeism:旷工迟到;
NotSigned:未打卡
locationResult
位置结果
Normal:范围内;
Outside:范围外;
NotSigned:未打卡
approveId
关联的审批id,当该字段非空时,表示打卡记录与请假、加班等审批有关
procInstId
关联的审批实例id,当该字段非空时,表示打卡记录与请假、加班等审批有关。可以与 获取单个审批数据配合使用
baseCheckTime
计算迟到和早退,基准时间
userCheckTime
实际打卡时间,  用户打卡时间的毫秒数
sourceType
数据来源
ATM:考勤机;
BEACON:IBeacon;
DING_ATM:钉钉考勤机;
USER:用户打卡;
BOSS:老板改签;
APPROVE:审批系统;
SYSTEM:考勤系统;
AUTO_CHECK:自动打卡

获取请假时长

该接口可以自动根据排班规则统计出每个员工的请假时长,进而与企业自有的请假/财务系统对接,进行工资统计,如果您的企业使用了钉钉考勤并希望依赖考勤系统自动计算员工请假时长,可选择使用此接口。

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/topapi/attendance/getleaveapproveduration?access_token=ACCESS_TOKEN
参数说明

名称 类型 是否必须 示例值 描述
userid String 必须 zhangsan 员工在企业内的UserID,企业用来唯一标识用户的字段
from_date Date 必须 2016-03-09 11:11:11 请假开始时间
to_date Date 必须 2016-03-10 11:11:11 请假结束时间

SDK请求示例(JAVA)

DefaultDingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/attendance/getleaveapproveduration");
OapiAttendanceGetleaveapprovedurationRequest request = new OapiAttendanceGetleaveapprovedurationRequest();
request.setFromDate(StringUtils.parseDateTime("2018-05-01 00:00:00"));
request.setToDate(StringUtils.parseDateTime("2018-05-05 00:00:00"));
request.setUserid("1226682231742708");
OapiAttendanceGetleaveapprovedurationResponse response = client.execute(request,accessToken);

返回结果

{
    "result":{
        "duration_in_minutes":0
    },
    "errcode":0,
    "errmsg":"ok"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
result
└ duration_in_minutes 请假时长(单位分钟)

查询请假状态

该接口用于查询指定企业下的指定用户在指定时间段内的请假状态

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/topapi/attendance/getleavestatus?access_token=ACCESS_TOKEN
参数说明

名称 类型 是否必须 示例值 描述
userid_list String 必须 123,121 待查询用户id列表,支持最多100个用户的批量查询
start_time Number 必须 1538323200000 开始时间 ,UNIX时间戳,支持最多180天的查询
end_time Number 必须 1538323200000 结束时间 ,UNIX时间戳,支持最多180天的查询时间
offset Number 必须 0 分页偏移,非负整数
size Number 必须 20 分页大小,正整数,最大20

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/attendance/getleavestatus");
OapiAttendanceGetleavestatusRequest req = new OapiAttendanceGetleavestatusRequest();
req.setUseridList("123,121");
req.setStartTime(1538323200000L);
req.setEndTime(1546358399000L);
req.setOffset(0L);
req.setSize(10L);
OapiAttendanceGetleavestatusResponse rsp = client.execute(req, accessToken);
System.out.println(rsp.getBody());

返回结果

{
    "errmsg":"OK",
    "errcode":0,
    "result":{
        "has_more": false,
        "leave_status":[
            {
                    "duration_unit":"percent_day",
                    "duration_percent":100,
                    "end_time":1538323200000,
                    "start_time":1538323200000,
                    "userid":"manager7580"
            }
        ]
    },
    "success":true
}
参数
说明
errcode
返回码
errmsg
对返回码的文本描述内容
result
└ has_more
是否有更多数据
└ leave_status
请假状态列表
└└ duration_unit
请假单位:“percent_day”表示天,“percent_hour”表示小时
└└ duration_percent
假期时长*100,例如用户请假时长为1天,该值就等于100
└└ end_time
请假结束时间,时间戳
└└ start_time
请假开始时间,时间戳
└└ userid
用户id

获取用户考勤组

在钉钉考勤应用中,考勤组是一类具有相同的班次、考勤位置等考勤规则的人或部门的组合,一个企业中的一个人只能属于一个考勤组。如果您的企业使用了钉钉考勤并希望获取员工的考勤组信息,可选择使用此接口。

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/topapi/attendance/getusergroup?access_token=ACCESS_TOKEN
参数说明

名称 类型 是否必须 示例值 描述
userid String 必须 zhangsan 员工在企业内的UserID,企业用来唯一标识用户的字段

SDK请求示例(JAVA)

DefaultDingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/attendance/getusergroup");
OapiAttendanceGetusergroupRequest request = new OapiAttendanceGetusergroupRequest();
request.setUserid("1226682231742708");
OapiAttendanceGetusergroupResponse response = client.execute(request,accessToken);

返回结果

{
    "result":{
        "name":"考勤组1",
        "group_id":123,
        "type":"TURN",
        "classes":[
            {
                    "class_id":456,
                    "name":"A班",
                    "sections":[
                        {
                                "times":[
                                    {
                                            "check_time":"1970-01-01 12:00:00",
                                            "check_type":"OnDuty",
                                            "across":0,
                                            "begin_min":30,
                                            "end_min":0
                                    }
                                ]
                        }
                    ],
                    "setting":{
                        "rest_begin_time":{
                            "across":0,
                            "begin_min":0,
                            "end_min":0,
                            "check_time":"1970-01-01 12:00:00",
                            "check_type":"OnDuty"
                        },
                        "rest_end_time":{
                            "across":0,
                            "begin_min":0,
                            "end_min":0,
                            "check_time":"1970-01-01 12:00:00",
                            "check_type":"OffDuty"
                        }
                    }
            }
        ]
    },
    "errcode":0,
    "errmsg":"ok"
}
参数
说明
errcode
返回码
errmsg
对返回码的文本描述内容
result
└ name
考勤组名称
└ group_id
考勤组id
└ type
考勤组类型
└ classes
考勤组中的班次列表
└ class_id
班次id
└ name
班次名称
└ sections
班次中上下班列表
└ times
班次中上下班详情列表
└ check_time
打卡时间
└ check_type
打卡类型
OnDuty:上班
OffDuty:下班
└ across
打卡时间跨几天
└ begin_min
允许的最早提前打卡时间,分钟为单位
└ end_min
允许的最晚延后打卡时间,分钟为单位
└ setting
班次配置
└ rest_begin_time
休息开始时间
└ across
across
└ begin_min
beginMin
└ end_min
endMin
└ check_time
开始时间
└ check_type
类型OnDuty:休息开始,OffDuty:休息结束
└ rest_end_time
休息结束时间
└ across
across
└ begin_min
beginMin
└ end_min
endMin
└ check_time
结束时间
└ check_type
类型
OnDuty:休息开始
OffDuty:休息结束
以上内容是否对您有帮助:
在文档使用中是否遇到以下问题(多选):
  • 内容错误
  • 更新不及时
  • 链接错误
  • 缺少代码/图片示例
  • 太简单/步骤待完善
手机号
更多建议
提交成功,感谢您的反馈!