这不是字段手册。字段会变，坑不太变。
外部群消息接口开发指南记的是我们封装企业微信外部群发送时，开发组内部约定的几条。对着说明抄请求体，抄不会这些约定，上线照样翻车：字进了私聊、超时打出两条、测试 hello 进了家长群。
新人入组先看约定，再看怎么调。
先定三个模型，再写调用
发送方：哪个员工会话在说话。
接收方：外部群还是好友，类型分开，禁止一个字符串通吃。最常见的事故就是类型没分------调用成功，人在群里找不着，其实在私聊。封装时强制枚举，调用方少传类型就编不过去，比写在注释里有用。
内容：最终要出现在群里的文本，或已经上传好的素材。业务渲染完再交给通道。
成功以回执为准，调用返回了不算：
- 超时不要立刻重打
- 先查同一业务键有没有已经成功的投递
- 企业微信 POST 接口超时重试，群里会两条，家长以为活动有两轮
- 幂等键来自业务单，不来自随机流水（随机流水每次重试都是新的，幂等形同虚设）
- 「不确定」单独标，不要当失败去撞
测试和生产名单隔离：
- 发送封装带环境
- 生产配置即使配了测试群白名单，也不许打到白名单外
- 本地联调默认死名单，要打真实外部群必须换环境并走审批
有人用生产通道打 hello，进了真客户群，公关比改代码久。企业微信接口没有帮你区分玩笑和通知。
错误翻译成人能处理的原因
不要都变成「发送失败」。运营看了找开发，开发以为是网络。分类之后，补救才不同：
| 原因 | 谁去补 |
|---|---|
| 会话不在 | 补登录 |
| 人不在群 | 改映射 |
| 素材不存在 | 重传素材 |
| 被限流 | 降速 |
日志带业务单号和群名称，不带一长串无法检索的内部码。周会上运营能念出来的失败原因，才算翻译完成。
上传和发送拆成两次封装。图片、文件超时才能看出在哪一段。揉成一次，指南写得再细也排不了障。企业微信 SDK 要不要自己包一层随团队，对外只暴露「投递到外部群」这一句，避免每个服务自己猜素材和会话。
登录是否还活，放在发送前的检查，不放在业务代码里到处判断：
- 新建设备要尽快扫上，拖过几分钟会话可能是死的，后面所有发送像通道挂了
- 登录地和常用地不一致会二次验证，表现像调用一直转圈，日志里不一定有「验证」两个字
这些检查进通道层，业务只看「通道不可用」去告警，不要让每个调用方复制一套登录逻辑。
封装收在 QiWe API 之后，各业务线只传员工、外部群、内容和业务键。企业微信开放接口的细节不要散落在每个服务里，否则约定只写在这篇指南里，代码里没有。
指南的目标是换人还能按约定改，而不是每人对着一份说明各写各的发送，各踩一遍同样的私聊和双发。
QiWe API 官网：http://www.qiweapi.com/