企业微信协议接口是什么

「协议接口」这个词，问的其实是三件事

检索「企业微信协议接口」的人，想问的很少是某个接口的签名，而是三件被名词裹在一起的事：这条路线的能力以什么形式交付、你和平台之间多了什么，以及它和官方开放平台是什么关系。拆开看，名词造成的迷雾会散掉大半。

• 交付物是一套 REST 接口。你写的是普通的 HTTP POST 请求，用 curl 就能验证，不需要引入特殊客户端或额外运行时。
• 形态上多了一层托管：登录态、会话保活、事件投递由这层持续维持，而不是由你的业务进程维持。
• 边界不能按名字推断。哪些能力覆盖、字段怎么定义、错误码怎么划分，一律以线上接口文档为准。

站内讲企业微信底层协议的那篇，把整条链路拆成传输、接入、契约、领域四层，结论是你真正工作的位置只在上面两层：契约层决定请求怎么拼、响应怎么判，领域层决定业务怎么编排；再往下的实现细节既不可见，也不该写进你的业务假设。「协议」两个字最常制造的误会，就是让人以为得去盯最底下那层。

和开放平台 API 的角度差异

• 开放平台 API：官方公开规范，适合做成官方应用形态、上架分发给多个企业客户使用的场景。
• 协议级网关：把消息发送、账号托管、客户与会话、群与协作、事件回调收敛成一套统一 REST 语义，偏重把能力接进自有系统时的编排与联调效率。

差别不在能力清单谁更长，在「必须一直有人管着」的那部分归谁。账号会话是连续的、要保活、会异常中断；而你的服务随时重启、随时扩缩容。把两者塞进同一个进程，代价不是多写几百行代码，是整套无状态部署的习惯都得让路。托管掉这层之后，业务进程重新变回无状态。站内讲企业微信协议 API 与网关接口的那篇，把这层真正吸走的四类复杂度、以及原样留给你的那几类分得更细。

选型也不必二选一。要官方上架的部分走官方规范，要快速接进自有系统的部分走网关，两条并存很常见。站内另有一篇按能力覆盖、接入成本、上架分发、可观测、合规、维护成本六个维度逐条对照的文章，选型会上可以直接照着过一遍。

动手之前要准备什么

• 一个账号实例：在控制台 manager.wecomapi.com 创建并扫码登录，确认状态面板显示在线。
• 一份 API 密钥：同样在控制台创建与轮换，调用时以 Authorization: Bearer 方式携带，不要写进前端或提交进仓库。
• 一个公网可达的回调地址：用于接收事件。本地开发阶段可以先用隧道工具临时暴露一个端口。
• 一个只用来收测试消息的接收方：自己的号或一个内部测试群，不要拿真实客户会话做联调。

分步接入：从零到一条完整回路

1. 1建实例并登录。在控制台创建实例、扫码登录，盯住状态面板变成在线再往下走。这一步没成，后面所有调用的失败都指向同一个原因，排查是白排。
2. 2发出第一条消息。用下面的请求给自己发一条文本。判据有两个：HTTP 返回 200，且响应体是 code 为 0、msg 为 success；同时目标会话里真的出现了这条消息。只满足前一个不算通过。
3. 3把响应头记进日志。响应头会带 x-request-id，这是事后定位某一次调用的唯一抓手；x-ratelimit-remaining 用来观察自己的调用节奏。两个都在调用出口统一记录，别等出了问题再补。
4. 4接上事件回调。配置回调地址后，回调入口只做三件事：验签、落一条原始记录、入队，然后立刻返回。真正的处理逻辑放到队列消费端，回调接口本身不承担业务耗时。
5. 5跑通一条回路。收到一条消息 → 你的系统处理 → 用发送接口回写一条。这条回路一旦成立，其余能力都是同一套形态的替换：换端点、换字段，鉴权、错误处理和重试策略不用重写。
6. 6换环境重跑。用另一套实例和密钥在预发环境把前五步再走一遍，确认没有任何硬编码。这一步通常能揪出两三个写死的值。

