WxJava 企业微信流程审批(OA 审批)开发实战指南:从提交申请到模板管理的完整 API 使用

原创2026-10-13 13:58:531,917 阅读
文章标签:后端

WxJava 企业微信流程审批(OA 审批)开发实战指南:从提交申请到模板管理的完整 API 使用

导读:企业微信的流程审批(传统 OA 审批 + 审批流程引擎)是企业内部各类申请单(请假、报销、用章、出差等)自动化的核心能力。本文基于 WxJava 仓库中的 APPROVAL_WORKFLOW_GUIDE.md 及 weixin-java-cp 模块源码,系统讲解提交审批申请、批量拉取审批单号、查询审批详情、审批流程引擎、审批模板管理、第三方应用与多账号支持等全部已实现能力。读完本文,你将能够直接使用 WxCpOaService / WxCpOaAgentService / WxCpTpOAService 三套接口完成企业微信审批业务从提交到回执的全链路开发。

一、功能总览:SDK 已完整实现的审批能力

WxJava 在 weixin-java-cp 模块中对企业微信流程审批提供了全面支持,覆盖“传统 OA 审批”和“审批流程引擎”两条技术路线。根据指南文档与 WxCpOaService.java 接口定义,已实现功能清单如下:

功能 企业微信接口 SDK 方法 实现类
提交审批申请 /cgi-bin/oa/applyevent WxCpOaService.apply(WxCpOaApplyEventRequest) WxCpOaServiceImpl.java
获取审批申请详情 /cgi-bin/oa/getapprovaldetail WxCpOaService.getApprovalDetail(String spNo) WxCpOaServiceImpl.java
批量获取审批单号 /cgi-bin/oa/getapprovalinfo WxCpOaService.getApprovalInfo(...)(新旧游标两套重载) WxCpOaServiceImpl.java
审批流程引擎(查询审批当前状态) /cgi-bin/corp/getopenapprovaldata WxCpOaAgentService.getOpenApprovalData(String thirdNo) WxCpOaAgentServiceImpl.java
创建审批模板 /cgi-bin/oa/approval/create_template WxCpOaService.createOaApprovalTemplate(WxCpOaApprovalTemplate) WxCpOaServiceImpl.java
更新审批模板 /cgi-bin/oa/approval/update_template WxCpOaService.updateOaApprovalTemplate(WxCpOaApprovalTemplate) WxCpOaServiceImpl.java
获取审批模板详情 /cgi-bin/oa/gettemplatedetail WxCpOaService.getTemplateDetail(String templateId) WxCpOaServiceImpl.java

以上接口路径常量统一维护在 WxCpApiPathConsts.java(如 APPLY_EVENT、GET_APPROVAL_INFO、GET_APPROVAL_DETAIL、GET_OPEN_APPROVAL_DATA、CREATE_TEMPLATE、UPDATE_TEMPLATE、GET_TEMPLATE_DETAIL),由 mainService.getWxCpConfigStorage().getApiUrl(...) 拼接 access_token 后统一走 POST 请求。

二、核心数据模型:如何构造一个审批申请

审批业务的数据核心是 WxCpOaApplyEventRequest.java,它对应“提交审批申请”接口的请求体。所有字段均使用 @SerializedName 映射到企业微信 JSON 字段,并通过链式调用(@Accessors(chain = true))方便构建。

2.1 请求字段说明

