企业微信 API 有哪些（能力总览）

「企业微信 API 有哪些」其实是三个问题

这个问题在不同人嘴里问的不是同一件事。有人在核对能力清单，想确认自己的场景能不能被覆盖；有人在看调用形态，关心鉴权怎么带、返回怎么判、出错能不能重试；还有人已经决定要做，只是想知道先接哪一个、后接哪一个。三件事混在一起答，结果就是一张读完仍然不知道从哪下手的清单。

• 能力清单：一共有哪几类接口，各自管什么。
• 调用形态：请求怎么发、响应怎么判、失败怎么处置。
• 落地顺序：这些能力按什么次序接，中途才不会返工。

下面按这三层依次回答，最后给一组可以自己核对的验收判据。本页是这个主题的总纲，每一段往下深挖的内容，站内都有单篇在讲。

第一层：六个能力域

• 消息发送：文本、图片、文件、链接卡片与富文本模板，支持按会话维度路由与重试策略。
• 账号接入与托管：扫码登录、会话保活、实例隔离与状态面板，适合多业务线分账与分环境。
• 客户与会话：客户联系、会话接管、标签与跟进记录的结构化读写，便于与 CRM 对齐。
• 群与协作：群创建、成员变更、群公告与群内消息，适配运营活动与项目群场景。
• 事件回调：消息、成员、客户与群事件订阅，支持签名校验、投递重试与死信观测。
• 系统集成：Webhook、OpenAPI、细粒度权限与审计日志，用于对接工单、ERP、OA 与自建中台。

这六项不是六个独立产品，是同一套接口的六个切面。它们之间有两条固定关系值得先记住：账号接入是其余五项的前置，没有一个在线的账号，消息发不出去、事件也推不过来；事件回调是唯一的入站方向，其余都是你主动发起的出站调用。把这两条摆清楚，排期顺序基本就定了。

第二层：调用形态与前置准备

六个域共用同一套调用约定，读一次就覆盖之后的每个接口。请求走 REST 语义，鉴权在请求头里带 Bearer 密钥，请求体与响应体都是 JSON；接口按幂等语义设计，网络抖动后重试是安全的；每次调用会在响应头回传 x-request-id，排障时提供它即可定位。站内讲 REST 调用约定的那篇把这四条各自的边界拆得更细，尤其是「重试是安全的」到底承诺了什么、又没有承诺什么。

动手之前，先把这几样准备齐，能省掉一半的返工：

• 控制台账号，以及一把在控制台创建的密钥；密钥的轮换也在控制台完成。
• 一个可公网访问的回调地址，本地联调可以用隧道工具临时暴露。
• 一个专门用来测试的会话对象，优先选自己或一个内部群，别拿真实客户试手。
• 测试与生产至少分成两套账号，不要共用同一把密钥。

第三层：把地图落成一条能跑的链路

不要六个域一起铺开。先跑通最短的一条链路，它会替你验证鉴权、网络、回调地址这三件最容易出问题的事；之后所有能力都是在这条链路上加分支。站内讲开发入门的那篇把这条最短链路收敛成了三步，并且解释了为什么顺序不能反过来 —— 发送失败的原因高度集中，回调收不到的原因散在三处。

1. 1在控制台创建密钥并写进环境变量。判据：密钥只出现在环境变量与密钥管理里，代码仓库和前端里搜不到它。
2. 2完成账号接入，确认实例在线。判据：控制台状态面板显示该账号在线，而不是停在「登录中」或已掉线。
3. 3调发送消息接口，往测试会话发一条文本。判据分两层看：HTTP 状态码是 2xx，并且响应体里 code 为 0；两层都过才算成功，只看其中一层是最常见的误判。
4. 4把这次调用的 x-request-id 记进日志。判据：拿一条业务记录，能反查出它对应的 x-request-id。
5. 5配置回调地址并订阅事件，然后往测试会话回一条消息。判据：你的服务收到一次推送，且验签通过。
6. 6把入站事件接到出站发送上，做出一次自动回复。判据：从收到消息到回复发出，全程没有人工介入。

curl -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"
  }'

# 响应体
# { "code": 0, "msg": "success" }
#
# 响应头（排障时真正有用的两个）
# x-request-id: req_7d4ec1a9
# x-ratelimit-remaining: 98

注意 x-request-id 和 x-ratelimit-remaining 都在响应头里，不是响应体字段。前者用于回溯单次调用，后者用于观察剩余额度，从第一天就把它们记进日志，成本几乎为零，但出事那天它们的价值远大于看起来的分量。其余字段定义与端点，以线上接口文档为准。

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

