📌 零、导读
适用对象
需要对接企业微信的后端开发者
要做内部应用、员工通知、客户运营（私域）的团队
企微对接的核心特点（区别于公众号/小程序）
主体是企业自建应用，凭证为 CorpID + AgentId + Secret
核心能力：通讯录、应用消息、回调、网页授权、客户联系
回调消息需 AES 加解密（难点）
可与微信互通（客户联系做私域）
涵盖范围
账号与应用准备
access_token 鉴权
通讯录对接
应用消息推送
接收消息与事件（回调+加解密）
网页授权登录（企微免登）
客户联系（与微信互通）
部署与运维
核心流程
申请准备 → 开发环境 → 鉴权 → 能力对接 → 测试 → 部署 → 运维
📝 一、申请与资质准备
🏢 1.1 注册企业微信
步骤1：访问企业微信官网（work.weixin.qq.com）
步骤2：点击"立即注册"
步骤3：填写企业信息（企业名称、行业、人员规模）
步骤4：填写管理员信息（姓名、手机号，微信扫码绑定）
步骤5：注册完成，进入企业微信管理后台
🛡️ 1.2 企业验证 / 认证
为什么需要
未验证企业有功能限制（如成员数上限、接口能力受限）
部分高级接口需要已认证企业
验证方式
方式1：提交营业执照等资质认证
方式2：通过已认证的微信公众号授权验证
⚠️ 建议尽早完成认证，避免后续接口受限
📱 1.3 创建自建应用
路径：管理后台 → 应用管理 → 自建 → 创建应用
填写
应用名称、logo
可见范围（哪些部门/成员能用）
创建后获得
AgentId：应用的唯一标识
Secret：应用的密钥
⚠️ 每个应用有独立的 AgentId 和 Secret
🆔 1.4 获取核心凭证
CorpID（企业ID）
路径：管理后台 → 我的企业 → 企业信息
企业唯一标识，全企业共用
Secret（应用密钥）
每个应用对应一个
⚠️ 保密，只在后端使用
凭证关系
CorpID：企业级，一个企业一个
AgentId + Secret：应用级，每个应用一套
调用接口用 CorpID + Secret 获取 access_token
🌐 1.5 设置可信域名与企业可信IP
设置可信域名（网页授权/登录/JS-SDK 用）
路径：应用详情 → 网页授权及JS-SDK → 设置可信域名
域名需已备案、可访问
需下载校验文件放到域名根目录
设置企业可信IP
路径：应用详情 → 企业可信IP
填入调用接口的服务器公网IP
⚠️ 未配置IP白名单，调接口会报错（新手高频坑）
💻 二、开发环境
🖥️ 2.1 服务器与域名
需要公网可访问的服务器（接收回调）
域名需已备案
回调、网页授权等需 HTTPS
🔧 2.2 SDK 与调试
企微提供多语言 SDK（Java、Python、PHP、Node等）
加解密库：官方提供（回调消息加解密必需）
调试工具：企微管理后台的接口调试、Postman
🔑 三、鉴权体系：access_token（对接基础）★
📖 3.1 什么是 access_token
调用企微接口的全局凭证
通过 CorpID + Secret 获取
每个应用（每个Secret）有对应的 access_token
🔄 3.2 获取 access_token
接口：GET /cgi-bin/gettoken
参数：corpid、corpsecret
返回：access_token、expires_in（有效期，秒）
⚠️ 3.3 access_token 管理（极其重要）
有效期：2小时（7200秒）
必须缓存，不能每次调接口都获取
有频率限制，频繁获取会被限制
建议
集中管理，定时刷新
多服务共享同一个 token
过期前主动刷新
⚠️ 不同应用的 access_token 相互独立，不要混用
🔗 四、核心能力对接（攻坚阶段，重点）★
👥 4.1 通讯录对接（企微特色）
作用
同步/管理企业的部门和成员
获取用户身份标识
关键身份标识（重点区分）
userid：成员在企业内的唯一标识（企业自定义）
openid：成员在微信下的标识（企微与微信关联）
external_userid：外部联系人（微信用户）的标识
部门管理
创建/获取/更新/删除部门
获取部门列表
成员管理
创建/读取/更新/删除成员
获取部门成员列表
获取成员详情（姓名、手机、邮箱等）
⚠️ 注意
通讯录接口需对应的通讯录权限（应用可见范围）
敏感字段（手机号等）可能有权限限制
📩 4.2 应用消息推送（给员工发通知）
作用
企业应用主动给员工发消息（如审批通知、告警）
消息类型
文本、图片、语音、视频
图文、文本卡片
小程序通知
发送流程
步骤1：获取 access_token
步骤2：调用发送接口
接口：POST /cgi-bin/message/send
参数：touser（用户）、toparty（部门）、totag（标签）、消息内容
步骤3：发送成功，用户在企微收到应用消息
发送目标
指定成员（userid）
指定部门
指定标签
⚠️ 注意
只能发给应用可见范围内的成员
有发送频率限制
🔄 4.3 接收消息与事件：回调 + 加解密（难点）★
作用
接收成员操作事件（如成员加入、审批、打卡）
接收用户发给应用的消息
配置回调
路径：应用详情 → 接收消息 → 设置API接收
填写
URL：你的回调地址（公网、80/443端口）
Token：自定义
EncodingAESKey：加解密密钥
回调验证流程
步骤1：企微向你的URL发GET请求，带签名和加密的echostr
步骤2：你的服务器验证签名、解密echostr
步骤3：返回解密后的明文，验证通过
接收消息/事件
企微向你的URL发POST请求
消息体是【加密的】XML
需用官方加解密库解密
消息加解密（重点）
企微回调消息默认加密
需要用 Token、EncodingAESKey、CorpID 进行解密
官方提供加解密库（Java/Python/PHP等）
流程：收到密文 → 解密 → 得到明文XML → 解析处理
⚠️ 关键点
回调必须公网可访问
加解密是难点，务必用官方库
验签失败、解密失败都要正确处理
被动回复也有超时限制（类似公众号5秒）
🔐 4.4 网页授权登录（企微免登）★
作用
在企微客户端内打开网页，免登获取用户身份
或网页扫码登录企微
场景一：企微内网页免登（静默）
步骤1：构造授权链接，引导跳转
参数：appid（CorpID）、redirect_uri、agentid、scope
步骤2：用户授权，企微回调你的 redirect_uri，带 code
步骤3：后端用 code + access_token 获取用户身份
接口：GET /cgi-bin/user/getuserinfo
返回：成员的 userid（企业成员）
步骤4：根据 userid 识别用户，生成登录态
场景二：网页扫码登录
用于企业外部网页，用企微扫码登录
获取用户身份（企业成员）
⚠️ 关键点
需配置可信域名（网页授权域名）
code 一次性，需尽快使用
企微内免登拿到的是 userid（企业成员身份）
区分：企微成员（userid）与 微信外部用户（另一套）
🤝 4.5 客户联系（与微信互通，私域运营）
作用
企微员工与微信用户（客户）互通
做客户运营、私域管理
核心概念
客户：加了企微员工的微信用户
external_userid：外部客户的标识
客户群：企微员工拉的客户群
主要能力
获取客户列表
获取客户详情
客户标签管理
客户群管理
客户朋友圈
使用前提
需开通"客户联系"功能
配置使用范围（哪些员工可用）
配置回调（接收客户联系事件）
⚠️ 注意
客户联系涉及微信用户，有合规要求
不能过度营销骚扰，否则会被限制
🧩 4.6 其他能力（按需）
审批（自建审批应用）
打卡、日程、会议
企微文档
微信客服（对接微信客服）
📤 六、部署上线
🚀 6.1 部署流程
步骤1：后端服务部署到公网服务器
步骤2：配置 HTTPS
步骤3：确保域名已备案
步骤4：配置正式环境凭证（CorpID、Secret、AgentId）
步骤5：配置正式回调URL、可信域名、可信IP
步骤6：真机验证核心功能
📱 6.2 应用发布与可见范围
设置应用可见范围（哪些部门/成员可用）
应用上线后，可见范围内的成员能在企微工作台看到
⚠️ 企微自建应用无需"审核发布"（区别于小程序），配置可见范围即可用
⚠️ 6.3 上线注意事项
敏感配置用环境变量，不要写死代码
回调地址切换正式环境时注意加解密参数一致
区分测试环境和生产环境的凭证
⚡ 八、速查清单
🔑 关键凭证
CorpID：企业ID（企业级）
AgentId：应用ID（应用级）
Secret：应用密钥（仅后端）
access_token：接口凭证（2小时，需缓存）
🔗 核心接口
获取token：/cgi-bin/gettoken
发送消息：/cgi-bin/message/send
获取用户身份：/cgi-bin/user/getuserinfo
通讯录：/cgi-bin/department/<i>、/cgi-bin/user/</i>
📋 关键流程速记
鉴权：CorpID+Secret → gettoken → access_token → 调接口
网页授权：跳转授权页 → 回调带code → code+token换userid → 识别用户
回调：配置URL → 验签+解密 → 处理消息/事件
消息推送：获取token → message/send → 员工收到通知
⚠️ 高频坑
忘记配置企业可信IP（调接口报错）
忘记配置可信域名（网页授权失败）
access_token 未缓存（频繁获取被限）
回调加解密出错（务必用官方库）
混淆 userid（企微成员）和 external_userid（外部客户）
域名必须已备案，回调需HTTPS
应用消息只能发给可见范围内的成员
Secret 绝不暴露给前端