字段 对应 JSON 字段 说明
creatorUserId creator_userid 申请人 userid,此审批申请将以此员工身份提交,申请人需在应用可见范围内
templateId template_id 模板 id。可在“获取审批申请详情”、“审批状态变化回调通知”中获得,也可在审批模板的模板编辑页面链接中获得。暂不支持通过接口提交「打卡补卡」「调班」模板审批单
useTemplateApprover use_template_approver 审批人模式:0-通过接口指定审批人、抄送人(此时 approver、notifyer 等参数可用);1-使用此模板在管理后台设置的审批流程,支持条件审批。默认为 0
chooseDepartment choose_department 提单者提单部门 id,不填默认为主部门
process process 审批流程信息(新版流程列表),支持单人审批、多人会签、多人或签,可能有多个审批节点,仅 use_template_approver 为 0 时生效
approvers approver 审批流程信息(旧版),同上仅 use_template_approver 为 0 时生效
notifiers notifyer 抄送人节点 userid 列表,仅 use_template_approver 为 0 时生效
notifyType notify_type 抄送方式:1-提单时抄送(默认值);2-单据通过后抄送;3-提单和单据通过后抄送
applyData apply_data 审批申请数据,可定义审批申请中各个控件的值,其中必填项必须有值,选填项可为空
summaryList summary_list 摘要信息,用于显示在审批通知卡片、审批列表的摘要信息,最多 3 行

2.2 新版流程(process)与旧版审批人(approver)

从源码结构看,SDK 同时支持新旧两套审批流程表达方式,以兼容不同版本的企业微信接口:

  • 旧版 Approver(WxCpOaApplyEventRequest.java):包含 attr(节点审批方式:1-或签;2-会签,仅在节点为多人审批时有效)和 userIds(userid,审批节点审批人列表)。
  • 新版 Process(WxCpOaApplyEventRequest.java):由 ProcessNode 节点列表组成,每个节点支持:
    • type:节点类型,1-审批人,2-抄送人,3-抄送人;
    • apvRel:多人审批方式,1-全签,2-或签,3-依次审批;
    • userIds:节点审批人 userid 列表。

2.3 申请数据控件:ApplyDataContent 与 ContentValue

申请单内容由 applyData.contents 中的 ApplyDataContent.java 列表表达,每个控件包含:

  • control:控件类型,支持 Text-文本、Textarea-多行文本、Number-数字、Money-金额、Date-日期/日期+时间、Selector-单选/多选、Contact-成员/部门、Tips-说明文字、File-附件、Table-明细;
  • id:控件唯一 id,可通过“获取审批模板详情”接口获得;
  • value:控件值,不同控件类型对应 ContentValue.java 中的不同赋值参数,例如 text(文本)、newNumber(数字)、newMoney(金额)、date、selector、members、departments、files、children(明细表)等。

三、提交审批申请:apply 实战

3.1 完整示例

以下示例整合自仓库演示代码 WxCpApprovalWorkflowDemo.java,构造一个同时包含文本、数字、金额三种控件的审批申请:

// 构建审批申请请求
WxCpOaApplyEventRequest request = new WxCpOaApplyEventRequest()
    .setCreatorUserId("creator_user_id")          // 申请人userid
    .setTemplateId("3Tka1eD6v6JfzhDMqPd3aMkFdxqtJMc2ZRioUBGCNS") // 模板id
    .setUseTemplateApprover(0)                    // 0=接口指定审批人
    .setApprovers(Arrays.asList(
        new WxCpOaApplyEventRequest.Approver()
            .setAttr(2)                           // 节点审批方式:2=会签
            .setUserIds(new String[]{"approver1", "approver2"})
    ))
    .setNotifiers(new String[]{"notifier1", "notifier2"}) // 抄送人
    .setNotifyType(1)                             // 抄送方式:1=提单时抄送
    .setApplyData(new WxCpOaApplyEventRequest.ApplyData()
        .setContents(Arrays.asList(
            // 文本控件
            new ApplyDataContent()
                .setControl("Text")
                .setId("Text-1234567890")
                .setValue(new ContentValue().setText("这是一个审批申请的文本内容")),
            // 数字控件
            new ApplyDataContent()
                .setControl("Number")
                .setId("Number-1234567890")
                .setValue(new ContentValue().setNewNumber("1000")),
            // 金额控件
            new ApplyDataContent()
                .setControl("Money")
                .setId("Money-1234567890")
                .setValue(new ContentValue().setNewMoney("10000"))
        ))
    );

// 提交审批申请,返回审批单号
String spNo = wxCpService.getOaService().apply(request);
System.out.println("审批申请提交成功,审批单号: " + spNo);

3.2 底层实现解析

