企业官网建设流程全解析

WxJava 企业微信流程审批开发指南：提交申请、查询详情与审批流程引擎实战

【免费下载链接】WxJava微信开发 Java SDK ，支持包括微信支付，开放平台，小程序，企业微信，视频号，公众号等的后端开发项目地址: https://gitcode.com/gh_mirrors/wx/WxJava

本篇指南基于 WxJava 仓库中的企业微信 OA 审批模块，系统讲解如何通过 SDK 提交审批申请、批量获取审批单号、查询审批申请详情、对接审批流程引擎（自建/第三方应用），以及审批模板的创建、更新与查询。读完本文，你将掌握企业微信「审批应用」从表单构造、流程指定到状态追踪的完整后端接入方案，并理解底层 API 调用链与核心数据模型。

功能总览：传统 OA 审批与审批流程引擎

企业微信的流程审批能力可分为两条主线，WxJava 均提供了完整封装：

• 传统 OA 审批：面向「审批应用」及有权限的自建应用，围绕/cgi-bin/oa/*系列接口实现，覆盖提交申请（applyevent）、批量获取审批单号（getapprovalinfo）、获取审批详情（getapprovaldetail）以及审批模板管理；
• 审批流程引擎：面向自建应用 / 第三方应用，通过/cgi-bin/corp/getopenapprovaldata主动查询审批单当前状态，对应WxCpOaAgentService。

这两条主线在 WxCpOaService.java 与 WxCpOaAgentService.java 两个接口中组织，实现类分别为 WxCpOaServiceImpl.java 和 WxCpOaAgentServiceImpl.java。

已实现 API 清单

需要说明的是：企业微信官方文档中提到的“新版流程审批”（审批流程引擎相关能力）在 WxJava 中已经完整实现，可直接投入使用，无需等待后续版本。

前置准备：获取 OA 服务实例

审批相关接口统一从WxCpService的getOaService()获取：

WxCpService wxCpService = ...; // 由 WxCpConfiguration / WxCpService 工厂创建 WxCpOaService oaService = wxCpService.getOaService();

多账号场景下，先通过WxCpMultiServices按 corpId 取到对应WxCpService再获取 OA 服务（详见下文“多账号配置”一节）。

提交审批申请：构造WxCpOaApplyEventRequest

提交审批申请的核心方法为WxCpOaService.apply(WxCpOaApplyEventRequest)，实现在 WxCpOaServiceImpl.apply：内部将请求对象序列化为 JSON 后 POST 到/cgi-bin/oa/applyevent，并从响应中解析出审批单号sp_no返回，因此方法签名是String。

请求参数详解

请求模型定义在 WxCpOaApplyEventRequest.java，采用@Accessors(chain = true)支持链式调用，字段与官方协议字段一一对应：

完整提交示例

import me.chanjar.weixin.cp.bean.oa.WxCpOaApplyEventRequest; import me.chanjar.weixin.cp.bean.oa.applydata.ApplyDataContent; import me.chanjar.weixin.cp.bean.oa.applydata.ContentValue; // 构造审批申请请求 WxCpOaApplyEventRequest request = new WxCpOaApplyEventRequest() .setCreatorUserId("userId") // 申请人 .setTemplateId("templateId") // 审批模板 id .setUseTemplateApprover(0) // 0-接口指定审批人 .setApprovers(Arrays.asList( // 旧版审批节点 new WxCpOaApplyEventRequest.Approver() .setAttr(2) // 2-会签；1-或签 .setUserIds(new String[]{"approver1", "approver2"}) )) .setNotifiers(new String[]{"notifier1", "notifier2"}) // 抄送人 .setNotifyType(1) // 提单时抄送 .setApplyData(new WxCpOaApplyEventRequest.ApplyData() .setContents(Arrays.asList( new ApplyDataContent() .setControl("Text") // 控件类型 .setId("Text-1234567890") // 控件 id（与模板控件对应） .setValue(new ContentValue().setText("Approval content")) )) ); // 提交审批，返回审批单号 String spNo = wxCpService.getOaService().apply(request);

旧版审批节点Approver：attr表示节点审批方式，1-或签、2-会签，仅在节点为多人审批时有效；userIds为节点审批人 userid 列表，多人会签/或签时需填写每个人的 userid。

新版流程process（当希望按新版流程列表指定审批链时使用）：

WxCpOaApplyEventRequest.Process process = new WxCpOaApplyEventRequest.Process() .setNodeList(Arrays.asList( new WxCpOaApplyEventRequest.ProcessNode() .setType(1) // 1-审批人 .setApvRel(1) // 1-全签；2-或签；3-依次审批 .setUserIds(new String[]{"userA", "userB"}) )); request.setProcess(process);

新版流程节点ProcessNode的type字段按官方语义为 1-审批人、2/3-抄送人；apvRel表示多人审批方式（1-全签、2-或签、3-依次审批）。

查询审批详情与批量获取审批单号

获取审批申请详情

getApprovalDetail(String spNo)根据审批单号查询审批申请详情，实现在 WxCpOaServiceImpl：POST/cgi-bin/oa/getapprovaldetail，入参仅需sp_no。

WxCpApprovalDetailResult result = wxCpService.getOaService() .getApprovalDetail("approval_number"); WxCpApprovalDetailResult.WxCpApprovalDetail detail = result.getInfo(); System.out.println("Approval Status: " + detail.getSpStatus()); System.out.println("Approval Name: " + detail.getSpName());

响应模型 WxCpApprovalDetailResult.java 中，info内嵌了审批详情对象，关键字段包括：

• spNo/spName：审批编号、审批模板名称；
• spStatus：申请单状态，取值为 WxCpSpStatus.java 枚举——1-审批中；2-已通过；3-已驳回；4-已撤销；6-通过后撤销；7-已删除；10-已支付；
• templateId：审批模板 id；
• applyTime：提交时间（Unix 时间戳）；
• applier：申请人信息（WxCpApprovalApplier.java）；
• spRecords：审批流程节点记录（WxCpApprovalRecord.java）；
• notifiers：抄送节点（WxCpOperator.java）；
• applyData：审批申请数据（WxCpApprovalApplyData.java）；
• comments：审批备注（WxCpApprovalComment.java）；
• sumMoney：审批单据总金额（单位分），当审批单包含费用相关控件时返回。

批量获取审批单号

getApprovalInfo(...)对应官方「批量获取审批单号」接口，用于拉取一段时间内企业微信“审批应用”单据的审批编号，支持按模板类型、申请人、部门、审批状态等条件筛选。实现时对size做了参数校验：size默认 100，合法范围 1～100，越界会抛出IllegalArgumentException（见 WxCpOaServiceImpl）。

Date startTime = new Date(System.currentTimeMillis() - 7 * 24 * 60 * 60 * 1000); // 7 天前 Date endTime = new Date(); // 旧版重载（cursor 为 Integer，官方已建议迁移到 new_cursor） WxCpApprovalInfo approvalInfo = wxCpService.getOaService() .getApprovalInfo(startTime, endTime, 0, 100, null); // 新版重载（new_cursor 为 String，推荐使用） WxCpApprovalInfo approvalInfo2 = wxCpService.getOaService() .getApprovalInfo(startTime, endTime, "", 100, null); List<String> spNumbers = approvalInfo.getSpNoList(); // 本页审批单号列表 String nextCursor = approvalInfo.getNewNextCursor(); // 下一页游标，分页拉取时回填

两个重载的差异在于分页游标类型：老字段cursor/next_cursor（Integer）官方已标记待废弃，新字段new_cursor/new_next_cursor（String）为推荐用法。对应响应模型 WxCpApprovalInfo.java 同时保留了两套游标字段。

接口使用约束（来自接口源码注释，见 WxCpOaService.java）：

• 调用频率限制 600 次/分钟；
• endtime需大于startime，起始时间跨度不能超过 31 天；
• 一次拉取最多 100 个审批记录，可通过多次拉取满足需求；
• 自建应用调用此接口，需在“管理后台-应用管理-审批-API-审批数据权限”中授权应用允许提交审批单据。

筛选条件filters：使用 WxCpApprovalInfoQueryFilter.java 构造，其KEY枚举支持以下维度：

组合规则：仅“部门”支持同时配置多个筛选条件；不同类型筛选条件之间为“与”关系，同类型之间为“或”关系。示例：

WxCpApprovalInfoQueryFilter filter = new WxCpApprovalInfoQueryFilter(); filter.setKey(WxCpApprovalInfoQueryFilter.KEY.TEMPLATE_ID); filter.setValue("templateId_xxx"); WxCpApprovalInfo info = wxCpService.getOaService() .getApprovalInfo(startTime, endTime, "", 100, Collections.singletonList(filter));

审批流程引擎：主动查询审批状态

审批流程引擎（新版流程审批）面向自建应用与第三方应用，核心入口是WxCpOaAgentService.getOpenApprovalData(String thirdNo)，实现在 WxCpOaAgentServiceImpl.java：POST/cgi-bin/corp/getopenapprovaldata，入参为第三方审批单号thirdNo，返回该审批单当前状态。

WxCpOaAgentService oaAgentService = wxCpService.getOaAgentService(); WxCpOpenApprovalData data = oaAgentService.getOpenApprovalData("thirdNo_xxx"); // data 中包含第三方审批单号、审批状态、审批流程记录等

响应模型为 WxCpOpenApprovalData.java（位于bean.oa.selfagent包）。典型使用场景：自建应用收到“审批状态变化”事件回调后，可主动调用本接口向企业微信确认审批单的实时状态，形成“回调驱动 + 主动兜底”的双通道状态同步。

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

WxJava 提供了审批模板的完整管理能力，对应接口方法均已在 WxCpOaService.java 中声明：

// 创建审批模板，返回新模板 id String templateId = oaService.createOaApprovalTemplate(cpTemplate); // 更新审批模板（已配置的审批流程和规则保持不变） oaService.updateOaApprovalTemplate(wxCpTemplate); // 获取模板详情 WxCpOaApprovalTemplateResult result = oaService.getTemplateDetail(templateId);

• createOaApprovalTemplate(WxCpOaApprovalTemplate)：请求体由 WxCpOaApprovalTemplate.java 承载，返回template_id（见 WxCpOaServiceImpl）。创建新模板后，管理后台及审批应用内将生成对应模板，并生效默认流程和规则配置；
• updateOaApprovalTemplate(WxCpOaApprovalTemplate)：更新模板内容，已配置的审批流程和规则不变；
• getTemplateDetail(String templateId)：查询模板详情，返回 WxCpOaApprovalTemplateResult.java。

权限说明（来自接口源码注释）：仅「审批」系统应用、自建应用和代开发自建应用可创建模板；更新模板时，所有应用都可以更新自己的模板，「审批」系统应用可修改管理员手动创建的模板，自建应用和代开发自建应用不可更新其他应用创建的模板。

第三方应用与多账号场景

第三方应用（服务商代开发）

企业微信第三方应用通过WxCpTpService.getOaService()获取 OA 服务，并在调用时为指定企业（corpId）提交或查询审批：

WxCpTpOAService tpOaService = wxCpTpService.getOaService(); // 为指定企业提交审批申请 String spNo = tpOaService.apply(request, "corpId"); // 为指定企业查询审批详情 WxCpApprovalDetailResult detail = tpOaService.getApprovalDetail("spNo", "corpId");

第三方应用场景下，WxCpOaAgentService.getOpenApprovalData(thirdNo)也常被用于查询第三方审批单的当前状态（详见上文“审批流程引擎”一节）。

多账号配置

面向多企业/多应用的部署，WxJava 通过WxCpMultiServices按 corpId 管理多套WxCpService（Spring Boot Starter 场景下由wx-java-cp-multi-spring-boot-starter提供自动装配，参考 wx-java-cp-multi-spring-boot-starter）：

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

审批相关数据模型速查

审批模块的核心数据模型集中在 weixin-java-cp/src/main/java/me/chanjar/weixin/cp/bean/oa 与bean/oa/selfagent包下，可直接用于 JSON 序列化与反序列化：

其中审批状态回调通知（XML 消息）由WxCpXmlApprovalInfo承载，可与WxCpOaAgentService.getOpenApprovalData配合实现审批状态实时追踪。

底层实现与验证路径

调用链解析

所有审批接口都遵循同一调用模式（见 WxCpOaServiceImpl.java）：

1. 构造 JSON 请求体（时间戳统一转换为 Unix 秒，如startTime.getTime() / 1000L）；
2. 通过mainService.getWxCpConfigStorage().getApiUrl(常量)拼接带 access_token 的完整 URL，端点常量定义在 WxCpApiPathConsts.Oa 中；
3. 调用mainService.post(url, body)发起 HTTPS 请求，由WxCpService统一负责 access_token 管理与错误码处理；
4. 使用 Gson（WxCpGsonBuilder/GsonParser）解析响应为对应数据模型。

这意味着你无需关心 access_token 刷新与签名细节，SDK 层已统一封装。

测试用例参考

官方指南建议参考WxCpOaServiceImplTest中的测试用例理解各方法的请求体结构，该测试类位于 weixin-java-cp/src/test/java/me/chanjar/weixin/cp/api 目录下，可结合测试中的 JSON 断言快速确认apply、getApprovalInfo、getApprovalDetail等方法的实际报文格式。

常见问题与使用提示

• 模板 id 从哪来：可从“获取审批申请详情”“审批状态变化回调通知”获得，也可从审批模板的模板编辑页面链接中提取；用getTemplateDetail亦可查询。
• 提交的审批单没有按预期流转：检查use_template_approver取值。为 0 时使用接口指定的approver/process，为 1 时使用管理后台配置的审批流程（支持条件审批），二者不可混用。
• 分页拉取审批单号：官方已弃用老游标cursor，请使用新版getApprovalInfo(startTime, endTime, newCursor, size, filters)重载，用返回的new_next_cursor作为下一页入参，直到返回空列表。
• 状态字段含义：spStatus的取值枚举（1-审批中、2-已通过、3-已驳回、4-已撤销等）定义在 WxCpSpStatus.java，判断结果时请勿硬编码数字。
• 回调与主动查询结合：审批状态变化通过回调 XML 通知（WxCpXmlApprovalInfo）推送，配合getOpenApprovalData(thirdNo)主动确认，可构建高可靠的审批状态同步链路。

结语

WxJava 已完整覆盖企业微信流程审批的两大主线：传统 OA 审批（提交、详情、批量拉取、模板管理）与审批流程引擎（getOpenApprovalData），同时支持自建应用、第三方应用（WxCpTpOaService）与多账号（WxCpMultiServices）场景。按本文路径组织请求体、处理游标分页与状态枚举，即可在业务系统中快速落地审批单据的提交与追踪能力。

【免费下载链接】WxJava微信开发 Java SDK ，支持包括微信支付，开放平台，小程序，企业微信，视频号，公众号等的后端开发项目地址: https://gitcode.com/gh_mirrors/wx/WxJava