企业微信 API 开发怎么入门

第一条链路只有三步

无论最终要做客服、SCRM 还是内部通知，起点都一样：拿到调用凭证 → 发出一条消息 → 收到一个事件。这三步跑通，你就验证了鉴权、网络、回调地址三件最容易出问题的事，剩下的都是在这条链路上加能力。

顺序不建议换。先发消息、后接回调，是因为发送失败的原因高度集中 —— 凭证不对、网络不通、目标填错，基本三选一，十分钟内能定位；而回调收不到的原因散在你自己的服务、公网可达性、平台侧配置三处。先把确定性高的那一步拿下，后一步的排查范围会小一大截。反过来先配回调，最常见的结局是卡在「收不到推送」上，而此时你连凭证有没有效都还没验证过。

1. 1创建应用、拿到调用凭证。这一步产出的是后续所有请求都要带的 Token。
2. 2调发送消息接口，往一个测试会话发一条文本。HTTP 层和业务层都返回成功，说明鉴权与网络通了 —— 这两层要分开判，判定方式与具体取值以线上接口文档为准。
3. 3配置回调地址，让消息事件推到你的服务。能收到一次推送，闭环就成立了。

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

三种「看起来通了」，其实没通

入门阶段最费时间的不是报错，是不报错的失败：三步看着都过了，链路其实停在半路。下面三种最常见，而且都发生在上面那三步里。

• 「HTTP 层通了就算成功」：上一步强调过两层要分开判，但第一版代码里最常见的仍然是只看了传输层，于是「没发出去」被记成「已发送」，直到有人问怎么没收到。判定方式与取值以线上接口文档为准，第一版就把两层的结果分别打进日志。
• 「消息发出去了，但哪都看不到」：先确认 guid 指的是不是你正盯着的那个账号、toId 指的是不是你正打开的那个会话。这两个值建议一开始就写进配置并注明各自指向谁，每次手拼参数是这一步最主要的事故来源。
• 「回调已经配好了」：保存配置时收到的那一次是验证请求，不是业务事件。必须由一条真实消息触发一次推送、而且你的服务真的解析出了内容，这一步才算数。

回调是分水岭

只会发消息的系统是单向的，能收到事件才算接进去了。用 wecomapi 的事件回调把消息推到自己的服务，工程要点就四条，但每一条踩了都很疼：回调地址必须公网可达且是 HTTPS；保存配置时平台会先发一次验证请求，要按要求原样回应；收到事件先快速返回 2xx 再入队异步处理，不要在回调里跑业务；用事件 ID 做幂等，因为重复投递一定会发生。

• 回调里做耗时操作 → 平台判超时 → 触发重试 → 你的系统被自己压垮
• 不做幂等 → 一条消息回复三次 → 客户投诉
• 本地开发没有公网地址 → 用内网穿透先把链路调通，别等部署到线上再试

入门时偶尔会有人问：能不能先不接回调，用定时拉取顶一阵？顶得住，但要清楚顶掉的是什么 —— 拉取只能看到「现在是什么状态」，中间发生过什么补不回来，而那恰恰是即时应答类需求的全部依据。三种取数形态的代价对比，站内讲长连接的那篇摊开算过；对入门链路来说结论足够简单：目标里只要有「实时」两个字，第三步就别跳。

新手最常绕的三段弯路

第一段：一上来就对齐数据模型。客户、标签、部门、外部群怎么映射到自己的库里，这件事在没跑通链路之前想不清楚，想清楚了也大概率要改。先用最粗的结构跑起来。

第二段：自己封装 SDK。以 REST 接入为主的接口，Node、Python、Java、Go 直接发 HTTP 请求就行。在只调三个接口的阶段封装一层，收益为零、维护成本先到。

第三段：跳过错误码。联调阶段把完整的请求体、响应体和请求标识打进日志，比任何调试技巧都管用。参数错误、权限不足、频控三类问题占了新手全部问题的绝大多数，而它们在 wecomapi 的返回里是明确区分的。

入门阶段的两个取舍

第一周会撞上两个选择题，两边都有人踩过，值得提前想清楚。

一是拿哪个账号联调。最好别和生产共用：测试消息会真的发到对面，而收到的人分不清哪条是测试，这类事故没有撤回按钮。代价在成本这一侧 —— 订阅按账号算，多开一个开发实例就是多一份固定开销，wecomapi 的计费单位是账号数、与调了多少次无关，所以这笔账在立项时就能估准。团队小、消息量低时共用也不是不行，但要提前约定哪些会话不许当测试对象，并且把生产账号的 guid 从开发配置里彻底拿掉，别指望靠记性。

二是联调时敢不敢多发。订阅内不按调用次数计费，重试、重放、把同一条用例跑上二十遍都不会变成账单，只要守住公平使用策略、别把明显异常的调用模式打到共享环境上就行。真正该省的是发进真人会话的消息条数：那笔成本不记在账单上，记在对方的耐心里，所以测试的收件方优先选自己或一个内部群。

还有一个顺序上的取舍：先接第二个能力，还是先把第一个接稳？判断依据只有一条 —— 这条链路的另一端有没有坐着真实客户。只在内部群里跑，怎么折腾都行；一旦客户能收到消息，新能力就得排在稳定性后面，因为在 IM 里，一次错发的可见度远高于一个还没上线的功能。

跑通之后往哪扩

闭环成立后，按业务方向挑一条加深：做客服和 AI 的往「消息 + 会话 + 回调」走，做私域和 SCRM 的往「客户 + 标签 + 外部群」走。两条都不急着同时做 —— 先让一条产生业务价值，再谈第二条。

加能力之前，先拿三个问题量一下现在这条链路：一条消息发出去之后，你能不能查到它什么时候发的、发给谁、对方怎么回的；同一个事件推两次，你的处理会不会跑两遍；服务重启的那十分钟里推过来的事件，是补得回来还是直接丢了。三个都答得上，后面加什么都是加法；有答不上的，先补这三条 —— 它们是所有能力共用的地基，越往后补，改动面越大。