EasyWeChat 企业微信 OA 接口实战:打卡数据与审批数据拉取全指南
EasyWeChat 企业微信 OA 接口实战:打卡数据与审批数据拉取全指南
本指南以 EasyWeChat(PHP 微信 SDK)4.x 文档中的企业微信 OA 模块为核心,系统讲解如何通过
Factory::work()初始化企业微信应用,并调用$app->oa->checkinRecords()与$app->oa->approvalRecords()两个高频 OA 接口,完成打卡记录与审批单数据的批量拉取。读完本文,你将掌握 OA 接口的完整调用姿势、参数语义、翻页与类型选择技巧,并能结合 SDK 源码理解其底层请求与鉴权机制。
一、前置准备:企业微信应用初始化
企业微信(WeCom)的使用方式与公众号一致,统一通过 \EasyWeChat\Factory::work($config) 初始化应用实例。OA 相关的两个接口(打卡数据、审批数据)均挂在初始化后的 $app->oa 上调用。
核心配置项如下(完整配置见 企业微信入门文档):
$config = [
'corp_id' => 'xxxxxxxxxxxxxxxxx',
'agent_id' => 100020, // 如果有 agent_id 则填写
'secret' => 'xxxxxxxxxx',
// 指定 API 调用返回结果的类型:array(default)/collection/object/raw/自定义类名
'response_type' => 'array',
'log' => [
'level' => 'debug',
'file' => __DIR__.'/wechat.log',
],
];
$app = Factory::work($config);
各参数说明:
| 配置项 | 必填 | 说明 |
|---|---|---|
corp_id |
是 | 企业 ID,在企业微信管理后台「我的企业」中获取 |
secret |
是 | 应用的密钥,在「应用管理」中为对应自建应用创建 |
agent_id |
否 | 自建应用的 AgentId,存在多个应用时用于区分,也用于 OA 网页授权等场景 |
response_type |
否 | 接口返回结果类型,默认 array,可选 collection/object/raw/自定义类名 |
log |
否 | 日志配置,level 指定级别、file 指定日志文件路径 |
初始化背后的源码结构
从仓库源码看,企业微信应用的入口是 src/Work/Application.php。Application 通过一组 InteractWith* Trait 组合了缓存(InteractWithCache)、配置(InteractWithConfig)、HTTP 客户端(InteractWithHttpClient)与服务器请求(InteractWithServerRequest)等能力:
getAccount()读取corp_id、secret、token、aes_key构建账户对象(src/Work/Application.php);getAccessToken()使用corpId与secret构建并缓存企业微信 Access Token(src/Work/Application.php);createClient()返回一个带 Access Token 自动注入与errcode失败判断的 HTTP 客户端(src/Work/Application.php):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());- 所有请求默认指向
https://qyapi.weixin.qq.com/,见getHttpClientDefaultOptions()(src/Work/Application.php)。
这意味着:你调用 $app->oa->xxx() 时,SDK 会自动完成 Access Token 的获取、缓存与注入;当企业微信返回 errcode 非 0 时,SDK 会按配置抛异常或返回错误数据,无需手动处理鉴权细节。
二、获取打卡数据:checkinRecords()
方法签名与参数语义
mixed checkinRecords(int $startTime, int $endTime, array $userList, int $type = 3)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
$startTime |
int | 是 | 起始时间,Unix 时间戳 |
$endTime |
int | 是 | 结束时间,Unix 时间戳 |
$userList |
array | 是 | 需要获取打卡记录的用户列表,如 ["james", "paul"] |
$type |
int | 否 | 打卡类型:1 上下班打卡;2 外出打卡;3 全部打卡,默认 3 |
$type说明:1:上下班打卡;2:外出打卡;3:全部打卡
三种典型调用
// 全部打卡数据
$app->oa->checkinRecords(1492617600, 1492790400, ["james", "paul"]);
// 获取上下班打卡
$app->oa->checkinRecords(1492617600, 1492790400, ["james", "paul"], 1);
// 获取外出打卡
$app->oa->checkinRecords(1492617600, 1492790400, ["james", "paul"], 2);
时间戳与数据窗口
示例中的 1492617600 与 1492790400 均为 Unix 时间戳(分别对应 2017-04-20 00:00 与 2017-04-22 00:00,北京时间),即一个两天的数据窗口。在实际业务中,建议用 strtotime() 或 Carbon 生成时间范围,例如:
$start = strtotime('2024-01-01 00:00:00');
$end = strtotime('2024-01-31 23:59:59');
$data = $app->oa->checkinRecords($start, $end, $userIds, 3);
返回结构要点
该接口对应企业微信官方接口 checkin/getcheckindata,返回的每条记录包含 userid、checkin_type(打卡类型)、checkin_time(打卡时间戳)、location_title、location_detail、notes 等字段,可用于考勤统计、迟到早退判定、外勤轨迹核验等场景。返回结构的具体字段以企业微信官方文档为准,SDK 负责将其按 response_type 配置转换为数组或对象。
三、获取审批数据:approvalRecords()
方法签名与参数语义
mixed approvalRecords(int $startTime, int $endTime, int $nextNumber = null)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
$startTime |
int | 是 | 起始时间,Unix 时间戳 |
$endTime |
int | 是 | 结束时间,Unix 时间戳 |
$nextNumber |
int | string | null | 否 | 第一个拉取的审批单号(sp_no),不填则从该时间段的第一个审批单开始拉取 |
$nextNumber:第一个拉取的审批单号,不填从该时间段的第一个审批单拉取
两种典型调用
// 从该时间段的第一条审批单开始拉取
$app->oa->approvalRecords(1492617600, 1492790400);
// 指定第一个拉取的审批单号,实现断点续拉
$app->oa->approvalRecords(1492617600, 1492790400, '201704240001');
关于 $nextNumber 的类型细节
注意一个文档层面的细节:方法签名中 $nextNumber 声明为 int,但实际使用时传入的是形如 '201704240001' 的审批单号字符串。这正是企业微信审批单号的真实形态(数字字符串)。PHP 的弱类型特性允许该调用正常工作,但如果你使用 PHPStan 等静态分析工具,可能会收到类型不一致的提示。从兼容性角度,建议仍按文档示例传入字符串形态的单号,并在返回的 sp_no 字段上原样使用。
翻页与增量拉取
该接口对应企业微信官方接口 corapprove/getapprovalinfo。当数据量较大时,返回结果会携带 sp_no 列表;把返回的最后一条 sp_no 作为下一次调用的 $nextNumber,即可实现审批单的分页/增量拉取,避免重复处理已同步的数据:
$page = null;
do {
$result = $app->oa->approvalRecords($start, $end, $page);
$spList = $result['sp_no'] ?? [];
foreach ($spList as $spNo) {
// 处理每一条审批单
}
$page = end($spList) ?: null; // 用最后一条单号继续翻页
} while ($spList);
next_spnum 等分页游标字段的具体命名以企业微信官方返回为准,落地时建议先打印一次完整返回结构再决定翻页字段。
四、OA 接口调用的实战要点
1. 权限与范围
- 打卡数据与审批数据均属于企业敏感数据,需要在企业微信管理后台为应用开启对应接口权限,并保证
secret对应的应用具有读取考勤、审批的权限范围; $userList传入的是成员的userid,需与通讯录模块获取到的userid保持一致(参见 通讯录)。
2. 时间窗口限制
企业微信对打卡、审批数据的拉取时间范围存在限制(通常为单次查询跨月受限)。大批量历史数据建议按天或按周切片循环拉取,例如:
for ($day = 1; $day <= 31; $day++) {
$start = mktime(0, 0, 0, 1, $day, 2024);
$end = mktime(23, 59, 59, 1, $day, 2024);
$app->oa->checkinRecords($start, $end, $userIds, 3);
}
3. 错误处理
SDK 的 HTTP 客户端以 errcode 是否为 0 作为请求成败判据(src/Work/Application.php)。当企业微信返回如 60011(无权限)、40098(参数错误)等错误码时,SDK 会按 http.throw 配置(默认 true)抛出异常,或返回含 errcode 的数组。建议对 OA 批量任务做异常捕获与重试:
try {
$data = $app->oa->checkinRecords($start, $end, $userIds, 3);
} catch (\EasyWeChat\Kernel\Exceptions\HttpException $e) {
// 记录日志、延迟重试或告警
}
4. 与日志、缓存联动
配置中的 log 项可将每次 OA 请求的耗时、URL 与返回摘要写入日志文件;Access Token 则由 SDK 内部缓存(默认 Symfony Cache,可参考 缓存定制),多个进程共享 Token 可显著降低接口频率限制风险。
5. 关于 oa 模块的现状说明
当前仓库的 src/Work 目录下以 Application、Server、AccessToken 等核心骨架为主,$app->oa 所对应的 OA 业务模块属于 4.x 文档描述的历史 API 面。如果你的项目基于 EasyWeChat 4.x 发行版使用,$app->oa->checkinRecords() 与 $app->oa->approvalRecords() 可直接照本文示例运行;若使用更高版本,建议先确认当前发行版中 OA 模块的方法命名与参数是否一致。无论版本如何,其底层请求链路(qyapi.weixin.qq.com 基础地址 + Access Token 自动注入 + errcode 失败判定)在本仓库源码中均可得到印证。
五、总结
| 能力 | 方法 | 关键参数 | 典型场景 |
|---|---|---|---|
| 打卡记录 | $app->oa->checkinRecords() |
时间范围、userid 列表、打卡类型 | 考勤统计、外勤核验 |
| 审批数据 | $app->oa->approvalRecords() |
时间范围、起始审批单号 | 审批流归档、同步 OA 系统 |
借助 EasyWeChat 的企业微信 OA 模块,你只需两三个方法调用即可打通企业微信的考勤与审批数据通道。把握三点即可稳定落地:正确初始化 Factory::work($config) 并开通接口权限、严格按 Unix 时间戳组织查询窗口、善用 $nextNumber 实现审批单的断点续拉。配合仓库中 src/Work/Application.php 展示的自动鉴权与错误判定机制,你可以将更多精力放在业务侧的数据清洗与呈现上。