从 WxCpOaServiceImpl.java 可以看到 apply 的实现非常直接:将请求对象序列化为 JSON 后 POST 到 APPLY_EVENT 路径,再从响应中解析出 sp_no 字段返回。这意味着:

  • 返回值为审批单号(sp_no)字符串,它是后续查询详情、追踪状态的唯一凭证,业务侧应持久化保存;
  • 请求体序列化使用 WxCpGsonBuilder,与 SDK 其他模块保持一致的 Gson 序列化风格;
  • 一旦 errcode 非 0,SDK 会在 post 调用层抛出 WxErrorException,因此调用方无需手动解析错误码。

四、查询审批:批量拉取单号与查询详情

4.1 批量获取审批单号:getApprovalInfo

getApprovalInfo 用于拉取一段时间内的审批单号,支持按模板、申请人、部门、审批状态等条件筛选。接口频率限制为 600 次/分钟,一次最多拉取 100 个审批记录;起止时间跨度不能超过 31 天。从 WxCpOaService.java 的接口定义与实现可以看到三套重载:

  • getApprovalInfo(startTime, endTime):最简形式,默认 cursor=0、size=100;
  • getApprovalInfo(startTime, endTime, Integer cursor, Integer size, filters):已标记 @Deprecated,旧版 cursor / next_cursor 字段待废弃;
  • getApprovalInfo(startTime, endTime, String newCursor, Integer size, filters):推荐使用,新版 new_cursor / new_next_cursor 游标分页。
// 获取最近 7 天的审批单(新版游标)
Date startTime = new Date(System.currentTimeMillis() - 7 * 24 * 60 * 60 * 1000L);
Date endTime = new Date();

WxCpApprovalInfo approvalInfo = wxCpService.getOaService()
    .getApprovalInfo(startTime, endTime, "0", 100, null);

List<String> spNumbers = approvalInfo.getSpNoList();   // 本次拉取的审批单号
String nextCursor = approvalInfo.getNewNextCursor();   // 用该值作为下一页 newCursor

参数约束(源码可验证):在 WxCpOaServiceImpl.java 中,size 为空时默认 100,且会校验 size 必须在 [1, 100] 区间,否则抛出 IllegalArgumentException;newCursor 为空时默认传空字符串。

筛选条件:filters 使用 WxCpApprovalInfoQueryFilter.java 表达,其 KEY 枚举支持:

枚举值 含义
TEMPLATE_ID 模板类型/模板 id
CREATOR 申请人
DEPARTMENT 审批单提单者所在部门(仅“部门”支持同时配置多个筛选条件)
SP_STATUS 审批状态
record_type 审批单类型属性:1-请假;2-打卡补卡;3-出差;4-外出;5-加班;6-调班;7-会议室预定;8-退款审批;9-红包报销审批

需要注意筛选条件的组合规则:不同类型的筛选条件之间为“与”的关系,同类型筛选条件之间为“或”的关系。返回体 WxCpApprovalInfo.java 除 spNoList 外还同时携带旧版 nextCursor 与新版权威游标 newNextCursor,用于循环分页。

4.2 获取审批申请详情:getApprovalDetail

拿到审批单号后,调用 getApprovalDetail(spNo) 即可获得完整详情:

WxCpApprovalDetailResult result = wxCpService.getOaService()
    .getApprovalDetail("approval_number");

WxCpApprovalDetailResult.WxCpApprovalDetail detail = result.getInfo();
System.out.println("审批单号: " + detail.getSpNo());
System.out.println("审批名称: " + detail.getSpName());
System.out.println("审批状态: " + detail.getSpStatus());
System.out.println("申请人: " + detail.getApplier().getUserId());
System.out.println("申请时间: " + detail.getApplyTime());

