EasyWeChat 企业微信 OA 模块开发指南:打卡与审批数据API详解

原创2026-09-24 17:18:111,917 阅读
文章标签:后端小程序认证鉴权

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 的源码实现。

登录后查看全文
easywechat