做企业微信二次开发这件事我踩了不少坑也总结了不少经验。这篇东西不打算写成官方文档的复读机就按我实际走过来的路子从接口测试怎么玩到正式接入要准备哪些东西一条线讲清楚。适合刚接手企微开发、脑子里还一团浆糊的新手也适合已经写完demo但迟迟不敢上生产的同学参考。企业微信二次开发的核心说白了就是两件事拿到企业微信的能力发消息、读通讯录、建群、审批这些以及让你的服务器能跟企业微信服务器安全地对话。想明白这两点后面所有工作都是在围绕它们展开。1. 动手前的思路梳理先搞清楚你要做的是哪一种企微开发很多新手上来就急着看接口文档我觉得这是最大的误区。企业微信开放的能力很大你一上来根本不知道该看哪个接口。我建议先退一步把自己的需求想清楚。1.1 先判断场景自建应用、机器人、webhook还是审批流我见过的大多数需求其实都能归到下面这几类里消息推送类最常见。服务器产生告警、订单通知、日报提醒通过企业微信推给指定成员或群。这类用自建应用的“发送应用消息”接口或者群机器人webhook几分钟就能跑通。数据交互类需要把企业微信的数据拉回来比如同步通讯录、获取打卡记录、读取审批单详情。这类要用到通讯录管理、审批等API权限要求更高。交互操作类用户在企微里点按钮、填表单你的后台要响应。这类必须配置回调URL涉及消息接收和加解密难度一下子提上来了。页面集成类把已有的H5系统塞进企业微信工作台用户免登录打开。这类主要涉及OAuth2网页授权、JS-SDK签名倒不复杂但细节多。拿到需求先分类再把对应的接口清单列出来后面一步一步就能走通。比如你只是想弄个告警机器人那就完全不用碰回调加解密别自己吓自己。1.2 技术方案选型先别纠结语言关键是搞懂官方API结构企业微信官方提供了Java、Python、PHP、Go等语言的SDK但说实话官方SDK更新慢、封装的水平也一般。我更推荐新手直接用HTTP接口调试等把流程跑通了再看自己项目里要用什么语言封装。原因很简单企业微信的API设计非常规整核心就是“域名 路径 GET/POST参数 JSON请求体”你把一个接口用Postman调通了其他接口基本就是复制粘贴改参数。用官方SDK反而多了一层黑盒出了问题不知道是SDK的问题还是接口的问题。技术选型唯一要提前考虑的是你现有团队的技术栈。比如公司内部全是Java那就用Java做如果你个人维护小工具Python脚本最省事。语言不重要重要的是HTTP请求会发、JSON会解析这两样会了企微开发你就学会了60%。1.3 账号权限和环境规划一个容易被忽略的前置条件正式开发前你要确保自己手上有企业微信管理后台的权限。个人注册的企业微信就能开发不一定非得是企业认证。但有一点非常关键自建应用的Secret只有管理员能查看如果你连管理后台都进不去后面全白搭。我的建议是先注册一个测试企业或者用公司现有的测试企业随便造一个自建应用。把CorpID企业ID和AgentId应用ID、Secret应用密钥三件套记下来这三样就是你所有接口调用的“身份证”。能拿到一个测试成员的UserId方便后面测试发消息。另外要注意环境分离开发环境用测试企业的应用生产环境用正式企业的应用不要混用。因为一旦接口调用有误生产环境的告警消息可能发给所有员工这个事故我见过太多次了。2. 正式开发前的准备工作与接口测试准备工作做得越细后面正式接入越顺。这一节我把从创建应用到接口测试的完整链路拆开讲。2.1 创建自建应用把CorpID、AgentId、Secret一次性拿齐具体操作路径企业微信管理后台 → 应用管理 → 应用 → 自建 → 创建应用。填一个名称和Logo选一个可见范围然后创建。创建完之后应用详情页能看到AgentId和Secret企业管理后台的“我的企业”里能看到CorpID。这里有两个易错点Secret只显示一次。第一次点开看的时候赶紧复制保存到密码管理器里。我见过不少人当时没存后来只能重置Secret重置后原来的Secret立即失效正在跑的服务直接歇菜。可见范围别选“所有人”。开发阶段选几个测试成员就够了不然你测试发消息全公司的人都收到了非常尴尬。创建好应用之后建议先把通讯录的“读取成员信息”权限勾上。后面你经常需要根据手机号或姓名反查UserId没这个权限寸步难行。2.2 用Postman/Apifox调通第一个接口获取access_token企业微信几乎所有接口都要带access_token所以成功拿到token是你迈过新手门槛的第一步。接口如下GET https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpidCORPIDcorpsecretSECRET用Postman或者Apifox建一个GET请求把上面的占位符换成你的真实值发送。正常返回{ errcode: 0, errmsg: ok, access_token: xxxxxx, expires_in: 7200 }看到errcode: 0就说明你成功了。如果报40013之类的错误码大概率是corpid或secret复制错了回去检查。注意token有效期是7200秒2小时而且企业微信对获取token的接口有频率限制。千万不能每次发消息都调一次gettoken否则后面会被限流。正确做法是把token缓存起来等快过期了再刷新。我用Apifox测接口主要是因为它能把环境变量管理的很好。比如我定义base_url、corpid、secret这些变量在请求里用{{corpid}}引用换企业环境的时候只需要改变量不用改测试用例。这一点在用同一个接口文档测试开发环境和生产环境时真的是救命功能。2.3 接口测试怎么测才不算白测断言、错误码和环境隔离很多新手用Postman调通一个接口就觉得自己搞定了其实这是假象。真正的接口测试要覆盖下面几个维度正常参数确认返回结构和预想一致。边界参数比如发消息内容超长、接收人不存在、附件类型错误看看接口怎么报错。鉴权异常带一个错误的token看是否返回40014确认服务端能够正确处理。幂等性同一个请求发两次看会不会造成重复数据比如重复发消息。在Apifox里这些可以通过断言自动验证// 断言HTTP状态码为200 pm.test(Status code is 200, () { pm.response.to.have.status(200); }); // 断言业务错误码为0 pm.test(errcode is 0, () { const jsonData pm.response.json(); pm.expect(jsonData.errcode).to.eql(0); }); // 判断access_token非空 pm.test(access_token exists, () { const jsonData pm.response.json(); pm.expect(jsonData.access_token).to.not.be.empty; });把这些断言保存到接口集合里以后每次改完代码回归一遍心里才有底。我自己习惯用Apifox做接口测试原因很简单它自带环境管理、断言库和文档分享一个工具全干了。Postman也行看你团队习惯。这里必须提醒一个老生常谈但总有人踩的坑千万不能在测试环境里调正式企业的接口。我曾见过有人把测试脚本里的corpid改成了正式企业的结果测试消息发给全员差点出事。测试环境和生产环境的凭据一定要物理隔离。3. 从接口测试到核心功能实现接口测试跑通了接下来要处理的就是把几个核心能力真正用起来。我按消息发送、回调接收、页面接入三个方向分别说。3.1 发送应用消息文本、markdown、图文卡片发送应用消息是所有企微开发里最常用的接口没有之一。请求地址POST https://qyapi.weixin.qq.com/cgi-bin/message/send?access_tokenACCESS_TOKEN请求体发送文本消息给单个成员{ touser: zhangsan, msgtype: text, agentid: 1000002, text: { content: 你好这是一条来自自建应用的消息 }, safe: 0 }这里面的agentid就是你的自建应用IDtouser对应用户的UserId不是手机号千万别搞错。如果想发给群里可以用totag按标签发或者用群机器人webhook发。Markdown消息是运维告警场景的利器。请求体换一下就行{ touser: zhangsan, msgtype: markdown, agentid: 1000002, markdown: { content: **告警通知**\nCPU使用率超过 90%\n请及时处理 } }在企业微信App里markdown消息会渲染成带格式的样子比纯文本清楚很多。这里有个细节企微的markdown只支持部分语法标题、加粗、引用、链接这些没问题但表格、图片就不行。别拿标准的markdown语法往里糊。图文卡片news类型也很常用适合做报表推送。它支持标题、描述、图片URL和跳转链接用户点一下就能进入你的H5页面{ touser: zhangsan, msgtype: news, agentid: 1000002, news: { articles: [ { title: 日报, description: 今日销售额 10000 元, url: https://example.com/report, picurl: https://example.com/pic.png } ] } }3.2 接收消息与回调URL的部署这是新手最容易卡住的一关如果你只是单向推消息不涉及用户点击交互那你可以跳过这一节。但如果你要做的是回复机器人、审批联动、菜单点击就必须配置回调URL。回调的原理很简单用户在企微里的动作发消息、点菜单、扫码由企业微信服务器转发到你的服务器URL你的服务器收到后返回特定格式的响应。配置路径管理后台 → 自建应用 → API接收消息 → 设置URL、Token、EncodingAESKey。URL是你的服务器上的一个HTTP接口比如https://yourdomain.com/callback。这里有个硬性要求这个URL必须是公网能访问的HTTPS地址而且端口默认是443。开发阶段可以用内网穿透工具临时顶一下但正式环境必须上正式的HTTPS域名。配置的时候企业微信会往你的URL发一条验证请求具体来说是GET请求带上msg_signature、timestamp、nonce、echostr四个参数。你需要用Token和EncodingAESKey做签名校验然后解密echostr把解密后的明文返回给企微服务器才算验证通过。很多新手在这一步就卡死了。我见过最多的报错是signature mismatch也就是签名校验失败。排查思路就三条Token是否跟后台配置的完全一致包括大小写和空格。时间戳和nonce是否用的是企微传过来的原值不能自己造。排序拼接的算法是否跟文档一致sort(token, timestamp, nonce)后拼接再做SHA1。3.3 回调消息加解密的常见坑回调消息的加解密是二次开发里最劝退新手的部分。企业微信用的是AES-CBC加密EncodingAESKey是43位字符解码后就是32字节的AES密钥。加密后的消息体是Base64编码的字符串。官方提供了各语言的加解密库Java和PHP的都有Python的话网上有现成实现但很多是旧版的。我的建议是优先用官方SDK里的加解密工具类不要自己重写。几个实战中容易踩的坑加密消息体里有个20字节的random前缀解密后要做截取很多人解密出来一堆乱码就是忘了处理前缀。AES-CBC的IV是密钥的前16位不是全零。企微回调的消息体加密跟公众号的加密格式类似但密钥算法有差异别混用。如果你做的是Python开发解密核心逻辑大概是这个流程# 这里只列关键流程需要结合官方算法实现 # 1. 从EncodingAESKey做base64解码得到AESKey # 2. 用AESKey的前16字节作为IV # 3. 对密文做AES-256-CBC解密 # 4. 去掉前20字节的random # 5. 接下来的4字节是明文的长度网络字节序 # 6. 从第24字节开始才是真正的明文字符串 # 7. 尾部可能有padding需要去掉这个流程看起来不难但手写很容易漏掉细节。所以我才反复说能用官方库就用官方库。3.4 部门、成员、H5应用等扩展场景消息做通了其他功能就比较顺手了。我再补充几个常用场景的注意点通讯录同步接口是/cgi-bin/user/list可以拉取部门成员列表。这里的坑是分页逻辑企微返回的成员数量可能会多需要遍历所有部门ID拉取后合并去重。另外通讯录接口的权限跟自建应用可见范围绑定看不到的人拉不到这是正常现象不是Bug。OAuth2网页授权H5页面要拿用户身份走的是企微的OAuth2流程。核心逻辑是先让用户访问授权链接企微跳转回你的回调URL并带上code你用code换UserId再用UserId反查用户详情。这里记得code有效期只有5分钟而且只能换一次用完就失效。文件与素材上传发图片、文件消息前需要先把素材上传到企微临时素材库拿到media_id后再发消息。临时素材有效期是3天所以正式业务里图片不能只依赖这个长期存储还是得放自己的OSS。4. 正式接入的完整落地清单测试环境怎么玩都行一旦要上正式环境就要按生产标准来要求自己。这一节我列一个从测试切到正式接入的完整checklist。4.1 从测试环境切到正式环境的配置梳理正式接入不是把测试代码里的corpid换一下就完事的建议按下面的顺序逐项检查域名与HTTPS证书回调URL必须换成你正式的域名证书要有效不能用自签名证书企微服务器不认。应用信息在正式企业里重新创建自建应用拿新的AgentId和Secret。旧测试应用的密码要重置防止有人拿测试凭据访问正式环境。IP白名单企微后台可以给应用配置可信IP配置后只有这些IP能调用API。这是个很好的安全边界建议把服务器出口IP加上开发机IP不要加。可见范围从测试成员扩大到正式员工分批次加先加几个部门试点没问题再全量。素材改用正式地址图片、视频、文件都要换成正式环境的可访问URL不能用本地的localhost。4.2 权限最小化与安全实践企业微信的权限模型是“应用 权限”的二维结构。每个应用可以单独开设权限范围你不需要给所有应用都开全部的API权限。我的建议是消息应用只开发送消息权限不开通讯录编辑权限。需要读取通讯录时只开“读取成员基本信息”不要开“编辑”。如果应用不需要上传素材就别勾选素材权限。还有一个细节Secret的管理。企微支持一个应用生成多个Secret不同Secret可以负责不同功能模块。比如一个Secret专门发消息另一个专门读通讯录就算一个泄露了影响范围也有限。同时要定期轮换Secret这个很多团队都会忽略。企微还支持“企业微信插件”和“小程序”等不同的接入形态权限体系略有差别。如果你对接的是微信插件就还要考虑微信端的用户身份映射复杂度会高一截。新手建议先把标准API吃透再考虑这些扩展形态。4.3 上线前的自测清单照着跑一遍再发版我每次上线企微应用之前都会按下面这个清单走一遍基础接口连通性gettoken成功且缓存逻辑正常。发送文本消息测试成员能收到消息App端和PC端都点开看一眼。发送markdown消息渲染格式正确没有乱码。发送图文卡片跳转链接能打开图片能正常加载。回调验证管理后台能保存成功说明回调URL验证通过。消息交互用户发一条消息后台能收到并能正常回复。异常场景发送消息给不存在的用户接口返回60111等错误码程序能捕获而不崩溃。并发场景模拟短时间内多条消息同时发送企微接口是否有频率限制程序是否做了重试。这一套走完基本可以放心交给业务方试用。4.4 监控、日志与故障排查正式接入之后你不能等用户来投诉才发现系统挂了。企微接口的调用情况、成功率和错误码都要尽量留日志或接监控。我习惯的做法是用ELK或者Simple Log Service收接口日志重点关注errcode非0的请求。在发送消息的函数里埋点统计发送成功耗时和失败率超过阈值就告警。对企微返回的常见错误码做中文备注方便排查。比如40014是token无效42001是token过期60020是IP不在白名单60111是用户不存在。这些错误码在文档里都能查但你在代码里先做个映射表以后排查会快很多。还有一个很多新手不知道的点企微接口有全局频率限制和每应用频率限制。发消息太频繁会触发45009接口调用超过限额。遇到这种情况优先考虑把多条消息合并成一条、用群机器人分流、或者降低推送频率。必要时申请提升限额企微后台是可以申请的但要写明理由。5. 新手常见问题速查表最后把我在各个技术群里看大家问得最多的几个问题整理成一张表方便你直接查。问题常见原因解决办法获取access_token返回40013corpid或secret错误检查三件套是否复制完整注意大小写发送消息返回60011没有权限给该用户发消息检查应用可见范围以及用户是否在可见范围内发送消息返回60111UserId不存在用通讯录接口反查UserId确认不是手机号回调验证一直signature mismatchToken不一致或排序拼接错误检查Token配置确认拼接排序算法与文档一致回调消息解密后乱码AES IV或padding没处理优先用官方库不要手撸加解密刷新页面就token过期缓存没做对token要放缓存2小时过期前半小时主动刷新接口偶尔报45009触发频率限制合并消息、降低频率、申请提升限额网页授权code总是失效code用过了或超时code只能换一次5分钟内有效排查是否存在重复调用这8个问题几乎覆盖了新手90%的卡点。如果你遇到没在上面的错误码直接去官方文档查错误码说明或者用errcode关键字搜社区基本都能找到答案。企业微信二次开发的入门门槛真没有想象中那么高。你把一条消息从无到有发出去再把一条回调从外到里接进来核心机制就掌握得差不多了。后面的那些接口无非是在这个框架上填不同的业务参数而已。我个人在实际操作中最大的体会是别在准备工作上省时间。企业微信接口出错90%的根因不是业务逻辑复杂而是corpid配错、Token没对齐、IP白名单漏加这些“低级”问题。你要是肯花半天时间把环境、凭据、测试集合都整理干净后面整个接入过程会异常顺畅。另外一个小技巧分享给你调试阶段把你的请求和响应都打成日志哪怕只是打印到标准输出排查问题时就能少走两小时弯路。等迭代到第三代、第四代应用的时候你会发现日志和监控带来的价值远超当时的编码工作量。
企业微信二次开发从入门到落地：接口调试、回调部署与安全实践
做企业微信二次开发这件事我踩了不少坑也总结了不少经验。这篇东西不打算写成官方文档的复读机就按我实际走过来的路子从接口测试怎么玩到正式接入要准备哪些东西一条线讲清楚。适合刚接手企微开发、脑子里还一团浆糊的新手也适合已经写完demo但迟迟不敢上生产的同学参考。企业微信二次开发的核心说白了就是两件事拿到企业微信的能力发消息、读通讯录、建群、审批这些以及让你的服务器能跟企业微信服务器安全地对话。想明白这两点后面所有工作都是在围绕它们展开。1. 动手前的思路梳理先搞清楚你要做的是哪一种企微开发很多新手上来就急着看接口文档我觉得这是最大的误区。企业微信开放的能力很大你一上来根本不知道该看哪个接口。我建议先退一步把自己的需求想清楚。1.1 先判断场景自建应用、机器人、webhook还是审批流我见过的大多数需求其实都能归到下面这几类里消息推送类最常见。服务器产生告警、订单通知、日报提醒通过企业微信推给指定成员或群。这类用自建应用的“发送应用消息”接口或者群机器人webhook几分钟就能跑通。数据交互类需要把企业微信的数据拉回来比如同步通讯录、获取打卡记录、读取审批单详情。这类要用到通讯录管理、审批等API权限要求更高。交互操作类用户在企微里点按钮、填表单你的后台要响应。这类必须配置回调URL涉及消息接收和加解密难度一下子提上来了。页面集成类把已有的H5系统塞进企业微信工作台用户免登录打开。这类主要涉及OAuth2网页授权、JS-SDK签名倒不复杂但细节多。拿到需求先分类再把对应的接口清单列出来后面一步一步就能走通。比如你只是想弄个告警机器人那就完全不用碰回调加解密别自己吓自己。1.2 技术方案选型先别纠结语言关键是搞懂官方API结构企业微信官方提供了Java、Python、PHP、Go等语言的SDK但说实话官方SDK更新慢、封装的水平也一般。我更推荐新手直接用HTTP接口调试等把流程跑通了再看自己项目里要用什么语言封装。原因很简单企业微信的API设计非常规整核心就是“域名 路径 GET/POST参数 JSON请求体”你把一个接口用Postman调通了其他接口基本就是复制粘贴改参数。用官方SDK反而多了一层黑盒出了问题不知道是SDK的问题还是接口的问题。技术选型唯一要提前考虑的是你现有团队的技术栈。比如公司内部全是Java那就用Java做如果你个人维护小工具Python脚本最省事。语言不重要重要的是HTTP请求会发、JSON会解析这两样会了企微开发你就学会了60%。1.3 账号权限和环境规划一个容易被忽略的前置条件正式开发前你要确保自己手上有企业微信管理后台的权限。个人注册的企业微信就能开发不一定非得是企业认证。但有一点非常关键自建应用的Secret只有管理员能查看如果你连管理后台都进不去后面全白搭。我的建议是先注册一个测试企业或者用公司现有的测试企业随便造一个自建应用。把CorpID企业ID和AgentId应用ID、Secret应用密钥三件套记下来这三样就是你所有接口调用的“身份证”。能拿到一个测试成员的UserId方便后面测试发消息。另外要注意环境分离开发环境用测试企业的应用生产环境用正式企业的应用不要混用。因为一旦接口调用有误生产环境的告警消息可能发给所有员工这个事故我见过太多次了。2. 正式开发前的准备工作与接口测试准备工作做得越细后面正式接入越顺。这一节我把从创建应用到接口测试的完整链路拆开讲。2.1 创建自建应用把CorpID、AgentId、Secret一次性拿齐具体操作路径企业微信管理后台 → 应用管理 → 应用 → 自建 → 创建应用。填一个名称和Logo选一个可见范围然后创建。创建完之后应用详情页能看到AgentId和Secret企业管理后台的“我的企业”里能看到CorpID。这里有两个易错点Secret只显示一次。第一次点开看的时候赶紧复制保存到密码管理器里。我见过不少人当时没存后来只能重置Secret重置后原来的Secret立即失效正在跑的服务直接歇菜。可见范围别选“所有人”。开发阶段选几个测试成员就够了不然你测试发消息全公司的人都收到了非常尴尬。创建好应用之后建议先把通讯录的“读取成员信息”权限勾上。后面你经常需要根据手机号或姓名反查UserId没这个权限寸步难行。2.2 用Postman/Apifox调通第一个接口获取access_token企业微信几乎所有接口都要带access_token所以成功拿到token是你迈过新手门槛的第一步。接口如下GET https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpidCORPIDcorpsecretSECRET用Postman或者Apifox建一个GET请求把上面的占位符换成你的真实值发送。正常返回{ errcode: 0, errmsg: ok, access_token: xxxxxx, expires_in: 7200 }看到errcode: 0就说明你成功了。如果报40013之类的错误码大概率是corpid或secret复制错了回去检查。注意token有效期是7200秒2小时而且企业微信对获取token的接口有频率限制。千万不能每次发消息都调一次gettoken否则后面会被限流。正确做法是把token缓存起来等快过期了再刷新。我用Apifox测接口主要是因为它能把环境变量管理的很好。比如我定义base_url、corpid、secret这些变量在请求里用{{corpid}}引用换企业环境的时候只需要改变量不用改测试用例。这一点在用同一个接口文档测试开发环境和生产环境时真的是救命功能。2.3 接口测试怎么测才不算白测断言、错误码和环境隔离很多新手用Postman调通一个接口就觉得自己搞定了其实这是假象。真正的接口测试要覆盖下面几个维度正常参数确认返回结构和预想一致。边界参数比如发消息内容超长、接收人不存在、附件类型错误看看接口怎么报错。鉴权异常带一个错误的token看是否返回40014确认服务端能够正确处理。幂等性同一个请求发两次看会不会造成重复数据比如重复发消息。在Apifox里这些可以通过断言自动验证// 断言HTTP状态码为200 pm.test(Status code is 200, () { pm.response.to.have.status(200); }); // 断言业务错误码为0 pm.test(errcode is 0, () { const jsonData pm.response.json(); pm.expect(jsonData.errcode).to.eql(0); }); // 判断access_token非空 pm.test(access_token exists, () { const jsonData pm.response.json(); pm.expect(jsonData.access_token).to.not.be.empty; });把这些断言保存到接口集合里以后每次改完代码回归一遍心里才有底。我自己习惯用Apifox做接口测试原因很简单它自带环境管理、断言库和文档分享一个工具全干了。Postman也行看你团队习惯。这里必须提醒一个老生常谈但总有人踩的坑千万不能在测试环境里调正式企业的接口。我曾见过有人把测试脚本里的corpid改成了正式企业的结果测试消息发给全员差点出事。测试环境和生产环境的凭据一定要物理隔离。3. 从接口测试到核心功能实现接口测试跑通了接下来要处理的就是把几个核心能力真正用起来。我按消息发送、回调接收、页面接入三个方向分别说。3.1 发送应用消息文本、markdown、图文卡片发送应用消息是所有企微开发里最常用的接口没有之一。请求地址POST https://qyapi.weixin.qq.com/cgi-bin/message/send?access_tokenACCESS_TOKEN请求体发送文本消息给单个成员{ touser: zhangsan, msgtype: text, agentid: 1000002, text: { content: 你好这是一条来自自建应用的消息 }, safe: 0 }这里面的agentid就是你的自建应用IDtouser对应用户的UserId不是手机号千万别搞错。如果想发给群里可以用totag按标签发或者用群机器人webhook发。Markdown消息是运维告警场景的利器。请求体换一下就行{ touser: zhangsan, msgtype: markdown, agentid: 1000002, markdown: { content: **告警通知**\nCPU使用率超过 90%\n请及时处理 } }在企业微信App里markdown消息会渲染成带格式的样子比纯文本清楚很多。这里有个细节企微的markdown只支持部分语法标题、加粗、引用、链接这些没问题但表格、图片就不行。别拿标准的markdown语法往里糊。图文卡片news类型也很常用适合做报表推送。它支持标题、描述、图片URL和跳转链接用户点一下就能进入你的H5页面{ touser: zhangsan, msgtype: news, agentid: 1000002, news: { articles: [ { title: 日报, description: 今日销售额 10000 元, url: https://example.com/report, picurl: https://example.com/pic.png } ] } }3.2 接收消息与回调URL的部署这是新手最容易卡住的一关如果你只是单向推消息不涉及用户点击交互那你可以跳过这一节。但如果你要做的是回复机器人、审批联动、菜单点击就必须配置回调URL。回调的原理很简单用户在企微里的动作发消息、点菜单、扫码由企业微信服务器转发到你的服务器URL你的服务器收到后返回特定格式的响应。配置路径管理后台 → 自建应用 → API接收消息 → 设置URL、Token、EncodingAESKey。URL是你的服务器上的一个HTTP接口比如https://yourdomain.com/callback。这里有个硬性要求这个URL必须是公网能访问的HTTPS地址而且端口默认是443。开发阶段可以用内网穿透工具临时顶一下但正式环境必须上正式的HTTPS域名。配置的时候企业微信会往你的URL发一条验证请求具体来说是GET请求带上msg_signature、timestamp、nonce、echostr四个参数。你需要用Token和EncodingAESKey做签名校验然后解密echostr把解密后的明文返回给企微服务器才算验证通过。很多新手在这一步就卡死了。我见过最多的报错是signature mismatch也就是签名校验失败。排查思路就三条Token是否跟后台配置的完全一致包括大小写和空格。时间戳和nonce是否用的是企微传过来的原值不能自己造。排序拼接的算法是否跟文档一致sort(token, timestamp, nonce)后拼接再做SHA1。3.3 回调消息加解密的常见坑回调消息的加解密是二次开发里最劝退新手的部分。企业微信用的是AES-CBC加密EncodingAESKey是43位字符解码后就是32字节的AES密钥。加密后的消息体是Base64编码的字符串。官方提供了各语言的加解密库Java和PHP的都有Python的话网上有现成实现但很多是旧版的。我的建议是优先用官方SDK里的加解密工具类不要自己重写。几个实战中容易踩的坑加密消息体里有个20字节的random前缀解密后要做截取很多人解密出来一堆乱码就是忘了处理前缀。AES-CBC的IV是密钥的前16位不是全零。企微回调的消息体加密跟公众号的加密格式类似但密钥算法有差异别混用。如果你做的是Python开发解密核心逻辑大概是这个流程# 这里只列关键流程需要结合官方算法实现 # 1. 从EncodingAESKey做base64解码得到AESKey # 2. 用AESKey的前16字节作为IV # 3. 对密文做AES-256-CBC解密 # 4. 去掉前20字节的random # 5. 接下来的4字节是明文的长度网络字节序 # 6. 从第24字节开始才是真正的明文字符串 # 7. 尾部可能有padding需要去掉这个流程看起来不难但手写很容易漏掉细节。所以我才反复说能用官方库就用官方库。3.4 部门、成员、H5应用等扩展场景消息做通了其他功能就比较顺手了。我再补充几个常用场景的注意点通讯录同步接口是/cgi-bin/user/list可以拉取部门成员列表。这里的坑是分页逻辑企微返回的成员数量可能会多需要遍历所有部门ID拉取后合并去重。另外通讯录接口的权限跟自建应用可见范围绑定看不到的人拉不到这是正常现象不是Bug。OAuth2网页授权H5页面要拿用户身份走的是企微的OAuth2流程。核心逻辑是先让用户访问授权链接企微跳转回你的回调URL并带上code你用code换UserId再用UserId反查用户详情。这里记得code有效期只有5分钟而且只能换一次用完就失效。文件与素材上传发图片、文件消息前需要先把素材上传到企微临时素材库拿到media_id后再发消息。临时素材有效期是3天所以正式业务里图片不能只依赖这个长期存储还是得放自己的OSS。4. 正式接入的完整落地清单测试环境怎么玩都行一旦要上正式环境就要按生产标准来要求自己。这一节我列一个从测试切到正式接入的完整checklist。4.1 从测试环境切到正式环境的配置梳理正式接入不是把测试代码里的corpid换一下就完事的建议按下面的顺序逐项检查域名与HTTPS证书回调URL必须换成你正式的域名证书要有效不能用自签名证书企微服务器不认。应用信息在正式企业里重新创建自建应用拿新的AgentId和Secret。旧测试应用的密码要重置防止有人拿测试凭据访问正式环境。IP白名单企微后台可以给应用配置可信IP配置后只有这些IP能调用API。这是个很好的安全边界建议把服务器出口IP加上开发机IP不要加。可见范围从测试成员扩大到正式员工分批次加先加几个部门试点没问题再全量。素材改用正式地址图片、视频、文件都要换成正式环境的可访问URL不能用本地的localhost。4.2 权限最小化与安全实践企业微信的权限模型是“应用 权限”的二维结构。每个应用可以单独开设权限范围你不需要给所有应用都开全部的API权限。我的建议是消息应用只开发送消息权限不开通讯录编辑权限。需要读取通讯录时只开“读取成员基本信息”不要开“编辑”。如果应用不需要上传素材就别勾选素材权限。还有一个细节Secret的管理。企微支持一个应用生成多个Secret不同Secret可以负责不同功能模块。比如一个Secret专门发消息另一个专门读通讯录就算一个泄露了影响范围也有限。同时要定期轮换Secret这个很多团队都会忽略。企微还支持“企业微信插件”和“小程序”等不同的接入形态权限体系略有差别。如果你对接的是微信插件就还要考虑微信端的用户身份映射复杂度会高一截。新手建议先把标准API吃透再考虑这些扩展形态。4.3 上线前的自测清单照着跑一遍再发版我每次上线企微应用之前都会按下面这个清单走一遍基础接口连通性gettoken成功且缓存逻辑正常。发送文本消息测试成员能收到消息App端和PC端都点开看一眼。发送markdown消息渲染格式正确没有乱码。发送图文卡片跳转链接能打开图片能正常加载。回调验证管理后台能保存成功说明回调URL验证通过。消息交互用户发一条消息后台能收到并能正常回复。异常场景发送消息给不存在的用户接口返回60111等错误码程序能捕获而不崩溃。并发场景模拟短时间内多条消息同时发送企微接口是否有频率限制程序是否做了重试。这一套走完基本可以放心交给业务方试用。4.4 监控、日志与故障排查正式接入之后你不能等用户来投诉才发现系统挂了。企微接口的调用情况、成功率和错误码都要尽量留日志或接监控。我习惯的做法是用ELK或者Simple Log Service收接口日志重点关注errcode非0的请求。在发送消息的函数里埋点统计发送成功耗时和失败率超过阈值就告警。对企微返回的常见错误码做中文备注方便排查。比如40014是token无效42001是token过期60020是IP不在白名单60111是用户不存在。这些错误码在文档里都能查但你在代码里先做个映射表以后排查会快很多。还有一个很多新手不知道的点企微接口有全局频率限制和每应用频率限制。发消息太频繁会触发45009接口调用超过限额。遇到这种情况优先考虑把多条消息合并成一条、用群机器人分流、或者降低推送频率。必要时申请提升限额企微后台是可以申请的但要写明理由。5. 新手常见问题速查表最后把我在各个技术群里看大家问得最多的几个问题整理成一张表方便你直接查。问题常见原因解决办法获取access_token返回40013corpid或secret错误检查三件套是否复制完整注意大小写发送消息返回60011没有权限给该用户发消息检查应用可见范围以及用户是否在可见范围内发送消息返回60111UserId不存在用通讯录接口反查UserId确认不是手机号回调验证一直signature mismatchToken不一致或排序拼接错误检查Token配置确认拼接排序算法与文档一致回调消息解密后乱码AES IV或padding没处理优先用官方库不要手撸加解密刷新页面就token过期缓存没做对token要放缓存2小时过期前半小时主动刷新接口偶尔报45009触发频率限制合并消息、降低频率、申请提升限额网页授权code总是失效code用过了或超时code只能换一次5分钟内有效排查是否存在重复调用这8个问题几乎覆盖了新手90%的卡点。如果你遇到没在上面的错误码直接去官方文档查错误码说明或者用errcode关键字搜社区基本都能找到答案。企业微信二次开发的入门门槛真没有想象中那么高。你把一条消息从无到有发出去再把一条回调从外到里接进来核心机制就掌握得差不多了。后面的那些接口无非是在这个框架上填不同的业务参数而已。我个人在实际操作中最大的体会是别在准备工作上省时间。企业微信接口出错90%的根因不是业务逻辑复杂而是corpid配错、Token没对齐、IP白名单漏加这些“低级”问题。你要是肯花半天时间把环境、凭据、测试集合都整理干净后面整个接入过程会异常顺畅。另外一个小技巧分享给你调试阶段把你的请求和响应都打成日志哪怕只是打印到标准输出排查问题时就能少走两小时弯路。等迭代到第三代、第四代应用的时候你会发现日志和监控带来的价值远超当时的编码工作量。
实现与MATLAB应用)
