EasyWeChat 企业微信 OA 模块开发指南:打卡与审批数据API详解
EasyWeChat 企业微信 OA 模块开发指南:打卡与审批数据API详解
通过本文,你将全面掌握使用 EasyWeChat(5.x)企业微信 SDK 中的 OA 模块来调用企业微信打卡与审批相关接口。本文将逐一拆解打卡规则获取、打卡记录拉取、排班管理、人脸录入以及审批数据拉取等核心 API 的使用方法,并深入底层配置与实现原理,确保每一段代码均可直接用于实战项目。
环境要求与安装
在使用 OA 模块前,请确保你的环境满足以下条件(详见 安装文档):
- PHP >= 7.4
- PHP cURL 扩展
- PHP OpenSSL 扩展
- PHP SimpleXML 扩展
- PHP fileinfo 拓展
通过 Composer 安装 EasyWeChat 5.x:
$ composer require overtrue/wechat:~5.0 -vvv
初始化企业微信应用
使用 OA 模块的第一步是初始化企业微信应用实例。配置文件中需提供 corp_id(企业 ID)和 secret(应用的凭证密钥),还可选填 agent_id、token、aes_key 等。一个典型的初始化代码如下:
$config = [
'corp_id' => 'xxxxxxxxxxxxxxxxx',
'secret' => 'xxxxxxxxxx',
//...
];
$app = Factory::work($config);
从源码中可见,Work 模块的 Config 类 会校验 corp_id、secret、token、aes_key 四项必填键。不过 OA 相关接口主要依赖 corp_id 和 secret 来获取 Access Token,token 与 aes_key 则在接收服务端推送消息时使用。
初始化后,$app 即代表一个完整的企业微信应用实例,可通过 $app->oa 动态访问 OA 服务(该访问方式基于 EasyWeChat 底层 HasAttributes Trait 的 __get 魔术方法实现,参见 HasAttributes)。
打卡模块 API
企业微信打卡功能是 OA 模块中最常用的部分。EasyWeChat SDK 封装了从规则查询、记录拉取到排班管理和人脸信息录入的全链路接口。
获取企业所有打卡规则
如需获取企业全体成员的打卡规则(包括全局规则配置),直接调用:
$app->oa->corpCheckinRules();
该方法无参数,底层对应企业微信接口 https://qyapi.weixin.qq.com/cgi-bin/checkin/getcorpcheckinoption。返回的规则数据包含打卡时间、地点、Wi-Fi 等配置信息。
获取员工的打卡规则
若要查询指定员工的个人打卡规则(包括其所属规则组、排班等个性化配置),需传入 Unix 时间戳和成员 UserID 列表:
$app->oa->checkinRules(int $datetime, array $userList);
参数说明:
$datetime:查询时间,Unix 时间戳(秒),用于获取该时间点生效的规则;$userList:要查询的成员 UserID 数组,例如["james", "paul"]。
该方法对应企业微信 cgi-bin/checkin/getcheckinoption 接口。
获取打卡记录数据
打卡记录查询是最核心的接口之一。$type 参数用于筛选打卡类型:
- 1:上下班打卡(正常打卡)
- 2:外出打卡(外勤打卡)
- 3:全部打卡(所有类型)
// 获取全部打卡数据(不传 type 时默认全部)
$app->oa->checkinRecords(1492617600, 1492790400, ["james", "paul"]);
// 仅获取上下班打卡记录
$app->oa->checkinRecords(1492617600, 1492790400, ["james", "paul"], 1);
// 仅获取外出打卡记录
$app->oa->checkinRecords(1492617600, 1492790400, ["james", "paul"], 2);
参数详解:
| 参数 | 类型 | 说明 |
|---|---|---|
$startTime |
int | 起始时间,Unix 时间戳(秒) |
$endTime |
int | 结束时间,Unix 时间戳(秒) |
$userList |
array | 要查询打卡记录的成员 UserID 列表 |
$type |
int | 打卡类型:1=上下班打卡,2=外出打卡,3=全部(默认) |
注意:startTime 和 endTime 的时间跨度不应超过 30 天。
获取打卡日报数据
查询打卡日报统计数据(如每日出勤时长、迟到早退等统计信息):
$app->oa->checkinDayData(int $startTime, int $endTime, array $userids);
参数与打卡记录类似,但返回的是按日聚合的统计结果。
获取打卡月报数据
查询打卡月报统计数据(月度汇总):
$app->oa->checkinMonthData(int $startTime, int $endTime, array $userids);
适合用于月度考勤报表的生成。
获取打卡人员排班信息
查询指定时间范围内特定成员的排班详情:
$app->oa->checkinSchedus(int $startTime, int $endTime, array $userids);
返回值包含每个成员的排班组 ID、打卡日期、班次 ID 等排班详情。
为打卡人员排班(设置排班)
除了查询排班,你还可以调用设置接口,为特定考勤组中的成员指定排班信息。该操作需要构造一个包含以下字段的关联数组:
$params = [
'groupid' => 226,
'items' => [
[
'userid' => 'james',
'day' => 5,
'schedule_id' => 234
]
],
'yearmonth' => 202012
];
$app->oa->setCheckinSchedus($params);
参数说明:
| 字段 | 类型 | 说明 |
|---|---|---|
groupid |
int | 打卡规则组 ID(从打卡规则中获取) |
items |
array | 排班项目列表,每一项包含 userid(成员ID)、day(当月第几日)、schedule_id(班次ID) |
yearmonth |
int | 排班所属的年月,格式为 YYYYMM,如 202012 代表 2020 年 12 月 |
录入打卡人员人脸信息
为了方便企业员工使用人脸识别打卡,SDK 提供了人脸信息录入接口:
$app->oa->addCheckinUserface(string $userid, string $userface);
$userid:成员 UserID;$userface:人脸图片的 URL 或 Base64 编码数据。
成功录入后,该成员即可通过人脸识别进行打卡。
获取审批数据
企业微信的审批功能同样通过 OA 模块调用。approvalRecords 方法用于拉取指定时间范围内的审批申请记录:
mixed approvalRecords(int $startTime, int $endTime, int $nextNumber = null)
$startTime/$endTime:Unix 时间戳,指定查询的起止时间;$nextNumber:可选,第一个拉取的审批单号。如果不传,则从该时间段内的第一个审批单开始拉取。
调用示例:
// 拉取 2017年4月20日 至 2017年4月21日 的所有审批记录
$app->oa->approvalRecords(1492617600, 1492790400);
// 指定从审批单号 '201704240001' 开始拉取
$app->oa->approvalRecords(1492617600, 1492790400, '201704240001');
此接口适用于审批数据的同步与归档。返回值包含审批单号、申请人、模板信息、审批流程状态等完整字段。
底层实现原理
从源码结构来看,Work 模块的 Application 类 是整个企业微信模块的入口,它通过 InteractWithClient、InteractWithHttpClient、InteractWithConfig 等 Trait 提供了 Access Token 自动注入、HTTP 客户端、配置管理等功能。
$app->oa 的动态属性访问机制,由 HasAttributes Trait 的 __get 魔术方法(参见 HasAttributes.php)支持,实际调用时会映射到具体的 API 请求方法。SDK 底层的 HTTP 客户端(AccessTokenAwareClient,详见 AccessTokenAwareClient.php)会自动为每个请求注入 Access Token,并具备自动重试和错误码判断能力。
所有 OA 接口最终都通过 createClient 方法创建的客户端发出请求,该方法在 Application.php 中定义:
public function createClient(): AccessTokenAwareClient
{
return (new AccessTokenAwareClient(
client: $this->getHttpClient(),
accessToken: $this->getAccessToken(),
failureJudge: fn (Response $response) => (bool) ($response->toArray()['errcode'] ?? 0),
throw: (bool) $this->config->get('http.throw', true),
))->setPresets($this->config->all());
}
从测试用例(如 ApplicationTest.php)可见,客户端被成功注入了一个 AccessTokenAwareClient 实例,验证了整个 Access Token 自动注入链路的完整性。
小结
本文围绕 EasyWeChat 5.x 企业微信 OA 模块,完整解析了打卡管理(企业规则、员工规则、记录、日报、月报、排班、人脸录入)和审批数据拉取的全部 API 方法。每一段代码示例均可在实际项目中直接复制使用。
使用 $app->oa 调用 OA 接口时,SDK 底层自动处理了 Access Token 的获取、刷新和注入,开发者只需关注业务参数的传递。若需深入了解 HTTP 客户端的重试机制和 Access Token 刷新策略,可进一步阅读 AccessTokenExpiredRetryStrategy.php 和 AccessTokenAwareClient.php 的源码实现。