企业微信协议怎么接入？从环境准备到第一条消息的联调步骤
适合准备做企微客服、SCRM、聚合会话的后端同学。按可执行清单写，接口名以你方实际文档为准。
写在前面
对接协议能力时，最容易犯的错是：对着接口列表东点西点，登录态、回调、业务调用顺序乱了，排障成本很高。
更稳的做法是固定一条主路径：
准备环境 → 初始化实例 → 配置回调 → 扫码登录 → 发第一条消息 → 用回调验收
跑通后再扩展联系人、标签、群等模块。
一、接入前准备
| 项 | 说明 |
|---|---|
联调环境 | 可访问的协议服务入口与文档权限 |
回调服务 | 公网可达的 HTTP 接口（本地可用内网穿透） |
日志 | 能同时看「调用响应」和「回调原文」 |
测试账号 | 专用企微测试号，避免影响正式客户 |
没有环境时，可先在体验环境按模块浏览接口分类与示例，再按门户接入说明推进：
二、Step 1：初始化实例，拿到 uuid
首次接入一般先初始化，获得实例标识uuid。首次登录场景下，账号标识vid常为空。
保存好：
POST /wxwork/init Content-Type: application/json { "vid": "" }uuid：后续所有业务调用都带它- 环境备注：对应哪个业务线 / 测试号
注意：多账号时每个在线号对应自己的uuid，不要混用。
三、Step 2：配置回调地址
把公网回调 URL 绑到当前实例（接口名常见类似设置回调地址）：
POST /wxwork/SetCallbackUrl Content-Type: application/json { "uuid": "你的uuid", "url": "https://your-domain.com/wx/callback" }自检三步：
- 用 Postman/curl 对本机回调打一发模拟请求
- 确认网关没有截断 body
- HTTPS 场景检查证书是否有效
回调入口建议「先应答、再异步处理」：
app.post('/wx/callback', async (req, res) => { const { uuid, type, json } = req.body res.status(200).send('ok') await enqueue({ uuid, type, json }) })四、Step 3：扫码登录，持久化 vid
调用获取二维码接口（如getQrCode），用测试账号完成登录。
关注点：
- 新设备可能触发验证码或二次验证
- 登录成功后，回调里会出现登录成功类事件
- 登录成功务必持久化
vid，供后续断线恢复
建议状态：
INIT → WAIT_QR → ONLINE 日志同时打： [PUSH] uuid=... type=登录相关... [CALL] uuid=... api=getQrCode ...五、Step 4：发出第一条业务调用
登录成功后，用 同一个 uuid 发一条文本消息做验收（接口名以文档为准，例如发送文本）：
{ "uuid": "你的uuid", "to": "目标会话标识", "content": "接入联调测试消息" }验收标准：
- 接口返回成功
- 企微会话里能看到消息
- 回调侧能观察到对应消息或状态事件（按实际下发为准）
六、Step 5：用回调做闭环验收
不要只看「发送成功」。完整验收至少包括：
- 回调公网可达，有原始报文日志
- 能按
type区分登录 / 消息等大类 - 消息类能读到
msgtype - 重复推送有幂等（如
uuid + msgid） - 同一
uuid的调用日志与回调日志能对上
消息回调里若文档提到referid：0多为原消息，非0多为衍生状态（如已读），不要一律当新消息入库。
七、常见失败对照表
| 现象 | 可能原因 | 处理方向 |
|---|---|---|
业务接口失败 | 未登录 / uuid 错误 | 先查登录态 |
收不到回调 | 非公网、防火墙、路径错 | 先测连通性 |
扫码后无成功事件 | 验证流程未走完 | 查二次验证相关流程 |
回调重复入库 | 未做幂等、未快速 ACK | 快应答 + 唯一键 |
本地正常线上失败 | 域名 / HTTPS / 证书 | 对比环境差异 |
八、跑通后怎么扩展（别一次做完）
主路径通了再按模块加：
- 客户与联系人、标签（SCRM）
- 群运营
- 媒体消息与文件下载
- 多实例 + 断线自动恢复（
vid+ 自动登录）
生产环境额外补：
- 每账号独立队列
- 在线数 / 重连成功率 / 回调失败率监控
小结
接入步骤可以记成一句话：
init 拿 uuid → 配回调 → 扫码拿 vid → 带 uuid 发第一条消息 → 用回调验收闭环。
顺序对了，后面扩 SCRM、客服、群运营会顺很多；顺序乱了，排障会成倍增加。