详情实体 WxCpApprovalDetailResult.java 内部类 WxCpApprovalDetail 的核心字段包括:

  • spNo / spName:审批编号、审批申请类型名称(审批模板名称);
  • spStatus:申请单状态,SDK 已封装为枚举 WxCpSpStatus.java:1-审批中(AUDITING)、2-已通过(PASSED)、3-已驳回(REJECTED)、4-已撤销(UNDONE)、6-通过后撤销(PASS_UNDONE)、7-已删除(DELETED)、10-已支付(ALREADY_PAY);
  • templateId:审批模板 id;applyTime:提交时间(Unix 时间戳);
  • applier:申请人信息(WxCpApprovalApplier);
  • spRecords:审批流程信息,可能有多个审批节点(WxCpApprovalRecord[]);
  • notifiers:抄送信息;applyData:审批申请数据;comments:审批申请备注信息;
  • sumMoney:审批单据的总金额(单位:分),当审批单包含费用相关控件时返回。该字段的 JSON 反序列化行为由 WxCpOaServiceImplTest.java 中的 testApprovalDetailSumMoney 用例验证,且对不含该字段的旧响应保持向后兼容(返回 null)。

五、审批流程引擎:主动查询审批当前状态

审批流程引擎能力由 WxCpOaAgentService.java 提供,对应 /cgi-bin/corp/getopenapprovaldata 接口。它允许开发者主动查询第三方/自建应用审批单的当前审批状态,是对“状态变化回调”之外的主动查询补充。

// 通过 WxCpService 获取自建应用审批服务
WxCpOaAgentService oaAgentService = wxCpService.getOaAgentService();

// 查询审批单当前状态,thirdNo 为第三方审批单号
WxCpOpenApprovalData data = oaAgentService.getOpenApprovalData("thirdNo");

从 WxCpOaAgentServiceImpl.java 的实现可以看出,SDK 将 thirdNo 放入请求体后 POST 到 GET_OPEN_APPROVAL_DATA,并从响应的 data 节点反序列化为 WxCpOpenApprovalData 返回。

六、审批模板管理:创建、更新与查询

除了提交与查询审批单,SDK 还完整支持审批模板的 CRUD,模板对象为 WxCpOaApprovalTemplate.java,包含:

  • templateId:仅更新模板时需要提供;
  • templateName:模板名称(TemplateTitle 列表,支持多语言,如 zh_CN);
  • templateContent:模板内容(TemplateContent,由 controls 控件列表组成)。

6.1 获取模板详情

String templateId = "3Tka1eD6v6JfzhDMqPd3aMkFdxqtJMc2ZRioUBGCNS";
WxCpOaApprovalTemplateResult templateResult = wxCpService.getOaService()
    .getTemplateDetail(templateId);

System.out.println("模板名称: " + templateResult.getTemplateNames());
System.out.println("模板内容: " + templateResult.getTemplateContent());

模板详情返回值中包含模板的控件列表(含每个控件的 id、control 类型、require 是否必填、单选/多选选项等),这正是构造 WxCpOaApplyEventRequest.applyData 时 id 的来源。仓库测试 WxCpOaServiceImplTest.java 中的 testGetTemplateDetail 展示了一个真实的“销售用章申请”模板 JSON,包含 Text、Selector、Textarea、Date、File 等多种控件及其选项配置。

6.2 创建与更新模板

// 创建模板:成功后返回新模板的 template_id
String templateId = wxCpService.getOaService()
    .createOaApprovalTemplate(WxCpOaApprovalTemplate.fromJson(templateJson));

// 更新模板:需携带 template_id,成功后无返回内容
wxCpService.getOaService()
    .updateOaApprovalTemplate(WxCpOaApprovalTemplate.fromJson(templateJson));

权限说明(来自接口注释):

  • 创建:仅「审批」系统应用、自建应用和代开发自建应用可调用;
  • 更新:所有应用都可以通过本接口更新自己的模板;「审批」系统应用可以修改管理员手动创建的模板;自建应用和代开发自建应用不可通过本接口更新其他应用创建的模板。

测试用例 testCreateOaApprovalTemplate 给出了一个可参考的创建模板 JSON:template_name 定义名称,template_content.controls 中每个控件包含 property(control、id、title、placeholder、require、un_print 等)与 config(如 selector 单选/多选配置)两部分。

七、第三方应用(服务商)与多账号支持

7.1 第三方应用场景

