钉钉企业内部应用 - 获取考勤打卡结果

本文是根据钉钉官方文档归纳所出，最后有 PHP 测试成功的 demo。

概述

钉钉登录是基于 OAuth2.0 协议标准构建的钉钉 OAuth2.0 授权登录系统。 在进行钉钉 OAuth2.0 授权登录接入之前，需要先创建一个应用，并获得相应的 AgentId 和 AppSecret。

OAuth2.0 授权说明

钉钉 OAuth2.0 授权登录让钉钉用户使用钉钉身份安全登录第三方应用或网站，在钉钉用户授权登录已接入钉钉 OAuth2.0 的第三方应用后，第三方可以获取到用户的接口调用凭证 sns_token，通过 sns_token 可以进行钉钉开放平台授权关系接口调用，从而实现获取钉钉用户基本开放信息和帮助用户实现基础开放功能等。

获取登录用户信息时序图：

钉钉 OAuth2.0 授权登录支持 authorization_code 模式，适用于拥有 server 端的应用授权。该模式整体流程为：

1. 第三方发起钉钉授权登录请求，钉钉用户允许授权第三方应用后，钉钉会拉起应用或重定向到第三方网站，并且带上授权临时票据 code 参数。
2. 通过 Code 调用 sns/getuserinfo_bycode 接口获取授权登录用户信息。

---

配置参数说明

Corpid 是企业在钉钉中的标识，每个企业拥有唯一的 Corpid

UserID 企业内每个员工都有唯一的 UserID，创建后不可修改。

Unionid 用户在当前钉钉开放平台账号范围内的唯一标识，同一个钉钉开放平台账号可以包含多个开放应用

AppKey/AppSecret

• Appkey 是 企业内部应用 应用的唯一身份标识
• AppSecret 是对应的调用密钥

---

具体实现过程

第一步: 准备工作 - 创建和配置应用并下载 SDK 包

根据自身情况进行配置，点我查看教程

---

第二步: 使用 SDK 调用接口

通过 SDK 调用考勤接口，获取考勤的打卡结果，服务端实现可分为以下步骤：

1. 下载 SDK 并导入到项目目录中，并将 appKey 和 appSecret 保存下来

   
   

2. 创建调用接口的文件，这里以 PHP 为例，创建名为 dd_attendance.php

   
   

3. 根据 appKey 和 appSecret 调用 获取企业内部应用的 access_token 接口获取 access_token

   
   

4. 根据 access_token 调用 获取打卡结果 接口获取考勤打卡的结果数据

请求参数说明

请求示例 （PHP SDK）

// 基本配置, 替换成自己的
$AppKey = '';

$AppSecret = '';

// 请求示例 （PHP SDK）
include "./dingding/TopSdk.php";
date_default_timezone_set('Asia/Shanghai');

$c = new DingTalkClient(DingTalkConstant::$CALL_TYPE_OAPI, DingTalkConstant::$METHOD_POST , DingTalkConstant::$FORMAT_JSON);

$req = new OapiAttendanceListRequest;

// 先获取 access_token - 开始 , access_token 有效期为 7200秒，有效期内重复获取会返回相同结果并自动续期，过期后再获取会返回新的 access_token, 文档链接: https://developers.dingtalk.com/document/app/obtain-orgapp-token
$access_token = '';
// 这里没有将 access_token 缓存, 实际操作时, 可将 access_token 进行缓存
$get_c = new DingTalkClient(DingTalkConstant::$CALL_TYPE_OAPI, DingTalkConstant::$METHOD_GET , DingTalkConstant::$FORMAT_JSON);

$access_token_request = new OapiGettokenRequest;

$access_token_request->setAppkey($AppKey);
$access_token_request->setAppsecret($AppSecret);

$access_token_response = $get_c->execute($access_token_request, $access_token, "https://oapi.dingtalk.com/gettoken");


if ($access_token_response->errcode != 0){
    // 错误
} else {
    $access_token = $access_token_response->access_token;
    file_put_contents('./data.log', 'access_token: ' . $access_token . '    ' . date("Y-m-d H:i:s", time())  . "\n" . "\n", FILE_APPEND);
}
// 先获取 access_token - 结束

// 设置起始工作日 - 起始工作日与结束工作日最多相隔 7 天
$req->setWorkDateFrom("2021-07-06 08:00:00");

// 设置结束工作日 - 起始工作日与结束工作日最多相隔 7 天
$req->setWorkDateTo("2021-07-07 12:00:00");

// 用户所在企业的 userid
$userIds = array('276933490129090108');
$req->setUserIdList($userIds);

// 页码
$req->setOffset("0");

// 每页条数
$req->setLimit("50");

// 获取
$responce_obj = $c->execute($req, $access_token, "https://oapi.dingtalk.com/attendance/list");

var_dump($responce_obj);

返回示例

{
	"errcode":0,
	"recordresult":[
		{
			"checkType":"OnDuty",
			"corpId":"ding2b15dc6154f4d112ffe93478753d9884",
			"locationResult":"Normal",
			"baseCheckTime":1625544000000,
			"groupId":781795238,
			"timeResult":"Normal",
			"userId":"276933490129090108",
			"recordId":67023885464,
			"workDate":1625500800000,
			"sourceType":"BOSS",
			"userCheckTime":1625544000000,
			"planId":216341548836,
			"id":160663847413
		},
		{
			"checkType":"OffDuty",
			"corpId":"ding2b15dc6154f4d112ffe93478753d9884",
			"locationResult":"Normal",
			"baseCheckTime":1625565600000,
			"groupId":781795238,
			"timeResult":"Normal",
			"userId":"276933490129090108",
			"recordId":67393055443,
			"workDate":1625500800000,
			"sourceType":"BOSS",
			"userCheckTime":1625565600000,
			"planId":216341548837,
			"id":161310850821
		},
		{
			"checkType":"OnDuty",
			"corpId":"ding2b15dc6154f4d112ffe93478753d9884",
			"locationResult":"Normal",
			"baseCheckTime":1625630400000,
			"groupId":781795238,
			"timeResult":"Normal",
			"userId":"276933490129090108",
			"recordId":67224193723,
			"workDate":1625587200000,
			"sourceType":"USER",
			"userCheckTime":1625628272000,
			"planId":217574178290,
			"id":160248303849
		}
	],
	"hasMore":false,
	"errmsg":"ok"
}

返回参数说明

下载 demo

我的 demo 从这里下载，点我