链路超过一条之后，就得先把数据流定下来，否则每接一个新业务方都要重新吵一遍。

出站方向由你的业务系统发起，中间过一层自己的编排服务再打到接口上。密钥和登录态不要散落在各业务模块里，集中由编排层持有 —— 站内讲凭证与 Token 管理的那篇专门讨论了它该存进程内还是集中缓存、多实例并发刷新时的惊群与旧值覆盖怎么防。

入站方向相反：平台把事件推到你的回调地址，你的服务只做三件事 —— 确认来源、快速应答、异步处理。

app.post("/wecom/callback", async (req, res) => {
  if (!verifySignature(req)) return res.sendStatus(401); // 来源不明直接拒收
  res.sendStatus(200);                                   // 先应答，再干活
  await queue.enqueue({ raw: req.rawBody });             // 原始报文整条入队
});

// 验签算法、幂等键取哪个字段，以线上接口文档为准

• 出站失败由调用方重试，退避按会话维度分桶，不要在账号维度上一把梭。
• 入站失败由平台侧按自己的策略重投，你能控制的只有应答快不快、幂等做没做、要不要主动拒收。
• 两个方向都保留原始报文，重放永远比复现便宜。

状态存哪，最省事的答案是分三处：登录态与密钥进集中缓存，事件与消息的原始报文落库，业务状态留在业务库。三者混在一张表里，早晚会在一次清理数据时互相牵连。

错误处理与排障

先接受一个前提：失败是常态，值得投入的是分类而不是穷举码值。码值有几十上百个还会随版本增补，背不完；真正决定处置动作的只有一句话 —— 现在该做什么。站内有一篇就是按这个思路把接口报错分成四类，这里只给结论。

• 确定性失败：参数或权限不对，重试多少次结果都一样，直接报错并告警。
• 状态失败：账号掉线、目标不可达，重试无意义，要先把状态修好再谈发送。
• 容量失败：触发频控，该退让的不只是这一条请求，而是整条链路降速。
• 结果未知：超时或连接中断，这类最贵 —— 它不等于失败，盲目重发会造成重复。

真的卡住时，按这个顺序查通常最快：

1. 1先分层。连不上、鉴权被拒、请求超时属于传输与鉴权层；HTTP 返回 2xx 但响应体里 code 不为 0 属于业务层。两层的排查方向完全不同，混着看一定绕远路。
2. 2拿 x-request-id。它在响应头里，不在响应体里；有它就能定位到具体某一次调用，没有就只能靠时间戳猜。
3. 3看 x-ratelimit-remaining。如果它长期贴近 0，问题不在这一次调用，而在你整体的调用节奏。
4. 4回调收不到，先分清是根本没推过来，还是推过来被自己挡了。前者查地址与订阅范围，后者查验签与中间层 —— 站内讲回调配置与验签的那篇提到，验签对不上八成不是算法的问题，而是原始报文在到达验签函数之前被谁动过。

怎么验证做对了

「跑通了」不是判据。下面这几条是可观察的，逐条过一遍，比再读十页文档有用：

• 任取一条最近发出的消息，能在日志里查到它对应的 x-request-id。
• 故意用一把错误的密钥调一次，系统报出的是鉴权失败，而不是笼统的「发送失败」。
• 把回调服务停掉五分钟再启动，看恢复后能否正常接收并幂等处理；补投窗口以线上接口文档为准。
• 同一个事件重复投递两次，业务侧只产生一次结果。
• 连续发送直到触发频控，链路表现为整体降速，而不是把一串失败往上抛。
• 监控面板上能同时看到出站成功率、入站事件量，以及 x-ratelimit-remaining 的走势。

这六条里只要有一条不成立，就说明链路上还有一段在靠运气跑。补完之后再往上叠加新的能力域，才是安全的。

按场景选，而不是按清单接

客服与 AI 场景主要落在消息、会话与回调这三项；私域与 SCRM 更偏客户、群、好友与自动化。先圈定要用的能力域，再进去看具体接口与字段，比从头到尾读一遍清单快得多。

如果是从现有方案迁过来，因为调用形态是统一的 REST 语义，业务侧的编排逻辑基本不需要改动，主要工作量落在字段映射和回调地址切换上。评估之前建议先按上面那条最短链路在预发环境实测一遍，能力边界与覆盖范围以线上接口文档为准。