适合准备做企微客服、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 对本机回调打一发模拟请求确认网关没有截断 bodyHTTPS 场景检查证书是否有效回调入口建议「先应答、再异步处理」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... apigetQrCode ...五、Step 4发出第一条业务调用登录成功后用 同一个 uuid 发一条文本消息做验收接口名以文档为准例如发送文本{ uuid: 你的uuid, to: 目标会话标识, content: 接入联调测试消息 }验收标准接口返回成功企微会话里能看到消息回调侧能观察到对应消息或状态事件按实际下发为准六、Step 5用回调做闭环验收不要只看「发送成功」。完整验收至少包括回调公网可达有原始报文日志能按type区分登录 / 消息等大类消息类能读到msgtype重复推送有幂等如uuid msgid同一uuid的调用日志与回调日志能对上消息回调里若文档提到referid0多为原消息非0多为衍生状态如已读不要一律当新消息入库。七、常见失败对照表现象可能原因处理方向业务接口失败未登录 / uuid 错误先查登录态收不到回调非公网、防火墙、路径错先测连通性扫码后无成功事件验证流程未走完查二次验证相关流程回调重复入库未做幂等、未快速 ACK快应答 唯一键本地正常线上失败域名 / HTTPS / 证书对比环境差异八、跑通后怎么扩展别一次做完主路径通了再按模块加客户与联系人、标签SCRM群运营媒体消息与文件下载多实例 断线自动恢复vid 自动登录生产环境额外补每账号独立队列在线数 / 重连成功率 / 回调失败率监控小结接入步骤可以记成一句话init 拿 uuid → 配回调 → 扫码拿 vid → 带 uuid 发第一条消息 → 用回调验收闭环。顺序对了后面扩 SCRM、客服、群运营会顺很多顺序乱了排障会成倍增加。
