企业微信接口对接教程：请求、回执与幂等

「企业微信接口」对接翻车，很少是因为少调了一个方法，而是因为 请求当时成功、群里没有消息、重试后又出现两条。 这篇按对接教程写：怎么组请求、怎么收结果、怎么保证只发一次。

对接对象先锁死，接口清单后补

对接前只回答三个问题：

消息要出现在员工工作台，还是外部群会话里？
发送方是应用，还是某个企业微信账号？
接收方用什么当主键：userid、外部联系人 ID，还是外部群 ID？

三个答案不定，接口文档翻得再熟也会接错。

员工工作台走官方应用消息接口。

外部群会话通常要走账号在线 + 群 ID 发送这一路，和通讯录接口不是同一套。

下面默认你要对接的是：指定企业微信账号 → 指定外部群 → 发出去 → 可对账。

请求怎么组：四个字段一个都不能省

每次发送请求固定带：

instance_id

哪个企微实例在发。多开时不靠「当前登录的那个号」这种隐式状态。

target_id

外部群稳定 ID。禁止用群名、群备注、最近一条聊天标题。

payload

类型 + 内容。文本、图片、文件分开，或用明确的 type。不要把「先发文字再发图」折叠成一个模糊字段让通道猜。

request_id

业务侧生成，全局唯一。对接的全部幂等都靠它。

可选但建议有：

biz_id：订单号 / 课次 ID，方便运营反查
priority：节点通知高于活动
earliest_send_at：允许进入的发送窗口

接口对接不是把聊天记录里的参数抄进 POST。是先把这张请求表当成你们内部标准，通道只是实现者。

调用时序：先问在线，再投递，再等结果

推荐顺序，不要合并成一次「发了就算」：

复制代码

1. 查实例在线
2. 校验 target_id 仍属于该实例（账号还在群）
3. 创建发送任务（状态=已受理）
4. 通道真正发出
5. 回执把任务改成成功或失败

为什么拆开：

RPA / 客户端通道里，HTTP 返回往往只代表「任务被接住」
官方接口里，也可能有异步审核或延迟投递
业务系统如果在第 3 步就给运营亮绿灯，对账一定假

对接协议上要接受两个时间点：受理时间、群内可见时间。报表用后者。

回执：同步失败和异步失败分开收

同步就能确定的

参数缺、签名错、实例不存在、明显离线。这类应直接 4xx/业务错误码，不要进队列装成发送中。

必须异步才能确定的

客户端已点进群、图片上传完成、被限制弹窗。这类用：

回调推到你的 URL，或
用 request_id 轮询任务状态

回执报文至少能还原：

request_id
终态：success / fail
失败分类（离线、不在群、限频、参数、未知）
通道侧消息标识（有则存，便于排重和客服核对）

未知失败不要自动当成功，也不要无限重试。进入人工或告警队列。

幂等：对接里最值钱的一段

网络抖动时，业务侧重试是常态。企业微信接口如果按「每次 POST 都新发一条」来实现，外部群会直接出现重复通知。

规则写死：

同一 request_id，通道只允许成功一次
重试必须原样带同一 request_id
文案改了但 ID 没改：以第一次受理的内容为准，或直接拒绝并要求新 ID
查询接口用 request_id 拉状态，不要再调发送

建议业务库先插任务再调通道。插入冲突（主键/唯一键）说明已经受理过，转去查状态，而不是再打一次发送。

错误码要对成运营动作

对接文档里的码只是原料。你们要映射成人话动作：

分类	系统动作	运营动作
离线	该实例停发	重新登录
不在群	关闭该群任务	检查是否退群、是否映射错
限频	推迟到下一窗口	降低该号任务量
参数错误	任务失败，不重试	改群 ID / 改类型
超时未决	只查询不重发	等回执，超时再人工看群

接口对接完成的标志，不是 Postman 绿了，而是运营能凭失败分类干活。

联调清单（按天）

当天： 测试号 + 测试外部群，文本请求带 request_id，能在群里看见。

次日： 同一 request_id 连打三次，群里仍一条。

再一日： 拔掉实例或退出群，确认回执分类正确、不会假成功。

然后： 图片、错误群 ID、夜间窗口拒绝发送。

内部群 webhook、通讯录、审批不要塞进同一轮联调。企业微信接口项目一混，日志就无法归因。

小结

企业微信接口怎么接，关键是请求四件套、受理与可见分离、回执可分类、request_id 真正幂等。先锁接收人和主键，再写调用时序。能重试而不重复、能失败而不撒谎，对接才算结束。功能可以后加，重复消息和假成功会立刻消耗客户群。