做企业微信审批流开发这事说难不算难说简单也真不简单。我前前后后给三家企业搭过自定义审批模板从刚开始连回调签名验证都调不通到后面把多级审批、条件分支、消息回写全流程跑稳中间踩过的坑差不多能写一本小册子。这篇就把我从零搭建企业微信自定义审批流的完整过程、完整代码、还有那些最容易翻车的细节整理出来给准备自己搞审批流的同学做个参考。这个内容适合谁看两类人。一类是公司内部IT或开发需要把线下的报销、请假、采购、合同流程搬到企业微信上又嫌官方审批后台不够灵活另一类是做企业服务集成的外包或SaaS开发需要把审批能力嵌入到自己的业务系统里。看完你就能自己搭一套带自定义模板、自动回调、状态回写的审批流改改模板ID和字段ID就能适配不同场景。1. 为什么我选择自建审批模板而不是直接套用系统审批很多团队一开始都会纠结企业微信自带的审批功能就能用为什么还要自己开发一套这个问题的答案基本决定了整个项目的技术选型方向。1.1 原生审批的边界在哪里企业微信原生审批系统确实好用打开就能发起请假、报销、补卡审批人也直接在聊天里点一下就行。但一旦业务复杂起来原生审批就开始露怯了。举几个我实际遇到的例子第一个例子是字段联动。我们有个采购流程金额超过五万就要自动追加一个财务总监审批节点金额低于五万只走部门经理就行。原生审批也能配条件分支但条件规则是基于表单字段的固定逻辑业务规则的调整往往要等官方的功能更新不能通过接口动态控制。第二个例子是审批数据要回写业务系统。原生审批结束后数据留在企业微信后台想同步到公司的ERP、OA或者财务软件得靠人工导出或者第三方工具去捞数据再手动对账。我们当时要对接内部预算系统审批结果要实时扣减预算额度这个原生审批完全做不到。第三个例子是流程不可编程。比如审批通过之后自动创建工单、自动发邮件、自动触发下一条流程审批驳回之后自动退回并通知发起人修改。这些“审批之外”的动作原生审批都不支持。你需要一个能跟业务系统对话的审批引擎。1.2 自建审批模板的核心优势自建审批流本质上是把企业微信当作“审批的展示层和触达层”真正的流程逻辑、数据存储、业务联动全部放在自己的服务里。这样做的好处非常直接表单字段完全自定义。文本框、数字框、日期、单选、多选、明细表、图片附件想怎么组合就怎么组合想什么时候加字段就什么时候加字段。审批节点动态计算。审批人可以是固定的人也可以根据表单内容动态算出比如根据金额、部门、城市等条件匹配对应的审批人。审批结果实时回写。审批状态变化通过回调瞬间通知到自己的系统业务数据可以无缝联动。审批流程可版本化。模板可以改版、灰度、回滚这在企业制度频繁变动的环境下非常有用。1.3 系统整体架构设计我建议的整体架构是企业微信管理后台创建一个自建应用应用里配置审批模板业务后端服务负责三件事第一是维护模板和流程配置的数据表第二是调用企业微信API发起审批第三是接收企业微信的审批事件回调并更新状态前端则提供一个H5页面嵌入到企业微信工作台用来发起审批和查看我的申请。选择后端技术栈时我用的是Node.js Express因为公司现有团队偏JavaScript方向。你完全可以用Python Flask、Java Spring Boot、Go Gin替换核心逻辑是一样的只是企业微信接口调用方式略有差异。这里有个重要的设计原则不要把所有逻辑都塞在回调处理函数里。因为企业微信回调可能乱序、重复、甚至延迟我后来把回调消息先写入队列再异步处理保证审批状态最终一致。这个后面会详细说。2. 前置准备企业微信应用、可信域名与API权限开始写代码之前必须先在企业微信管理后台把应用的“地基”打牢。很多审批流开发做到一半突然卡壳回头一看全是配置问题。2.1 创建自建应用与获取基础凭证登录企业微信管理后台进入“应用管理” - “自建应用” - “创建应用”填上应用名称和 Logo创建完成后你会拿到两个关键信息AgentId 和 Secret。另外还要在企业信息里找到 CorpId这三个值基本上贯穿整个开发过程。创建应用后默认只有基础权限调用审批相关接口需要额外申请接口权限。在“应用管理”里找到你的自建应用进入“API权限”把以下权限加进去审批获取审批模板详情、提交审批申请、获取审批申请详情、获取审批数据通讯录读取成员、读取部门用于解析审批人消息推送发送应用消息用于通知审批人这里要提醒一下Secret和AgentId不要在代码里写死建议放在环境变量或配置中心。因为Secret一旦泄漏别人就能拿它调用你的企业接口风险非常大。我见过有人把Secret直接提交到Git仓库结果整个企业通讯录都被拉走教训很深。2.2 可信域名与回调URL配置一字之差就是千古恨这是审批流开发中踩坑率最高的环节。很多热词搜索里也常看到“可信域名”相关的问题比如“该域名主体为第三方服务商请使用企业主体域名”这个提示的意思就是你配置的域名没有通过企业微信的可信域名校验。企业微信要求所有需要调用JS-SDK的页面域名以及接收回调的URL域名都必须先完成域名归属验证。具体的配置路径是“应用管理” - 你的自建应用 - “网页应用及JS-SDK” - “可信域名”。配置可信域名有几个硬性要求域名必须是企业主体名下的且已经完成ICP备案。第三方服务商的域名不能用。域名必须支持HTTPS访问证书有效。必须下载企业微信提供的校验文件放到域名根目录下确认能通过外网访问。回调URL的配置在“接收消息”里需要填一个完整的URL比如https://yourdomain.com/wecom/callback同时设置Token和EncodingAESKey。这里的Token和EncodingAESKey是回调加解密用的跟业务Token完全是两回事后面代码里会用到。需要特别说明的是回调URL和可信域名是两套体系即使回调URL配了JS-SDK的页面访问还是需要可信域名即使可信域名通过也不代表回调就能通。我见过不少同学在这两个地方来回改结果一个是校验文件没放对另一个是回调URL路径写错。2.3 权限范围与通讯录同步自建应用默认只能看到部分通讯录信息。如果审批流里需要按照部门找审批人或者要读取成员UserID就必须在“权限管理”里把通讯录权限设为“企业通讯录”或者至少“自建应用可见范围”包含对应的部门和成员。这一步的坑在于应用可见范围直接决定了“谁能看到这个应用”也决定了接口能拉到哪些人。如果你把可见范围设成某个部门但审批流程里却要选另一个部门的经理接口会返回“userid不存在”或者权限不足。我当时就在这卡了半天最后才发现是可见范围没包含审批人所在的部门。3. 数据模型与流程引擎设计先把表结构想清楚代码是表象数据模型才是审批流的灵魂。如果表结构设计得不好后面加需求改流程会非常痛苦。3.1 审批模板与字段表设计我设计了四张核心表模板表、字段表、节点表、审批记录表。模板表approval_templates用来存模板基础信息字段名类型说明idint主键template_namevarchar模板名称wecom_template_idvarchar企业微信审批模板IDcreatorvarchar创建人UserIDstatustinyint启用/停用created_atdatetime创建时间字段表approval_template_fields用来存模板的表单字段定义字段名类型说明idint主键template_idint关联模板表field_keyvarchar字段标识如amountfield_namevarchar字段显示名如报销金额field_typevarcharText/Textarea/Number/Date/Select/Moneyrequiredtinyint是否必填optionstext单选/多选的选项JSON格式sortint排序节点表approval_nodes用来定义审批流程字段名类型说明idint主键template_idint关联模板表node_namevarchar节点名称如部门经理审批node_typetinyint1顺序审批 2会签 3或签approver_typevarcharuser指定人/role角色/dept部门负责人approver_valuevarchar审批人的UserID或部门IDcondition_exprtext可选节点生效条件如amount 50000sortint节点顺序审批记录表approval_records用来存审批实例状态字段名类型说明idint主键sp_novarchar企业微信审批编号template_idint模板IDcreatorvarchar发起人UserIDcurrent_statustinyint审批中/通过/驳回/撤销apply_datatext提交的表单数据JSON格式callback_datatext回调原始数据JSON格式created_atdatetime创建时间updated_atdatetime更新时间3.2 审批节点类型与执行规则审批节点这块我用一个例子来说明。假设报销流程是这样的金额小于5000元只需要直属上级审批金额在5000元到50000元之间需要部门经理审批金额超过50000元需要部门经理和财务总监都审批。对应到表结构我会有三个节点节点1条件amount 5000审批人为直属上级节点2条件amount 5000 amount 50000审批人为部门经理节点3条件amount 50000节点类型为会签审批人为部门经理和财务总监注意企业微信创建审批模板的时候本身就支持配置审批人但如果你完全依赖企业微信的审批模板配置去做条件分支那你仍然没法把“审批结果回写业务系统”“自动触发后续动作”这些逻辑接进来。所以我自己的做法是企业微信那边只配一个“通用审批模板”所有自定义逻辑都放在自己的节点表里通过代码决定传给企业微信的审批人究竟是谁。这样做有个好处企业微信那边只当它是普通的审批流而真正的流程规则掌握在自己手里。后续改流程只需要改数据库不用去企业微信后台改模板也不用重新发布应用。3.3 审批状态机设计审批状态我统一用如下状态0审批中1审批通过2审批驳回3审批撤销审批中的记录可能经历节点推进比如从“部门经理审批中”变成“财务审批中”这个中间态可以单独用current_node字段记录不必给每个节点都设计一个状态位。状态流转只发生在三个地方提交时设为审批中回调里收到审批结果为通过/驳回时更新主动撤销时设为撤销。这里有个细节企业微信回调里审批通过和审批驳回对应的事件是不同的审批驳回时可以附上审批意见在向发起人发送通知时要把审批意见一起带过去否则发起人只知道被拒了不知道原因。4. 后端接口实现从Token管理到回调加解密下面进入核心代码实现。为了让你能直接跑通我把代码拆成几个模块工具函数、提交审批接口、回调处理接口。我用Node.js Express实现依赖包只用了express、axios和cryptoNode内置。4.1 环境变量与依赖创建一个项目目录初始化npm并安装依赖mkdir approval-demo cd approval-demo npm init -y npm install express axios在项目根目录创建.env文件填入你的企业微信配置WECOM_CORP_IDww1234567890 WECOM_AGENT_ID1000002 WECOM_SECRETyour_secret_here WECOM_CALLBACK_TOKENyour_token WECOM_CALLBACK_ENCODING_AES_KEYyour_encoding_aes_key这里说一下EncodingAESKey在企业微信后台生成是一个43位的字符串Base64解码后是32字节用来做AES加解密。Token是任意字符串用于签名验证。两个值都要妥善保管。4.2 AccessToken管理必须缓存不能每次现取企业微信接口调用都需要AccessToken获取接口在https://qyapi.weixin.qq.com/cgi-bin/gettoken参数是corpid和corpsecret。AccessToken有效期默认7200秒但企业微信官方要求必须缓存不建议频繁请求。我封装了一个带缓存的获取函数// utils/wecom.js const axios require(axios); const CORP_ID process.env.WECOM_CORP_ID; const SECRET process.env.WECOM_SECRET; let accessTokenCache { token: , expiresAt: 0 }; async function getAccessToken() { // 如果token还没过期直接用缓存 if (accessTokenCache.token Date.now() accessTokenCache.expiresAt - 300000) { return accessTokenCache.token; } const url https://qyapi.weixin.qq.com/cgi-bin/gettoken; const resp await axios.get(url, { params: { corpid: CORP_ID, corpsecret: SECRET } }); if (resp.data.errcode ! 0) { throw new Error(获取access_token失败: ${JSON.stringify(resp.data)}); } accessTokenCache.token resp.data.access_token; // 有效期是7200秒提前300秒过期保证安全 accessTokenCache.expiresAt Date.now() resp.data.expires_in * 1000; return accessTokenCache.token; } module.exports { getAccessToken };这里减300秒是为了避免token恰好在使用时过期。在多实例部署时建议用Redis缓存这个token因为它天然是全局共享的。4.3 提交审批申请接口企业微信创建审批申请的接口是POST /cgi-bin/oa/applyevent请求体中模板ID、发起人、审批人、表单内容都要传。我写了一个提交审批的路由前端传过来一个模板标识和表单数据后端根据模板配置解析出企业微信模板ID、审批人列表再拼装请求体。// routes/approval.js const express require(express); const axios require(axios); const { getAccessToken } require(../utils/wecom); const { getTemplateConfig, buildApplyData } require(../services/approvalService); const router express.Router(); router.post(/submit, async (req, res) { try { const { templateCode, creator, formData } req.body; // 1. 从数据库读取模板配置省略SQL用函数代替 const template await getTemplateConfig(templateCode); // 2. 根据表单数据和节点条件计算实际审批人 const approvers template.nodes .filter(node evalNodeCondition(node.condition_expr, formData)) // 实际生产请用规则引擎避免eval .map(node node.approver_value); // 3. 去重并拼成数组 const approverList [...new Set(approvers)]; // 4. 构造apply_data const applyData buildApplyData(template.fields, formData); // 5. 调用企业微信接口 const accessToken await getAccessToken(); const resp await axios.post( https://qyapi.weixin.qq.com/cgi-bin/oa/applyevent?access_token${accessToken}, { creator_userid: creator, template_id: template.wecom_template_id, use_template_approver: 0, approver: approverList, apply_data: { contents: applyData }, summary_list: [ { summary_info: [ { text: template.template_name, lang: zh_CN } ] } ] } ); if (resp.data.errcode ! 0) { return res.status(500).json({ success: false, error: resp.data }); } // 6. 把审批编号存库这个编号用于后续回调关联 const spNo resp.data.sp_no; await saveApprovalRecord({ spNo, templateCode, creator, formData, status: 0 }); res.json({ success: true, spNo }); } catch (error) { console.error(提交审批失败, error); res.status(500).json({ success: false, error: error.message }); } }); module.exports router;buildApplyData这一层是重点。企业微信的表单控件类型很多每种控件对应的数据结构都不一样。我封装了一个映射函数// services/approvalService.js function buildApplyData(fields, formData) { return fields.map(field { const value formData[field.field_key]; switch (field.field_type) { case Text: return { control: Text, id: field.wecom_control_id, // 需要从企业微信模板详情里拿到控件ID value: { text: value || } }; case Textarea: return { control: Textarea, id: field.wecom_control_id, value: { text: value || } }; case Number: return { control: Number, id: field.wecom_control_id, value: { new_number: value || 0 } }; case Money: return { control: Money, id: field.wecom_control_id, value: { new_money: value || 0 } }; case Date: return { control: Date, id: field.wecom_control_id, value: { new_date: value } }; case Select: return { control: Select, id: field.wecom_control_id, value: { select: { options: [{ key: value }] } } }; default: return null; } }).filter(Boolean); }注意这里的wecom_control_id不是你自己定义的字段标识而是企业微信审批模板里每个控件的唯一ID。获取方式有两个一是调用“获取审批模板详情”接口传template_id接口会返回模板的所有控件及其ID和属性名二是直接在企业微信后台编辑审批模板时浏览器控制台可以看到每个控件的id。更推荐第一种自动化处理才不会出错。4.4 回调接收与验证最难啃的骨头回调接收是企业微信审批流开发中最容易出问题的地方。企业微信服务器收到审批状态变更后会向你的回调URL发POST请求。请求参数包括msg_signature、timestamp、nonce和echostr首次验证时才有echostrbody是加密的XML。先处理关键的URL验证阶段。当你第一次在后台配置回调URL时企业微信会向你的URL发一个GET请求带timestamp、nonce、echostr三个参数你需要用msg_signature验证后解密echostr返回明文内容给企业微信配置才能生效。代码如下// routes/callback.js const express require(express); const crypto require(crypto); const router express.Router(); const TOKEN process.env.WECOM_CALLBACK_TOKEN; const AES_KEY process.env.WECOM_CALLBACK_ENCODING_AES_KEY; // 把EncodingAESKey解码为Buffer取前16字节作为AES IV const encodingAESKey Buffer.from(AES_KEY , base64); const key encodingAESKey; const iv key.slice(0, 16); // 签名验证 function verifySignature(msgSignature, timestamp, nonce, echostr) { const arr [TOKEN, timestamp, nonce, echostr].sort(); const str arr.join(); const sha1 crypto.createHash(sha1).update(str).digest(hex); return sha1 msgSignature; } // AES解密 function decrypt(encrypted) { const decipher crypto.createDecipheriv(aes-256-cbc, key, iv); decipher.setAutoPadding(false); let decrypted Buffer.concat([ decipher.update(encrypted, base64), decipher.final() ]); // PKCS7去掉填充 const padSize decrypted[decrypted.length - 1]; decrypted decrypted.slice(0, decrypted.length - padSize); return decrypted.toString(utf8); } // 处理URL验证 router.get(/callback, (req, res) { const { msg_signature, timestamp, nonce, echostr } req.query; if (!verifySignature(msg_signature, timestamp, nonce, echostr)) { return res.status(401).send(signature error); } // 密文格式为随机16字节 4字节网络序长度 明文 receiveid const decrypted decrypt(echostr); // 提取真实明文从第20位开始前4位是长度 const msgLen decrypted.readUInt32BE(4); const msg decrypted.slice(8, 8 msgLen).toString(utf8); res.send(msg); });这里有个极易踩的坑EncodingAESKey是43位的Base64字符串需要补一个等号变成长度44才能正确Base64解码。另外AES解密后要去掉填充而且明文格式前面16字节随机数、4字节长度、后面才是真正的回复内容。我第一次写的时候忘了去随机值和长度直接拿整个解密结果当明文结果返回给企业微信的东西多了前缀后台一直提示验证失败。解决这个问题的另一个思路是直接使用官方提供的加解密库。企业微信官方提供了各语言版本的加解密库比如node版本的wecom/crypto用它就不用自己处理这些底层细节了。不过自己实现一遍对理解原理很有帮助出了问题也能排查。4.5 审批事件回调处理配置好URL验证后企业微信会把审批状态变更事件以POST请求推给你的回调地址。POST请求的body是加密的XML解密后XML里会有Event节点。审批相关的Event包括approval_info审批状态变更通知里面有SpNo审批编号、ApprovalStatus1审批通过、2审批驳回、3撤销、ApprovalNode当前节点等。处理流程是先解密XML再根据Event类型走不同分支。router.post(/callback, express.text({ type: text/xml }), async (req, res) { const { msg_signature, timestamp, nonce } req.query; const encryptedMsg req.body; // 验证签名 const arr [TOKEN, timestamp, nonce, encryptedMsg].sort(); const sha1 crypto.createHash(sha1).update(arr.join()).digest(hex); if (sha1 ! msg_signature) { return res.status(401).send(signature error); } try { // 解密 const decryptedXml decrypt(encryptedMsg); // 解析XML里的ToUserName, AgentID, Event, SpNo等字段 // 这里用简易正则提取关键字段生产环境建议用xml2js const event /Event!\[CDATA\[(\w)\]\]\/Event/.exec(decryptedXml); const spNoMatch /SpNo!\[CDATA\[(\w)\]\]\/SpNo/.exec(decryptedXml); const statusMatch /ApprovalStatus(\d)\/ApprovalStatus/.exec(decryptedXml); if (event event[1] approval_info spNoMatch) { const spNo spNoMatch[1]; const approvalStatus statusMatch ? parseInt(statusMatch[1]) : 0; // 更新数据库状态 await updateApprovalStatus(spNo, approvalStatus); // 发送通知给发起人 await notifyApplicant(spNo, approvalStatus); } // 企业微信要求5秒内返回否则会重试 res.send(success); } catch (error) { console.error(回调处理失败, error); res.status(500).send(error); } });需要注意企业微信回调有个超时机制你的服务器必须在5秒内响应success否则企业微信会认为发送失败并重试。未来如果你要在这个回调里做很多耗时操作比如写库、发通知、调第三方API最好先把消息放进队列立即返回success再由worker异步处理。我后来就是这么改的用RabbitMQ或者Redis队列都行。解密后的XML里还包含审批人节点信息。在企业微信的事件回调中approval_info事件的数据结构大致是xml ToUserNamecorp_id/ToUserName AgentID1000002/AgentID Eventapproval_info/Event ApprovalInfo SpNo202101010001/SpNo SpStatus1/SpStatus ApprovalNode NodeStatus1/NodeStatus NodeAttr1/NodeAttr NodeType1/NodeType Items Item ItemStatus1/ItemStatus ItemName张三/ItemName ItemUseridZhangSan/ItemUserid ItemTime1609459200/ItemTime /Item /Items /ApprovalNode /ApprovalInfo /xml这里需要特别区分SpStatus和ApprovalStatus。笔试的时候很容易混淆SpStatus是审批实例的整体状态1审批中、2已通过、3已驳回、4已撤销ApprovalNode里的NodeStatus是节点状态。我之前写的解析逻辑用错了字段导致审批已经通过了系统里还显示审批中排查了半天才发现是字段取错。4.6 消息通知审批通过/驳回后触达发起人审批状态变化后要及时通过各种方式通知发起人。最直接的方式是调用企业微信应用消息接口发送文本卡片消息。接口是POST /cgi-bin/message/send参数包含touser、msgtype、agentid、textcard等。下面是一个发送文本卡片的例子async function notifyApplicant(spNo, status) { const { creator } await getApprovalRecord(spNo); const accessToken await getAccessToken(); const statusText status 1 ? 已通过 : (status 2 ? 已驳回 : 已撤销); const title 审批结果通知; const description 您的审批单 ${spNo} 已${statusText}; await axios.post( https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token${accessToken}, { touser: creator, msgtype: textcard, agentid: process.env.WECOM_AGENT_ID, textcard: { title, description, url: https://yourdomain.com/approval/detail?spNo${spNo}, btntxt: 查看详情 } } ); }这里的url必须使用可信域名下的地址否则在企业微信里点不开。我之前把详情页地址指向内网IP结果审批人收到通知后点击没有任何反应查了半天发现是因为域名不可信。5. 前端模板配置与审批发起页面后端接口就绪后还需要一个让普通员工能发起审批的前端页面。这个页面我做成H5嵌入到企业微信工作台。5.1 模板配置器给管理员用的配置界面管理员需要一个配置页用来创建模板、添加字段、配置节点。我建议做两个页面模板列表页看到所有已创建的模板支持新增、编辑、停用。模板编辑页左侧是表单字段配置区右侧是流程节点配置区。表单字段配置区的核心交互是管理员点“新增字段”选择字段类型文本、数字、金额、日期、单选、多选填写字段名称和字段标识必要时填写选项值。保存后生成field_key对应的控件定义。流程节点配置区稍微复杂一点要支持添加审批节点选择节点类型顺序审批、会签、或签设置审批人可以选指定成员、指定部门负责人、指定角色设置条件基于某个字段的表达式例如amount大于50000才走当前节点前端把配置的数据以JSON格式提交到后端接口后端写入approval_templates和approval_template_fields、approval_nodes三张表。5.2 审批发起页面实现员工在企业微信工作台打开应用后会看到一个模板列表点进具体模板会动态渲染表单。这里用的是简单的JSON渲染方案前端根据template.fields数组生成对应的输入组件。核心的提交逻辑是用ajax调用上面的/approval/submit接口把表单数据post过去。下面是一个简化版HTML页面!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title发起审批/title /head body h1报销申请/h1 form idapprovalForm label金额/labelinput typenumber idamount nameamount label事由/labeltextarea idreason namereason/textarea button typesubmit提交审批/button /form script document.getElementById(approvalForm).addEventListener(submit, async (event) { event.preventDefault(); const formData { amount: document.getElementById(amount).value, reason: document.getElementById(reason).value }; const resp await fetch(/approval/submit, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ templateCode: expense, creator: WangXiaoMing, formData }) }); const data await resp.json(); if (data.success) { alert(提交成功审批编号 data.spNo); } else { alert(提交失败 data.error); } }); /script /body /html这个页面的creator我在demo里写死成WangXiaoMing实际部署时应该从企业微信的登录态获取。怎么拿登录态企业微信提供了OAuth2授权前端跳转到授权链接后端拿code换取用户身份拿到UserID后再发起审批。5.3 移动端适配的注意事项企业微信内置浏览器本质上是基于Chromium内核的对H5的支持还算不错。但有几个细节需要注意页面宽度尽量适配375px左右的屏幕按钮和输入框不能太小。企业微信有自己的底部导航和右上角菜单页面的固定元素要避开这些区域。如果需要调用企业微信JS-SDK的能力比如选人、选部门、打开摄像头需要引入https://res.wx.qq.com/open/js/jweixin-1.2.0.js并完成agentConfig注入。JS-SDK的签名逻辑是后端用corpId、agentId、timestamp、nonceStr、url这些参数计算出签名前端调用wx.agentConfig注册。签名算法跟普通微信JSSDK类似但需要额外的agentConfig加签。这块内容比较细有需要的同学可以单独写一篇审批流里如果只做表单填写不一定要用JSSDK。6. 常见坑位与排查实录按照惯例把我在实际开发中踩过的一些坑整理一下这部分最花时间但也是最有价值的。6.1 可信域名与回调URL的连环坑很多同学配置可信域名时遇到“该域名主体为第三方服务商请使用企业主体域名”的提示下意识以为是企业微信版本问题实际上是因为域名ICP备案主体跟当前企业主体不一致。解决方式就是让域名备案到当前企业名下或者使用企业已有的备案域名子域名。回调URL验证失败最常见的几个原因签名验证代码写错。注意排序是数组sort()不是字符串直接比较。解密后的明文没有去掉随机前缀和长度头。返回了success以外的内容包括返回JSON、返回空字符串。服务器时区不对导致timestamp校验失败其实企业微信没强制校验timestamp但最好保持一致。6.2 审批人参数解析失败创建审批申请时approver数组传的是UserID不是姓名也不是手机号。如果你在后台配置的可见范围不含审批人接口会返回60011之类的错误码。此外如果审批人是部门负责人需要先把部门负责人对应的UserID解析出来再传给接口不能直接传部门ID。解析部门负责人的接口是GET /cgi-bin/user/list?department_idxxxfetch_child0通过department_id拉取成员列表再判断谁是负责人。这个方法在企业微信通讯录只有一个负责人时很有效如果多个负责人会返回一个数组你需要决定取第一个还是全部。6.3 回调事件漏收、重复与加解密出错回调漏收的原因通常是没有在5秒内返回success或者服务器有防火墙拦截了企业微信的IP。处理方式是把企业微信服务器的IP段加到白名单虽然官方没强制要求但能减少很多莫名奇妙的连接超时。重复回调也是常态。企业微信对未收到成功响应的回调会重试多次所以你的回调处理逻辑必须天然幂等。比如更新审批状态前先查一次当前状态如果已经是最终状态就跳过。如果不做幂等同一个审批单被回调了三次数据库里status字段会来回覆盖还可能出现和业务数据不一致的情况。加解密出错最常见的原因就是EncodingAESKey和Token配置不一致。后台配置的EncodingAESKey是43位Base64字符串程序里解码时要加等号签名里用的Token要跟后台完全一致不能多空格。6.4 状态同步与消息通知异常审批已经通过但业务系统没反应或者发起人没收到通知。大概率是回调解析里用错了状态字段。我在前面已经强调过SpStatus和ApprovalStatus、NodeStatus是三个不同的概念我用一张表帮你理清楚字段含义取值SpStatus整个审批单状态1审批中、2已通过、3已驳回、4已撤销ApprovalStatus回调事件中的审批单状态1审批通过、2审批驳回、3撤销NodeStatus当前节点状态1审批中、2已通过、3已驳回这里要提醒的是企业微信回调事件里并没有直接叫ApprovalStatus的字段实际XML里是SpStatus。我在前面的示例代码里统一用了ApprovalStatus作变量名对应到XML字段就是SpStatus。在集成时务必检查你解析的是不是SpStatus别和张三李四的文档搞混。6.5 环境差异与多应用隔离测试环境和生产环境不要共用一个企业微信应用否则会出现测试数据推给真实员工、审批人收到测试通知等事故。我见过最惨的一次是同事在测试环境点了个按钮结果给全公司几百人发了审批通知还是没法撤销的那种。建议做法是申请两个应用一个叫“XX审批流测试”一个叫“XX审批流生产”可见范围分别设为测试部门和生产全体员工。在环境变量里区分WECOM_AGENT_ID和WECOM_SECRET配置中心里也分命名空间。数据库表也都分开测试环境的回调URL指向测试服务器生产环境的回调URL指向生产服务器。7. 安全加固与性能优化建议审批流涉及公司内部敏感数据安全和性能必须重视。7.1 安全基线第一所有回调接口必须验证签名签名算法就是官方文档那一套不要自己发明。第二对所有出口请求校验企业微信返回的errcode非0就要告警。第三AccessToken、Secret、EncodingAESKey等敏感配置绝不能出现在日志里。我曾经在调试时把整个请求对象打印出来结果Token全打到日志里后来改配置才换掉。还需要做好数据权限控制。审批记录表里的apply_data包含员工填写的敏感字段比如身份证号、银行卡号、医疗信息后端查询接口必须校验当前用户是不是审批单的发起人或者审批人否则任何人都能通过接口拉取全部审批数据。7.2 Token缓存、限流与幂等AccessToken缓存我在前面已经给过代码。在企业微信审批流这种场景token是全局公用的多实例部署时建议用Redis避免每个实例各自拉取token导致限流。企业微信接口有频率限制一般调用量不会打满但万一你有批量同步任务最好自己加一个简单的令牌桶限流。审批回调处理要幂等。做法是在approval_records表给sp_no加唯一索引并在更新状态前判断当前状态。如果已经是从终态通过/驳回/撤销回调过来的直接return。还有一种情况是审批通过后又收到驳回回调理论上不可能但防一手按“以最新回调为准”处理。7.3 日志、监控与告警我把审批流的运行日志分成了三类请求日志记录每次审批提交、回调接收的关键参数不记录表单详细内容保护隐私。错误日志记录所有调用企业微信接口失败的返回体、堆栈信息。审计日志记录谁在什么时间发起了什么审批审批状态如何变化这个日志只增不改用于纠纷追溯。监控方面重点监控三个指标审批提交接口的耗时和失败率、回调接收的成功率、审批状态更新的延迟。一旦回调超过5分钟还没有更新某条审批单的状态就触发告警。我还会定期跑一个定时任务把处于“审批中”状态且超过N天没有变化的记录捞出来人工确认是否卡在某个节点上。最后分享一个经验做了几套审批流下来我最大的体会是审批流开发的核心难点不在企业微信接口本身而在于流程数据的建模和边界情况的处理。接口文档写得很清楚照着调就行但“审批通过之后业务系统要做什么”“回调重复发了怎么办”“审批人换了部门怎么处理”这些业务问题才是真正需要花时间设计的。如果你也是第一次接触企业微信审批流我的建议是从一个最简单的单节点审批开始跑通比如“部门经理审批文本字段”先跑通提交、回调、通知闭环再去加会签、条件分支、自定义字段这些进阶功能。直接一步到位做复杂流程出了错你都不知道是模板配错了还是接口调错了。最后再分享一个小技巧企业微信的“审批”应用里其实支持导入外部审批数据但接口文档和历史版本信息都藏得比较深建议你在动手前把官方文档里“OA审批”那一节完整读一遍尤其是“提交审批申请”和“获取审批模板详情”两个接口的参数说明。我就是因为一开始没仔细看apply_data里每个控件的value结构导致提交后审批人看到的内容全是空的排查了很久。 企业微信自定义审批流开发指南：从零搭建到避坑实战
做企业微信审批流开发这事说难不算难说简单也真不简单。我前前后后给三家企业搭过自定义审批模板从刚开始连回调签名验证都调不通到后面把多级审批、条件分支、消息回写全流程跑稳中间踩过的坑差不多能写一本小册子。这篇就把我从零搭建企业微信自定义审批流的完整过程、完整代码、还有那些最容易翻车的细节整理出来给准备自己搞审批流的同学做个参考。这个内容适合谁看两类人。一类是公司内部IT或开发需要把线下的报销、请假、采购、合同流程搬到企业微信上又嫌官方审批后台不够灵活另一类是做企业服务集成的外包或SaaS开发需要把审批能力嵌入到自己的业务系统里。看完你就能自己搭一套带自定义模板、自动回调、状态回写的审批流改改模板ID和字段ID就能适配不同场景。1. 为什么我选择自建审批模板而不是直接套用系统审批很多团队一开始都会纠结企业微信自带的审批功能就能用为什么还要自己开发一套这个问题的答案基本决定了整个项目的技术选型方向。1.1 原生审批的边界在哪里企业微信原生审批系统确实好用打开就能发起请假、报销、补卡审批人也直接在聊天里点一下就行。但一旦业务复杂起来原生审批就开始露怯了。举几个我实际遇到的例子第一个例子是字段联动。我们有个采购流程金额超过五万就要自动追加一个财务总监审批节点金额低于五万只走部门经理就行。原生审批也能配条件分支但条件规则是基于表单字段的固定逻辑业务规则的调整往往要等官方的功能更新不能通过接口动态控制。第二个例子是审批数据要回写业务系统。原生审批结束后数据留在企业微信后台想同步到公司的ERP、OA或者财务软件得靠人工导出或者第三方工具去捞数据再手动对账。我们当时要对接内部预算系统审批结果要实时扣减预算额度这个原生审批完全做不到。第三个例子是流程不可编程。比如审批通过之后自动创建工单、自动发邮件、自动触发下一条流程审批驳回之后自动退回并通知发起人修改。这些“审批之外”的动作原生审批都不支持。你需要一个能跟业务系统对话的审批引擎。1.2 自建审批模板的核心优势自建审批流本质上是把企业微信当作“审批的展示层和触达层”真正的流程逻辑、数据存储、业务联动全部放在自己的服务里。这样做的好处非常直接表单字段完全自定义。文本框、数字框、日期、单选、多选、明细表、图片附件想怎么组合就怎么组合想什么时候加字段就什么时候加字段。审批节点动态计算。审批人可以是固定的人也可以根据表单内容动态算出比如根据金额、部门、城市等条件匹配对应的审批人。审批结果实时回写。审批状态变化通过回调瞬间通知到自己的系统业务数据可以无缝联动。审批流程可版本化。模板可以改版、灰度、回滚这在企业制度频繁变动的环境下非常有用。1.3 系统整体架构设计我建议的整体架构是企业微信管理后台创建一个自建应用应用里配置审批模板业务后端服务负责三件事第一是维护模板和流程配置的数据表第二是调用企业微信API发起审批第三是接收企业微信的审批事件回调并更新状态前端则提供一个H5页面嵌入到企业微信工作台用来发起审批和查看我的申请。选择后端技术栈时我用的是Node.js Express因为公司现有团队偏JavaScript方向。你完全可以用Python Flask、Java Spring Boot、Go Gin替换核心逻辑是一样的只是企业微信接口调用方式略有差异。这里有个重要的设计原则不要把所有逻辑都塞在回调处理函数里。因为企业微信回调可能乱序、重复、甚至延迟我后来把回调消息先写入队列再异步处理保证审批状态最终一致。这个后面会详细说。2. 前置准备企业微信应用、可信域名与API权限开始写代码之前必须先在企业微信管理后台把应用的“地基”打牢。很多审批流开发做到一半突然卡壳回头一看全是配置问题。2.1 创建自建应用与获取基础凭证登录企业微信管理后台进入“应用管理” - “自建应用” - “创建应用”填上应用名称和 Logo创建完成后你会拿到两个关键信息AgentId 和 Secret。另外还要在企业信息里找到 CorpId这三个值基本上贯穿整个开发过程。创建应用后默认只有基础权限调用审批相关接口需要额外申请接口权限。在“应用管理”里找到你的自建应用进入“API权限”把以下权限加进去审批获取审批模板详情、提交审批申请、获取审批申请详情、获取审批数据通讯录读取成员、读取部门用于解析审批人消息推送发送应用消息用于通知审批人这里要提醒一下Secret和AgentId不要在代码里写死建议放在环境变量或配置中心。因为Secret一旦泄漏别人就能拿它调用你的企业接口风险非常大。我见过有人把Secret直接提交到Git仓库结果整个企业通讯录都被拉走教训很深。2.2 可信域名与回调URL配置一字之差就是千古恨这是审批流开发中踩坑率最高的环节。很多热词搜索里也常看到“可信域名”相关的问题比如“该域名主体为第三方服务商请使用企业主体域名”这个提示的意思就是你配置的域名没有通过企业微信的可信域名校验。企业微信要求所有需要调用JS-SDK的页面域名以及接收回调的URL域名都必须先完成域名归属验证。具体的配置路径是“应用管理” - 你的自建应用 - “网页应用及JS-SDK” - “可信域名”。配置可信域名有几个硬性要求域名必须是企业主体名下的且已经完成ICP备案。第三方服务商的域名不能用。域名必须支持HTTPS访问证书有效。必须下载企业微信提供的校验文件放到域名根目录下确认能通过外网访问。回调URL的配置在“接收消息”里需要填一个完整的URL比如https://yourdomain.com/wecom/callback同时设置Token和EncodingAESKey。这里的Token和EncodingAESKey是回调加解密用的跟业务Token完全是两回事后面代码里会用到。需要特别说明的是回调URL和可信域名是两套体系即使回调URL配了JS-SDK的页面访问还是需要可信域名即使可信域名通过也不代表回调就能通。我见过不少同学在这两个地方来回改结果一个是校验文件没放对另一个是回调URL路径写错。2.3 权限范围与通讯录同步自建应用默认只能看到部分通讯录信息。如果审批流里需要按照部门找审批人或者要读取成员UserID就必须在“权限管理”里把通讯录权限设为“企业通讯录”或者至少“自建应用可见范围”包含对应的部门和成员。这一步的坑在于应用可见范围直接决定了“谁能看到这个应用”也决定了接口能拉到哪些人。如果你把可见范围设成某个部门但审批流程里却要选另一个部门的经理接口会返回“userid不存在”或者权限不足。我当时就在这卡了半天最后才发现是可见范围没包含审批人所在的部门。3. 数据模型与流程引擎设计先把表结构想清楚代码是表象数据模型才是审批流的灵魂。如果表结构设计得不好后面加需求改流程会非常痛苦。3.1 审批模板与字段表设计我设计了四张核心表模板表、字段表、节点表、审批记录表。模板表approval_templates用来存模板基础信息字段名类型说明idint主键template_namevarchar模板名称wecom_template_idvarchar企业微信审批模板IDcreatorvarchar创建人UserIDstatustinyint启用/停用created_atdatetime创建时间字段表approval_template_fields用来存模板的表单字段定义字段名类型说明idint主键template_idint关联模板表field_keyvarchar字段标识如amountfield_namevarchar字段显示名如报销金额field_typevarcharText/Textarea/Number/Date/Select/Moneyrequiredtinyint是否必填optionstext单选/多选的选项JSON格式sortint排序节点表approval_nodes用来定义审批流程字段名类型说明idint主键template_idint关联模板表node_namevarchar节点名称如部门经理审批node_typetinyint1顺序审批 2会签 3或签approver_typevarcharuser指定人/role角色/dept部门负责人approver_valuevarchar审批人的UserID或部门IDcondition_exprtext可选节点生效条件如amount 50000sortint节点顺序审批记录表approval_records用来存审批实例状态字段名类型说明idint主键sp_novarchar企业微信审批编号template_idint模板IDcreatorvarchar发起人UserIDcurrent_statustinyint审批中/通过/驳回/撤销apply_datatext提交的表单数据JSON格式callback_datatext回调原始数据JSON格式created_atdatetime创建时间updated_atdatetime更新时间3.2 审批节点类型与执行规则审批节点这块我用一个例子来说明。假设报销流程是这样的金额小于5000元只需要直属上级审批金额在5000元到50000元之间需要部门经理审批金额超过50000元需要部门经理和财务总监都审批。对应到表结构我会有三个节点节点1条件amount 5000审批人为直属上级节点2条件amount 5000 amount 50000审批人为部门经理节点3条件amount 50000节点类型为会签审批人为部门经理和财务总监注意企业微信创建审批模板的时候本身就支持配置审批人但如果你完全依赖企业微信的审批模板配置去做条件分支那你仍然没法把“审批结果回写业务系统”“自动触发后续动作”这些逻辑接进来。所以我自己的做法是企业微信那边只配一个“通用审批模板”所有自定义逻辑都放在自己的节点表里通过代码决定传给企业微信的审批人究竟是谁。这样做有个好处企业微信那边只当它是普通的审批流而真正的流程规则掌握在自己手里。后续改流程只需要改数据库不用去企业微信后台改模板也不用重新发布应用。3.3 审批状态机设计审批状态我统一用如下状态0审批中1审批通过2审批驳回3审批撤销审批中的记录可能经历节点推进比如从“部门经理审批中”变成“财务审批中”这个中间态可以单独用current_node字段记录不必给每个节点都设计一个状态位。状态流转只发生在三个地方提交时设为审批中回调里收到审批结果为通过/驳回时更新主动撤销时设为撤销。这里有个细节企业微信回调里审批通过和审批驳回对应的事件是不同的审批驳回时可以附上审批意见在向发起人发送通知时要把审批意见一起带过去否则发起人只知道被拒了不知道原因。4. 后端接口实现从Token管理到回调加解密下面进入核心代码实现。为了让你能直接跑通我把代码拆成几个模块工具函数、提交审批接口、回调处理接口。我用Node.js Express实现依赖包只用了express、axios和cryptoNode内置。4.1 环境变量与依赖创建一个项目目录初始化npm并安装依赖mkdir approval-demo cd approval-demo npm init -y npm install express axios在项目根目录创建.env文件填入你的企业微信配置WECOM_CORP_IDww1234567890 WECOM_AGENT_ID1000002 WECOM_SECRETyour_secret_here WECOM_CALLBACK_TOKENyour_token WECOM_CALLBACK_ENCODING_AES_KEYyour_encoding_aes_key这里说一下EncodingAESKey在企业微信后台生成是一个43位的字符串Base64解码后是32字节用来做AES加解密。Token是任意字符串用于签名验证。两个值都要妥善保管。4.2 AccessToken管理必须缓存不能每次现取企业微信接口调用都需要AccessToken获取接口在https://qyapi.weixin.qq.com/cgi-bin/gettoken参数是corpid和corpsecret。AccessToken有效期默认7200秒但企业微信官方要求必须缓存不建议频繁请求。我封装了一个带缓存的获取函数// utils/wecom.js const axios require(axios); const CORP_ID process.env.WECOM_CORP_ID; const SECRET process.env.WECOM_SECRET; let accessTokenCache { token: , expiresAt: 0 }; async function getAccessToken() { // 如果token还没过期直接用缓存 if (accessTokenCache.token Date.now() accessTokenCache.expiresAt - 300000) { return accessTokenCache.token; } const url https://qyapi.weixin.qq.com/cgi-bin/gettoken; const resp await axios.get(url, { params: { corpid: CORP_ID, corpsecret: SECRET } }); if (resp.data.errcode ! 0) { throw new Error(获取access_token失败: ${JSON.stringify(resp.data)}); } accessTokenCache.token resp.data.access_token; // 有效期是7200秒提前300秒过期保证安全 accessTokenCache.expiresAt Date.now() resp.data.expires_in * 1000; return accessTokenCache.token; } module.exports { getAccessToken };这里减300秒是为了避免token恰好在使用时过期。在多实例部署时建议用Redis缓存这个token因为它天然是全局共享的。4.3 提交审批申请接口企业微信创建审批申请的接口是POST /cgi-bin/oa/applyevent请求体中模板ID、发起人、审批人、表单内容都要传。我写了一个提交审批的路由前端传过来一个模板标识和表单数据后端根据模板配置解析出企业微信模板ID、审批人列表再拼装请求体。// routes/approval.js const express require(express); const axios require(axios); const { getAccessToken } require(../utils/wecom); const { getTemplateConfig, buildApplyData } require(../services/approvalService); const router express.Router(); router.post(/submit, async (req, res) { try { const { templateCode, creator, formData } req.body; // 1. 从数据库读取模板配置省略SQL用函数代替 const template await getTemplateConfig(templateCode); // 2. 根据表单数据和节点条件计算实际审批人 const approvers template.nodes .filter(node evalNodeCondition(node.condition_expr, formData)) // 实际生产请用规则引擎避免eval .map(node node.approver_value); // 3. 去重并拼成数组 const approverList [...new Set(approvers)]; // 4. 构造apply_data const applyData buildApplyData(template.fields, formData); // 5. 调用企业微信接口 const accessToken await getAccessToken(); const resp await axios.post( https://qyapi.weixin.qq.com/cgi-bin/oa/applyevent?access_token${accessToken}, { creator_userid: creator, template_id: template.wecom_template_id, use_template_approver: 0, approver: approverList, apply_data: { contents: applyData }, summary_list: [ { summary_info: [ { text: template.template_name, lang: zh_CN } ] } ] } ); if (resp.data.errcode ! 0) { return res.status(500).json({ success: false, error: resp.data }); } // 6. 把审批编号存库这个编号用于后续回调关联 const spNo resp.data.sp_no; await saveApprovalRecord({ spNo, templateCode, creator, formData, status: 0 }); res.json({ success: true, spNo }); } catch (error) { console.error(提交审批失败, error); res.status(500).json({ success: false, error: error.message }); } }); module.exports router;buildApplyData这一层是重点。企业微信的表单控件类型很多每种控件对应的数据结构都不一样。我封装了一个映射函数// services/approvalService.js function buildApplyData(fields, formData) { return fields.map(field { const value formData[field.field_key]; switch (field.field_type) { case Text: return { control: Text, id: field.wecom_control_id, // 需要从企业微信模板详情里拿到控件ID value: { text: value || } }; case Textarea: return { control: Textarea, id: field.wecom_control_id, value: { text: value || } }; case Number: return { control: Number, id: field.wecom_control_id, value: { new_number: value || 0 } }; case Money: return { control: Money, id: field.wecom_control_id, value: { new_money: value || 0 } }; case Date: return { control: Date, id: field.wecom_control_id, value: { new_date: value } }; case Select: return { control: Select, id: field.wecom_control_id, value: { select: { options: [{ key: value }] } } }; default: return null; } }).filter(Boolean); }注意这里的wecom_control_id不是你自己定义的字段标识而是企业微信审批模板里每个控件的唯一ID。获取方式有两个一是调用“获取审批模板详情”接口传template_id接口会返回模板的所有控件及其ID和属性名二是直接在企业微信后台编辑审批模板时浏览器控制台可以看到每个控件的id。更推荐第一种自动化处理才不会出错。4.4 回调接收与验证最难啃的骨头回调接收是企业微信审批流开发中最容易出问题的地方。企业微信服务器收到审批状态变更后会向你的回调URL发POST请求。请求参数包括msg_signature、timestamp、nonce和echostr首次验证时才有echostrbody是加密的XML。先处理关键的URL验证阶段。当你第一次在后台配置回调URL时企业微信会向你的URL发一个GET请求带timestamp、nonce、echostr三个参数你需要用msg_signature验证后解密echostr返回明文内容给企业微信配置才能生效。代码如下// routes/callback.js const express require(express); const crypto require(crypto); const router express.Router(); const TOKEN process.env.WECOM_CALLBACK_TOKEN; const AES_KEY process.env.WECOM_CALLBACK_ENCODING_AES_KEY; // 把EncodingAESKey解码为Buffer取前16字节作为AES IV const encodingAESKey Buffer.from(AES_KEY , base64); const key encodingAESKey; const iv key.slice(0, 16); // 签名验证 function verifySignature(msgSignature, timestamp, nonce, echostr) { const arr [TOKEN, timestamp, nonce, echostr].sort(); const str arr.join(); const sha1 crypto.createHash(sha1).update(str).digest(hex); return sha1 msgSignature; } // AES解密 function decrypt(encrypted) { const decipher crypto.createDecipheriv(aes-256-cbc, key, iv); decipher.setAutoPadding(false); let decrypted Buffer.concat([ decipher.update(encrypted, base64), decipher.final() ]); // PKCS7去掉填充 const padSize decrypted[decrypted.length - 1]; decrypted decrypted.slice(0, decrypted.length - padSize); return decrypted.toString(utf8); } // 处理URL验证 router.get(/callback, (req, res) { const { msg_signature, timestamp, nonce, echostr } req.query; if (!verifySignature(msg_signature, timestamp, nonce, echostr)) { return res.status(401).send(signature error); } // 密文格式为随机16字节 4字节网络序长度 明文 receiveid const decrypted decrypt(echostr); // 提取真实明文从第20位开始前4位是长度 const msgLen decrypted.readUInt32BE(4); const msg decrypted.slice(8, 8 msgLen).toString(utf8); res.send(msg); });这里有个极易踩的坑EncodingAESKey是43位的Base64字符串需要补一个等号变成长度44才能正确Base64解码。另外AES解密后要去掉填充而且明文格式前面16字节随机数、4字节长度、后面才是真正的回复内容。我第一次写的时候忘了去随机值和长度直接拿整个解密结果当明文结果返回给企业微信的东西多了前缀后台一直提示验证失败。解决这个问题的另一个思路是直接使用官方提供的加解密库。企业微信官方提供了各语言版本的加解密库比如node版本的wecom/crypto用它就不用自己处理这些底层细节了。不过自己实现一遍对理解原理很有帮助出了问题也能排查。4.5 审批事件回调处理配置好URL验证后企业微信会把审批状态变更事件以POST请求推给你的回调地址。POST请求的body是加密的XML解密后XML里会有Event节点。审批相关的Event包括approval_info审批状态变更通知里面有SpNo审批编号、ApprovalStatus1审批通过、2审批驳回、3撤销、ApprovalNode当前节点等。处理流程是先解密XML再根据Event类型走不同分支。router.post(/callback, express.text({ type: text/xml }), async (req, res) { const { msg_signature, timestamp, nonce } req.query; const encryptedMsg req.body; // 验证签名 const arr [TOKEN, timestamp, nonce, encryptedMsg].sort(); const sha1 crypto.createHash(sha1).update(arr.join()).digest(hex); if (sha1 ! msg_signature) { return res.status(401).send(signature error); } try { // 解密 const decryptedXml decrypt(encryptedMsg); // 解析XML里的ToUserName, AgentID, Event, SpNo等字段 // 这里用简易正则提取关键字段生产环境建议用xml2js const event /Event!\[CDATA\[(\w)\]\]\/Event/.exec(decryptedXml); const spNoMatch /SpNo!\[CDATA\[(\w)\]\]\/SpNo/.exec(decryptedXml); const statusMatch /ApprovalStatus(\d)\/ApprovalStatus/.exec(decryptedXml); if (event event[1] approval_info spNoMatch) { const spNo spNoMatch[1]; const approvalStatus statusMatch ? parseInt(statusMatch[1]) : 0; // 更新数据库状态 await updateApprovalStatus(spNo, approvalStatus); // 发送通知给发起人 await notifyApplicant(spNo, approvalStatus); } // 企业微信要求5秒内返回否则会重试 res.send(success); } catch (error) { console.error(回调处理失败, error); res.status(500).send(error); } });需要注意企业微信回调有个超时机制你的服务器必须在5秒内响应success否则企业微信会认为发送失败并重试。未来如果你要在这个回调里做很多耗时操作比如写库、发通知、调第三方API最好先把消息放进队列立即返回success再由worker异步处理。我后来就是这么改的用RabbitMQ或者Redis队列都行。解密后的XML里还包含审批人节点信息。在企业微信的事件回调中approval_info事件的数据结构大致是xml ToUserNamecorp_id/ToUserName AgentID1000002/AgentID Eventapproval_info/Event ApprovalInfo SpNo202101010001/SpNo SpStatus1/SpStatus ApprovalNode NodeStatus1/NodeStatus NodeAttr1/NodeAttr NodeType1/NodeType Items Item ItemStatus1/ItemStatus ItemName张三/ItemName ItemUseridZhangSan/ItemUserid ItemTime1609459200/ItemTime /Item /Items /ApprovalNode /ApprovalInfo /xml这里需要特别区分SpStatus和ApprovalStatus。笔试的时候很容易混淆SpStatus是审批实例的整体状态1审批中、2已通过、3已驳回、4已撤销ApprovalNode里的NodeStatus是节点状态。我之前写的解析逻辑用错了字段导致审批已经通过了系统里还显示审批中排查了半天才发现是字段取错。4.6 消息通知审批通过/驳回后触达发起人审批状态变化后要及时通过各种方式通知发起人。最直接的方式是调用企业微信应用消息接口发送文本卡片消息。接口是POST /cgi-bin/message/send参数包含touser、msgtype、agentid、textcard等。下面是一个发送文本卡片的例子async function notifyApplicant(spNo, status) { const { creator } await getApprovalRecord(spNo); const accessToken await getAccessToken(); const statusText status 1 ? 已通过 : (status 2 ? 已驳回 : 已撤销); const title 审批结果通知; const description 您的审批单 ${spNo} 已${statusText}; await axios.post( https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token${accessToken}, { touser: creator, msgtype: textcard, agentid: process.env.WECOM_AGENT_ID, textcard: { title, description, url: https://yourdomain.com/approval/detail?spNo${spNo}, btntxt: 查看详情 } } ); }这里的url必须使用可信域名下的地址否则在企业微信里点不开。我之前把详情页地址指向内网IP结果审批人收到通知后点击没有任何反应查了半天发现是因为域名不可信。5. 前端模板配置与审批发起页面后端接口就绪后还需要一个让普通员工能发起审批的前端页面。这个页面我做成H5嵌入到企业微信工作台。5.1 模板配置器给管理员用的配置界面管理员需要一个配置页用来创建模板、添加字段、配置节点。我建议做两个页面模板列表页看到所有已创建的模板支持新增、编辑、停用。模板编辑页左侧是表单字段配置区右侧是流程节点配置区。表单字段配置区的核心交互是管理员点“新增字段”选择字段类型文本、数字、金额、日期、单选、多选填写字段名称和字段标识必要时填写选项值。保存后生成field_key对应的控件定义。流程节点配置区稍微复杂一点要支持添加审批节点选择节点类型顺序审批、会签、或签设置审批人可以选指定成员、指定部门负责人、指定角色设置条件基于某个字段的表达式例如amount大于50000才走当前节点前端把配置的数据以JSON格式提交到后端接口后端写入approval_templates和approval_template_fields、approval_nodes三张表。5.2 审批发起页面实现员工在企业微信工作台打开应用后会看到一个模板列表点进具体模板会动态渲染表单。这里用的是简单的JSON渲染方案前端根据template.fields数组生成对应的输入组件。核心的提交逻辑是用ajax调用上面的/approval/submit接口把表单数据post过去。下面是一个简化版HTML页面!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title发起审批/title /head body h1报销申请/h1 form idapprovalForm label金额/labelinput typenumber idamount nameamount label事由/labeltextarea idreason namereason/textarea button typesubmit提交审批/button /form script document.getElementById(approvalForm).addEventListener(submit, async (event) { event.preventDefault(); const formData { amount: document.getElementById(amount).value, reason: document.getElementById(reason).value }; const resp await fetch(/approval/submit, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ templateCode: expense, creator: WangXiaoMing, formData }) }); const data await resp.json(); if (data.success) { alert(提交成功审批编号 data.spNo); } else { alert(提交失败 data.error); } }); /script /body /html这个页面的creator我在demo里写死成WangXiaoMing实际部署时应该从企业微信的登录态获取。怎么拿登录态企业微信提供了OAuth2授权前端跳转到授权链接后端拿code换取用户身份拿到UserID后再发起审批。5.3 移动端适配的注意事项企业微信内置浏览器本质上是基于Chromium内核的对H5的支持还算不错。但有几个细节需要注意页面宽度尽量适配375px左右的屏幕按钮和输入框不能太小。企业微信有自己的底部导航和右上角菜单页面的固定元素要避开这些区域。如果需要调用企业微信JS-SDK的能力比如选人、选部门、打开摄像头需要引入https://res.wx.qq.com/open/js/jweixin-1.2.0.js并完成agentConfig注入。JS-SDK的签名逻辑是后端用corpId、agentId、timestamp、nonceStr、url这些参数计算出签名前端调用wx.agentConfig注册。签名算法跟普通微信JSSDK类似但需要额外的agentConfig加签。这块内容比较细有需要的同学可以单独写一篇审批流里如果只做表单填写不一定要用JSSDK。6. 常见坑位与排查实录按照惯例把我在实际开发中踩过的一些坑整理一下这部分最花时间但也是最有价值的。6.1 可信域名与回调URL的连环坑很多同学配置可信域名时遇到“该域名主体为第三方服务商请使用企业主体域名”的提示下意识以为是企业微信版本问题实际上是因为域名ICP备案主体跟当前企业主体不一致。解决方式就是让域名备案到当前企业名下或者使用企业已有的备案域名子域名。回调URL验证失败最常见的几个原因签名验证代码写错。注意排序是数组sort()不是字符串直接比较。解密后的明文没有去掉随机前缀和长度头。返回了success以外的内容包括返回JSON、返回空字符串。服务器时区不对导致timestamp校验失败其实企业微信没强制校验timestamp但最好保持一致。6.2 审批人参数解析失败创建审批申请时approver数组传的是UserID不是姓名也不是手机号。如果你在后台配置的可见范围不含审批人接口会返回60011之类的错误码。此外如果审批人是部门负责人需要先把部门负责人对应的UserID解析出来再传给接口不能直接传部门ID。解析部门负责人的接口是GET /cgi-bin/user/list?department_idxxxfetch_child0通过department_id拉取成员列表再判断谁是负责人。这个方法在企业微信通讯录只有一个负责人时很有效如果多个负责人会返回一个数组你需要决定取第一个还是全部。6.3 回调事件漏收、重复与加解密出错回调漏收的原因通常是没有在5秒内返回success或者服务器有防火墙拦截了企业微信的IP。处理方式是把企业微信服务器的IP段加到白名单虽然官方没强制要求但能减少很多莫名奇妙的连接超时。重复回调也是常态。企业微信对未收到成功响应的回调会重试多次所以你的回调处理逻辑必须天然幂等。比如更新审批状态前先查一次当前状态如果已经是最终状态就跳过。如果不做幂等同一个审批单被回调了三次数据库里status字段会来回覆盖还可能出现和业务数据不一致的情况。加解密出错最常见的原因就是EncodingAESKey和Token配置不一致。后台配置的EncodingAESKey是43位Base64字符串程序里解码时要加等号签名里用的Token要跟后台完全一致不能多空格。6.4 状态同步与消息通知异常审批已经通过但业务系统没反应或者发起人没收到通知。大概率是回调解析里用错了状态字段。我在前面已经强调过SpStatus和ApprovalStatus、NodeStatus是三个不同的概念我用一张表帮你理清楚字段含义取值SpStatus整个审批单状态1审批中、2已通过、3已驳回、4已撤销ApprovalStatus回调事件中的审批单状态1审批通过、2审批驳回、3撤销NodeStatus当前节点状态1审批中、2已通过、3已驳回这里要提醒的是企业微信回调事件里并没有直接叫ApprovalStatus的字段实际XML里是SpStatus。我在前面的示例代码里统一用了ApprovalStatus作变量名对应到XML字段就是SpStatus。在集成时务必检查你解析的是不是SpStatus别和张三李四的文档搞混。6.5 环境差异与多应用隔离测试环境和生产环境不要共用一个企业微信应用否则会出现测试数据推给真实员工、审批人收到测试通知等事故。我见过最惨的一次是同事在测试环境点了个按钮结果给全公司几百人发了审批通知还是没法撤销的那种。建议做法是申请两个应用一个叫“XX审批流测试”一个叫“XX审批流生产”可见范围分别设为测试部门和生产全体员工。在环境变量里区分WECOM_AGENT_ID和WECOM_SECRET配置中心里也分命名空间。数据库表也都分开测试环境的回调URL指向测试服务器生产环境的回调URL指向生产服务器。7. 安全加固与性能优化建议审批流涉及公司内部敏感数据安全和性能必须重视。7.1 安全基线第一所有回调接口必须验证签名签名算法就是官方文档那一套不要自己发明。第二对所有出口请求校验企业微信返回的errcode非0就要告警。第三AccessToken、Secret、EncodingAESKey等敏感配置绝不能出现在日志里。我曾经在调试时把整个请求对象打印出来结果Token全打到日志里后来改配置才换掉。还需要做好数据权限控制。审批记录表里的apply_data包含员工填写的敏感字段比如身份证号、银行卡号、医疗信息后端查询接口必须校验当前用户是不是审批单的发起人或者审批人否则任何人都能通过接口拉取全部审批数据。7.2 Token缓存、限流与幂等AccessToken缓存我在前面已经给过代码。在企业微信审批流这种场景token是全局公用的多实例部署时建议用Redis避免每个实例各自拉取token导致限流。企业微信接口有频率限制一般调用量不会打满但万一你有批量同步任务最好自己加一个简单的令牌桶限流。审批回调处理要幂等。做法是在approval_records表给sp_no加唯一索引并在更新状态前判断当前状态。如果已经是从终态通过/驳回/撤销回调过来的直接return。还有一种情况是审批通过后又收到驳回回调理论上不可能但防一手按“以最新回调为准”处理。7.3 日志、监控与告警我把审批流的运行日志分成了三类请求日志记录每次审批提交、回调接收的关键参数不记录表单详细内容保护隐私。错误日志记录所有调用企业微信接口失败的返回体、堆栈信息。审计日志记录谁在什么时间发起了什么审批审批状态如何变化这个日志只增不改用于纠纷追溯。监控方面重点监控三个指标审批提交接口的耗时和失败率、回调接收的成功率、审批状态更新的延迟。一旦回调超过5分钟还没有更新某条审批单的状态就触发告警。我还会定期跑一个定时任务把处于“审批中”状态且超过N天没有变化的记录捞出来人工确认是否卡在某个节点上。最后分享一个经验做了几套审批流下来我最大的体会是审批流开发的核心难点不在企业微信接口本身而在于流程数据的建模和边界情况的处理。接口文档写得很清楚照着调就行但“审批通过之后业务系统要做什么”“回调重复发了怎么办”“审批人换了部门怎么处理”这些业务问题才是真正需要花时间设计的。如果你也是第一次接触企业微信审批流我的建议是从一个最简单的单节点审批开始跑通比如“部门经理审批文本字段”先跑通提交、回调、通知闭环再去加会签、条件分支、自定义字段这些进阶功能。直接一步到位做复杂流程出了错你都不知道是模板配错了还是接口调错了。最后再分享一个小技巧企业微信的“审批”应用里其实支持导入外部审批数据但接口文档和历史版本信息都藏得比较深建议你在动手前把官方文档里“OA审批”那一节完整读一遍尤其是“提交审批申请”和“获取审批模板详情”两个接口的参数说明。我就是因为一开始没仔细看apply_data里每个控件的value结构导致提交后审批人看到的内容全是空的排查了很久。