对于服务商代开发场景,SDK 在 WxCpTpOAService.java 中提供了带 corpId 参数的审批接口,便于在同一第三方应用中处理多个企业客户:

WxCpTpOAService tpOaService = wxCpTpService.getOaService();

// 代指定企业提交审批申请
String spNo = tpOaService.apply(request, "corpId");

// 获取指定企业审批详情
WxCpApprovalDetailResult detail = tpOaService.getApprovalDetail("spNo", "corpId");

// 获取指定企业模板详情
WxCpOaApprovalTemplateResult template = tpOaService.getTemplateDetail("templateId", "corpId");

// 复制/更新模板到企业(openTemplateId 为服务商侧的开放模板 ID)
String templateId = tpOaService.copyTemplate("openTemplateId", "corpId");

7.2 多账号配置支持

面向企业内部多 Corp 的场景,WxJava 提供 WxCpMultiServices 按 corpId 获取独立的 WxCpService 实例(对应 Spring Boot 多账号 starter,参见 wx-java-cp-multi-spring-boot-starter):

@Autowired
private WxCpMultiServices wxCpMultiServices;

// 获取指定企业的服务实例
WxCpService wxCpService = wxCpMultiServices.getWxCpService("corpId");
WxCpOaService oaService = wxCpService.getOaService();

八、测试与验证:如何确认功能可用

仓库为审批功能提供了两层验证手段:

  1. 单元/集成测试:WxCpOaServiceImplTest.java 覆盖 testApply、testGetApprovalInfo、testGetApprovalDetail、testGetTemplateDetail、testApprovalDetailSumMoney、testCreateOaApprovalTemplate 等关键用例,其中 testApprovalDetailSumMoney 与模板详情用例包含完整的 JSON 反序列化验证,可直接作为字段映射正确性的参考;
  2. 完整流程演示:WxCpApprovalWorkflowDemo.java 以 completeWorkflowDemo() 串联了「提交审批 → 获取详情 → 批量拉取 → 模板管理」四个步骤,演示代码中明确标注了需要配置真实的企业微信服务参数后方可运行。

九、注意事项与常见问题

  1. 权限配置:自建应用调用批量获取审批单号等接口时,需在「管理后台 - 应用管理 - 审批 - API - 审批数据权限」中授权应用允许提交/读取审批单据(见 WxCpOaService.java 接口注释);
  2. 接口限制:批量获取审批单号单次最多 100 条、频率不超过 600 次/分钟;endtime 需大于 starttime,起止时间跨度不能超过 31 天;查询审批申请详情、提交审批申请的调用者需确保申请人、审批人在应用可见范围内;
  3. 游标演进:旧版 cursor/next_cursor 分页字段已标记废弃,getApprovalInfo 的旧重载亦标记 @Deprecated,新开发请使用 new_cursor/new_next_cursor 对应的重载;
  4. 控件 id 来源:构造 applyData 时各控件的 id 必须来自“获取审批模板详情”接口返回的控件定义,必填控件(require=1)必须填写值;
  5. 模板限制:暂不支持通过接口提交「打卡补卡」「调班」模板的审批单;
  6. 旧接口下线:getApprovalData(旧版获取审批数据,/cgi-bin/corp/getapprovaldata)官方已标注“后续将不再维护、逐步下线”,推荐使用「批量获取审批单号 + 获取审批申请详情」的新接口组合。

结语

综上所述,WxJava 已经完整覆盖企业微信流程审批的全部核心能力:以 WxCpOaService 支撑传统 OA 审批的提交与查询,以 WxCpOaAgentService 支撑审批流程引擎的主动状态查询,以模板管理接口支撑审批模板的动态维护,并通过 WxCpTpOAService 与 WxCpMultiServices 分别支持第三方服务商与多账号场景。无论是内部 OA 系统集成,还是服务商多租户交付,都可以基于 weixin-java-cp 模块直接落地,具体使用疑问可参考 WxCpOaServiceImplTest.java 测试用例与 WxCpApprovalWorkflowDemo.java 完整演示。

登录后查看全文
WxJava