钉钉二次开发 考勤与薪资统计

结合企业实际需求，对接钉钉考勤，得到考勤统计报表，对接人事管理系统，自动得到薪资报表。

 

• 启用智能统计报表流程
• 接口调用
• 是否启用智能统计报表
• 获取报表列定义
• 获取报表列值
• 获取报表假期数据

考勤智能统计报表，是考勤为了满足企业个性化的统计需求，提供的一套智能可编程的报表系统。企业可以通过简单勾选或者高级编程模式来定制企业的统计规则，非常便捷地提供便于计算薪酬结果的统计数据。本文介绍如何使用统计报表API，获取企业的统计报表数据。

启用智能统计报表流程

开发者登录钉钉管理后台，点击工作台-考勤打卡-进入，打开考勤打卡后台。

点击月度汇总，查看是否开启智能统计报表：

如果右上角是“切换新版”，那么是未启用智能报表状态。需要点击切换新版，即可启用智能统计报表。

如果右上角是“返回旧版”，那么无需进行其他操作，当前已启用新版智能统计报表。

 

接口调用

是否启用智能统计报表

判断企业是否开启了考勤智能报表，如果企业未启用智能报表，无法调用统计报表其他的接口。

 

请求方式：POST（HTTPS）

请求地址：https://oapi.dingtalk.com/topapi/attendance/isopensmartreport?access_token=ACCESS_TOKEN

参数说明：无需入参

 

SDK请求示例（JAVA）：

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/attendance/isopensmartreport");
OapiAttendanceIsopensmartreportRequest req = new OapiAttendanceIsopensmartreportRequest();
OapiAttendanceIsopensmartreportResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());

 

返回结果：

{
    "result": {
        "smart_report": true
    },
    "errmsg": "ok",
    "errcode": 0
}

 

参数	类型	示例值	说明
errcode	Number	0	返回码。0表示成功，其他表示失败
errmsg	String	ok	对返回码的文本描述内容
result
└smart_report	boolen	true	true：开启，false：未开启

 

获取报表列定义

获取企业智能考勤报表中的列信息，通过获取列信息中的id值，可以根据列的id查询考勤智能报表中该列的统计数据，企业可以自主选择需要哪些列值来参与薪酬的计算。

注意：如果是获取假期相关字段信息，不返回id。如果希望获取假期相关信息，请调用本文-“获取报表假期数据”接口。

 

请求方式：POST（HTTPS）

请求地址：https://oapi.dingtalk.com/topapi/attendance/getattcolumns?access_token=ACCESS_TOKEN

参数说明：无需入参

SDK请求示例（JAVA）：

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/attendance/getattcolumns");
OapiAttendanceGetattcolumnsRequest req = new OapiAttendanceGetattcolumnsRequest();
OapiAttendanceGetattcolumnsResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());

 

返回结果：

{
    "errmsg": "ok",
    "errcode": 0,
    "result": {
        "columns": [{
            "id": 123,
            "name": "工时"
        }]
    }
}

 

参数	类型	示例值	说明
errcode	Number	0	返回码。0表示成功，其他表示失败
errmsg	String	ok	对返回码的文本描述内容
result
└columns
└└id	Number	123	列id
└└name	String	工时	列名称

 

获取报表列值

获取钉钉智能考勤报表的列值数据，其中包含了一定时间段内报表某些列的所有数据，以及相关的列信息，企业可以基于该接口的返回值计算员工薪酬。

 

注意：不支持获取离职人员的考勤信息，离职人员的考勤数据可以在OA管理后台查询。

​

请求方式：POST（HTTPS）

请求地址：https://oapi.dingtalk.com/topapi/attendance/getcolumnval?access_token=ACCESS_TOKEN

参数说明：

参数	类型	必须	示例值	说明
userid	String	是	zhangsan	员工id
column_id_list	String	是	1,2,3	报表列id列表，多个用英文逗号分隔，最大长度20
from_date	Date	是	2018-07-11 12:12:12	开始时间
to_date	Date	是	2018-07-12 12:12:12	结束时间，结束时间减去开始时间必须在31天以内

 

SDK请求示例（JAVA）：

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/attendance/getcolumnval");
OapiAttendanceGetcolumnvalRequest req = new OapiAttendanceGetcolumnvalRequest();
req.setUserid("zhangsan");
req.setColumnIdList("1,2,3");
req.setFromDate(StringUtils.parseDateTime("2018-07-11 12:12:12"));
req.setToDate(StringUtils.parseDateTime("2018-07-12 12:12:12"));
OapiAttendanceGetcolumnvalResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());

 

返回结果：

{
    "errmsg": "ok",
    "errcode": 0,
    "result": {
        "column_vals": [{
            "column_vals": [{
                "date": "2019-07-11",
                "value": "1.0"
            }],
            "column_vo": {
                "id": 123
            },
            "fixed_value": "0"
        }]
    }
}

 

参数	类型	示例值	说明
errcode	Number	0	返回码。0表示成功，其他表示失败
errmsg	String	ok	对返回码的文本描述内容
result
└column_vals
└└column_vals
└└└date	String	2019-08-15	日期
└└└value	String	1.0	每天的值
└└column_vo
└└└id	Number	123	报表列id
└└fixed_value	String	2.0	固定值，某些报表列是固定列值的，那么仅会在这个字段返回，不会在column_vals中返回

 

获取报表假期数据

根据假期名称和用户id获取钉钉智能考勤报表的假期数据，其中包含了一定时间段内报表假期列的所有数据，由于假期列是一个动态列，因此需要根据假期名称获取数据。

 

请求方式：POST（HTTPS）

请求地址：https://oapi.dingtalk.com/topapi/attendance/getleavetimebynames?access_token=ACCESS_TOKEN

参数说明：

参数	类型	必须	示例值	说明
userid	String	是	zhangsan	员工id
leave_names	String	是	年假	假期名称，多个用英文逗号分隔，最大长度20
from_date	Date	是	2018-07-11 12:12:12	开始时间
to_date	Date	是	2018-07-12 12:12:12	结束时间，结束时间减去开始时间必须在31天以内

 

SDK请求示例（JAVA）

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/attendance/getleavetimebynames");
OapiAttendanceGetleavetimebynamesRequest req = new OapiAttendanceGetleavetimebynamesRequest();
req.setUserid("zhangsan");
req.setLeaveNames("年假");
req.setFromDate(StringUtils.parseDateTime("2018-07-11 12:12:12"));
req.setToDate(StringUtils.parseDateTime("2018-07-12 12:12:12"));
OapiAttendanceGetleavetimebynamesResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());

 

返回结果

{
    "result": {
        "columns": [{
            "columnvo": {
                "name": "年假",
                "id": 1
            },
            "columnvals": [{
                "value": "1.0",
                "date": "2018-08-09"
            }]
        }]
    },
    "errcode": 0,
    "errmsg": "ok"
}

 

参数	类型	示例值	说明
errcode	Number	0	返回码。0表示成功，其他表示失败
errmsg	String	ok	对返回码的文本描述内容
result
└columns
└└columnvals
└└└date	String	2018-08-09	日期
└└└value	String	1.0	每天的值
└└columnvo
└└└id	Number	123	报表列id
└└└name	String	年假	假期类型