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 清单能力请求端点SDK 入口方法提交审批申请POST /cgi-bin/oa/applyeventWxCpOaService.apply(WxCpOaApplyEventRequest)获取审批申请详情POST /cgi-bin/oa/getapprovaldetailWxCpOaService.getApprovalDetail(String spNo)批量获取审批单号POST /cgi-bin/oa/getapprovalinfoWxCpOaService.getApprovalInfo(...)含新版new_cursor分页重载审批流程引擎状态查询POST /cgi-bin/corp/getopenapprovaldataWxCpOaAgentService.getOpenApprovalData(String thirdNo)获取审批模板详情POST /cgi-bin/oa/gettemplatedetailWxCpOaService.getTemplateDetail(String templateId)创建审批模板POST /cgi-bin/oa/approval/create_templateWxCpOaService.createOaApprovalTemplate(...)更新审批模板POST /cgi-bin/oa/approval/update_templateWxCpOaService.updateOaApprovalTemplate(...)需要说明的是企业微信官方文档中提到的“新版流程审批”审批流程引擎相关能力在 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)支持链式调用字段与官方协议字段一一对应字段JSON 字段必填说明creatorUserIdcreator_userid是申请人 userid此审批申请将以此员工身份提交申请人需在应用可见范围内templateIdtemplate_id是模板 id可从“获取审批申请详情”“审批状态变化回调通知”中获得也可在审批模板的模板编辑页面链接中获得暂不支持通过接口提交「打卡补卡」「调班」模板审批单useTemplateApproveruse_template_approver是审批人模式0-通过接口指定审批人、抄送人此时 approver/process、notifyer 等参数可用1-使用模板在管理后台设置的审批流程支持条件审批。默认 0chooseDepartmentchoose_department否提单者提单部门 id不填默认为主部门processprocess条件新版流程节点列表仅use_template_approver为 0 时生效approversapprover条件旧版审批流程信息支持单人审批、多人会签、多人或签仅use_template_approver为 0 时生效notifiersnotifyer否抄送人节点 userid 列表仅use_template_approver为 0 时生效notifyTypenotify_type否抄送方式1-提单时抄送默认值2-单据通过后抄送3-提单和单据通过后抄送applyDataapply_data是审批申请数据各控件的值必填项必须有值选填项可为空summaryListsummary_list否摘要信息用于显示在审批通知卡片、审批列表最多 3 行完整提交示例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);旧版审批节点Approverattr表示节点审批方式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)根据审批单号查询审批申请详情实现在 WxCpOaServiceImplPOST/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审批模板 idapplyTime提交时间Unix 时间戳applier申请人信息WxCpApprovalApplier.javaspRecords审批流程节点记录WxCpApprovalRecord.javanotifiers抄送节点WxCpOperator.javaapplyData审批申请数据WxCpApprovalApplyData.javacomments审批备注WxCpApprovalComment.javasumMoney审批单据总金额单位分当审批单包含费用相关控件时返回。批量获取审批单号getApprovalInfo(...)对应官方「批量获取审批单号」接口用于拉取一段时间内企业微信“审批应用”单据的审批编号支持按模板类型、申请人、部门、审批状态等条件筛选。实现时对size做了参数校验size默认 100合法范围 1100越界会抛出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); ListString spNumbers approvalInfo.getSpNoList(); // 本页审批单号列表 String nextCursor approvalInfo.getNewNextCursor(); // 下一页游标分页拉取时回填两个重载的差异在于分页游标类型老字段cursor/next_cursorInteger官方已标记待废弃新字段new_cursor/new_next_cursorString为推荐用法。对应响应模型 WxCpApprovalInfo.java 同时保留了两套游标字段。接口使用约束来自接口源码注释见 WxCpOaService.java调用频率限制 600 次/分钟endtime需大于startime起始时间跨度不能超过 31 天一次拉取最多 100 个审批记录可通过多次拉取满足需求自建应用调用此接口需在“管理后台-应用管理-审批-API-审批数据权限”中授权应用允许提交审批单据。筛选条件filters使用 WxCpApprovalInfoQueryFilter.java 构造其KEY枚举支持以下维度枚举JSON 字段含义TEMPLATE_IDtemplate_id模板类型/模板 idCREATORcreator申请人DEPARTMENTdepartment审批单提单者所在部门SP_STATUSsp_status审批状态record_typerecord_type审批单类型1-请假2-打卡补卡3-出差4-外出5-加班6-调班7-会议室预定8-退款审批9-红包报销审批组合规则仅“部门”支持同时配置多个筛选条件不同类型筛选条件之间为“与”关系同类型之间为“或”关系。示例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.javaPOST/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 管理多套WxCpServiceSpring Boot Starter 场景下由wx-java-cp-multi-spring-boot-starter提供自动装配参考 wx-java-cp-multi-spring-boot-starterAutowired 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 序列化与反序列化数据模型作用WxCpOaApplyEventRequest提交审批申请请求体含Approver、Process、ProcessNode、ApplyData内部类WxCpApprovalDetailResult获取审批申请详情的响应内嵌WxCpApprovalDetailWxCpApprovalInfo批量获取审批单号的响应含spNoList与新旧游标字段WxCpApprovalInfoQueryFilter批量拉取的筛选条件KEY枚举 valueWxCpSpStatus/WxCpRecordSpStatus审批单状态 / 审批记录状态枚举WxCpApprovalRecord/WxCpApprovalRecordDetail审批流程节点记录与节点内审批明细WxCpApprovalApplier/WxCpOperator申请人信息 / 操作者抄送人信息WxCpApprovalApplyData审批申请数据控件内容列表WxCpApprovalComment审批备注信息WxCpOaApprovalTemplate/WxCpOaApprovalTemplateResult审批模板请求体 / 模板详情响应WxCpOpenApprovalData审批流程引擎查询结果bean/oa/selfagent包WxCpXmlApprovalInfo审批状态变化事件的 XML 消息体解析消息回调场景WxCpGetApprovalData旧版“获取审批数据”接口的响应模型其中审批状态回调通知XML 消息由WxCpXmlApprovalInfo承载可与WxCpOaAgentService.getOpenApprovalData配合实现审批状态实时追踪。底层实现与验证路径调用链解析所有审批接口都遵循同一调用模式见 WxCpOaServiceImpl.java构造 JSON 请求体时间戳统一转换为 Unix 秒如startTime.getTime() / 1000L通过mainService.getWxCpConfigStorage().getApiUrl(常量)拼接带 access_token 的完整 URL端点常量定义在 WxCpApiPathConsts.Oa 中调用mainService.post(url, body)发起 HTTPS 请求由WxCpService统一负责 access_token 管理与错误码处理使用 GsonWxCpGsonBuilder/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
WxJava 企业微信流程审批开发指南：提交申请、查询详情与审批流程引擎实战
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 清单能力请求端点SDK 入口方法提交审批申请POST /cgi-bin/oa/applyeventWxCpOaService.apply(WxCpOaApplyEventRequest)获取审批申请详情POST /cgi-bin/oa/getapprovaldetailWxCpOaService.getApprovalDetail(String spNo)批量获取审批单号POST /cgi-bin/oa/getapprovalinfoWxCpOaService.getApprovalInfo(...)含新版new_cursor分页重载审批流程引擎状态查询POST /cgi-bin/corp/getopenapprovaldataWxCpOaAgentService.getOpenApprovalData(String thirdNo)获取审批模板详情POST /cgi-bin/oa/gettemplatedetailWxCpOaService.getTemplateDetail(String templateId)创建审批模板POST /cgi-bin/oa/approval/create_templateWxCpOaService.createOaApprovalTemplate(...)更新审批模板POST /cgi-bin/oa/approval/update_templateWxCpOaService.updateOaApprovalTemplate(...)需要说明的是企业微信官方文档中提到的“新版流程审批”审批流程引擎相关能力在 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)支持链式调用字段与官方协议字段一一对应字段JSON 字段必填说明creatorUserIdcreator_userid是申请人 userid此审批申请将以此员工身份提交申请人需在应用可见范围内templateIdtemplate_id是模板 id可从“获取审批申请详情”“审批状态变化回调通知”中获得也可在审批模板的模板编辑页面链接中获得暂不支持通过接口提交「打卡补卡」「调班」模板审批单useTemplateApproveruse_template_approver是审批人模式0-通过接口指定审批人、抄送人此时 approver/process、notifyer 等参数可用1-使用模板在管理后台设置的审批流程支持条件审批。默认 0chooseDepartmentchoose_department否提单者提单部门 id不填默认为主部门processprocess条件新版流程节点列表仅use_template_approver为 0 时生效approversapprover条件旧版审批流程信息支持单人审批、多人会签、多人或签仅use_template_approver为 0 时生效notifiersnotifyer否抄送人节点 userid 列表仅use_template_approver为 0 时生效notifyTypenotify_type否抄送方式1-提单时抄送默认值2-单据通过后抄送3-提单和单据通过后抄送applyDataapply_data是审批申请数据各控件的值必填项必须有值选填项可为空summaryListsummary_list否摘要信息用于显示在审批通知卡片、审批列表最多 3 行完整提交示例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);旧版审批节点Approverattr表示节点审批方式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)根据审批单号查询审批申请详情实现在 WxCpOaServiceImplPOST/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审批模板 idapplyTime提交时间Unix 时间戳applier申请人信息WxCpApprovalApplier.javaspRecords审批流程节点记录WxCpApprovalRecord.javanotifiers抄送节点WxCpOperator.javaapplyData审批申请数据WxCpApprovalApplyData.javacomments审批备注WxCpApprovalComment.javasumMoney审批单据总金额单位分当审批单包含费用相关控件时返回。批量获取审批单号getApprovalInfo(...)对应官方「批量获取审批单号」接口用于拉取一段时间内企业微信“审批应用”单据的审批编号支持按模板类型、申请人、部门、审批状态等条件筛选。实现时对size做了参数校验size默认 100合法范围 1100越界会抛出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); ListString spNumbers approvalInfo.getSpNoList(); // 本页审批单号列表 String nextCursor approvalInfo.getNewNextCursor(); // 下一页游标分页拉取时回填两个重载的差异在于分页游标类型老字段cursor/next_cursorInteger官方已标记待废弃新字段new_cursor/new_next_cursorString为推荐用法。对应响应模型 WxCpApprovalInfo.java 同时保留了两套游标字段。接口使用约束来自接口源码注释见 WxCpOaService.java调用频率限制 600 次/分钟endtime需大于startime起始时间跨度不能超过 31 天一次拉取最多 100 个审批记录可通过多次拉取满足需求自建应用调用此接口需在“管理后台-应用管理-审批-API-审批数据权限”中授权应用允许提交审批单据。筛选条件filters使用 WxCpApprovalInfoQueryFilter.java 构造其KEY枚举支持以下维度枚举JSON 字段含义TEMPLATE_IDtemplate_id模板类型/模板 idCREATORcreator申请人DEPARTMENTdepartment审批单提单者所在部门SP_STATUSsp_status审批状态record_typerecord_type审批单类型1-请假2-打卡补卡3-出差4-外出5-加班6-调班7-会议室预定8-退款审批9-红包报销审批组合规则仅“部门”支持同时配置多个筛选条件不同类型筛选条件之间为“与”关系同类型之间为“或”关系。示例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.javaPOST/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 管理多套WxCpServiceSpring Boot Starter 场景下由wx-java-cp-multi-spring-boot-starter提供自动装配参考 wx-java-cp-multi-spring-boot-starterAutowired 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 序列化与反序列化数据模型作用WxCpOaApplyEventRequest提交审批申请请求体含Approver、Process、ProcessNode、ApplyData内部类WxCpApprovalDetailResult获取审批申请详情的响应内嵌WxCpApprovalDetailWxCpApprovalInfo批量获取审批单号的响应含spNoList与新旧游标字段WxCpApprovalInfoQueryFilter批量拉取的筛选条件KEY枚举 valueWxCpSpStatus/WxCpRecordSpStatus审批单状态 / 审批记录状态枚举WxCpApprovalRecord/WxCpApprovalRecordDetail审批流程节点记录与节点内审批明细WxCpApprovalApplier/WxCpOperator申请人信息 / 操作者抄送人信息WxCpApprovalApplyData审批申请数据控件内容列表WxCpApprovalComment审批备注信息WxCpOaApprovalTemplate/WxCpOaApprovalTemplateResult审批模板请求体 / 模板详情响应WxCpOpenApprovalData审批流程引擎查询结果bean/oa/selfagent包WxCpXmlApprovalInfo审批状态变化事件的 XML 消息体解析消息回调场景WxCpGetApprovalData旧版“获取审批数据”接口的响应模型其中审批状态回调通知XML 消息由WxCpXmlApprovalInfo承载可与WxCpOaAgentService.getOpenApprovalData配合实现审批状态实时追踪。底层实现与验证路径调用链解析所有审批接口都遵循同一调用模式见 WxCpOaServiceImpl.java构造 JSON 请求体时间戳统一转换为 Unix 秒如startTime.getTime() / 1000L通过mainService.getWxCpConfigStorage().getApiUrl(常量)拼接带 access_token 的完整 URL端点常量定义在 WxCpApiPathConsts.Oa 中调用mainService.post(url, body)发起 HTTPS 请求由WxCpService统一负责 access_token 管理与错误码处理使用 GsonWxCpGsonBuilder/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
