EasyWeChat 企业微信 OA 接口实战:打卡数据与审批数据拉取全指南

原创2026-09-23 21:24:141,947 阅读
文章标签:后端小程序认证鉴权

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 展示的自动鉴权与错误判定机制,你可以将更多精力放在业务侧的数据清洗与呈现上。

登录后查看全文
easywechat