# -i 会把响应头一起打出来，这一步就是要看头
curl -i -X POST https://manager.wecomapi.com/message/sendText \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "guid":    "7db8...",
    "toId":    "78813...",
    "content": "Hello WeCom"
  }'

# 期望看到：
#   HTTP/1.1 200 OK
#   x-request-id: req_7d4ec1a9        <- 排障时提供它即可定位
#   x-ratelimit-remaining: 98         <- 观察余量，别贴着底跑
#   { "code": 0, "msg": "success" }
# 端点、字段与错误码以线上接口文档为准

架构与数据流：谁调谁、状态存哪、谁负责重试

出方向和入方向是两条独立链路，把它们混在一起想，是排障时最常见的卡点。

• 出方向：你的服务 → 网关 REST 接口 → 企业微信侧。同步调用，结果当场可判。
• 入方向：事件发生 → 网关 → 你的回调地址 → 队列 → 消费者。异步投递，结果不在调用现场。

状态存哪有一条清楚的分界。登录态、会话保活、实例的存活与恢复由托管侧维持，你这边不要另存一份；业务状态 —— 这条消息处理到哪一步、这个客户跟进到什么阶段 —— 只能存在你自己的库里，网关不替你记业务语义。分界越清楚，后面越不容易出现两边都以为对方记了的空档。

重试也分两段，各归各的。出方向由你的调用方负责：接口按幂等语义设计，网络抖动后重试是安全的。入方向由投递侧负责重投，你要做的是幂等消费 —— 给每条事件取一个稳定的去重键，重复投递时只生效一次。两段不能互相假设，尤其不能因为投递侧会重投，就在自己这边省掉去重。

错误处理与排障

拿到失败响应先别急着查码值。码值多、还会随版本增补，真正决定处置的只有一件事：现在该做什么。按这个分，只有四类。

• 确定性失败：请求本身不对，比如参数缺失、目标不存在。重试多少次都一样，要改的是请求。
• 状态失败：账号实例掉线或未登录。先去控制台看状态面板、恢复登录，而不是在代码里加重试。
• 容量失败：调得太快。退避后重试，同时回看 x-ratelimit-remaining 的走势，判断是瞬时尖峰还是常态超配。
• 结果未知：超时、连接中断，你并不知道对方到底执行了没有。这类最危险，既不能当成功，也不能当失败。

两个最贵的误判：把「结果未知」直接当失败，会造成重复发送，用户端看到两条一样的消息；把「状态失败」当成容量失败，程序会一直退避重试，而实际上需要有人去把账号重新登上，退避到天亮也不会自己好。站内讲企业微信接口报错怎么分类处理的那篇，把四类的映射和处置写得更完整。

排障时手上要有三样东西：出问题那一次调用的 x-request-id、当时的请求体、以及 HTTP 状态码和响应体 code 两层各自的值。三样齐了，问题基本能收敛到具体一次调用；缺了 x-request-id，往往只能靠时间戳大海捞针。这也是上一节第 3 步要求在调用出口统一记录的原因。

怎么判断你确实做对了

「跑通了」不是判据。下面这几条才是 —— 每条都能在不看代码的前提下观察到。

1. 1连续发 20 条测试消息，接收方收到 20 条，不多不少；任取其中一条，能用 x-request-id 在日志里定位到对应的那次调用。
2. 2故意让队列消费端抛一次错，确认这条事件最终仍被处理，且业务侧的效果只发生了一次，没有出现两条重复回复。
3. 3重启一次业务进程，期间产生的事件在恢复后仍被消费；控制台状态面板上账号保持在线，不受你这边重启影响。
4. 4把配置整体换成预发环境的实例与密钥，不改一行代码即可运行。做不到，说明还有硬编码没清干净。
5. 5看一天的 x-ratelimit-remaining 走势，确认业务高峰时仍有余量，而不是长期贴着底跑。