企业微信营销 API 怎么用

三类接口，三种时间尺度

先把差异摆出来，后面所有设计决策都从这张表推出来。

• 触达（发消息、群发、群内推送）：秒级同步、要限速、发出去不可撤回，失败必须当场知道
• 标签（打标、改备注、分组）：分钟级最终一致、可重复写、天然幂等，晚几分钟生效不影响业务
• 回流（行为事件、转化数据、报表）：天级聚合、允许迟到、必须可重算，追求实时的回流基本都在浪费钱

三者的错误处理策略因此完全不同：触达失败要限次重试并留下明确终态，标签失败可以无脑重放，回流失败最好的处理往往是等下一轮批处理自己修好。把它们塞进同一个重试框架，你会得到一个既不敢重试触达、又对回流过度紧张的系统。

一次完整的营销动作必然横跨这三类，所以不要指望一个同步调用把事情做完。设计的第一步是承认它们不在一个时间尺度上，并为每一类单独选一致性要求。

触达类：难的是发之前，不是发出去

发送本身是三类里最简单的一环 —— 在 wecomapi 里它就是一次带鉴权的 POST。真正决定这套系统事后能不能复盘的，是发送之前那三步做没做。

1. 1归因标识必须在发送前生成。发完再想办法把消息和活动对上，永远对不齐 —— 同一个客户可能同时挂在三条流程里。
2. 2收件名单的求值时机必须显式声明，并把结果存成带 ID 的快照。提交时冻结还是执行时逐批求值都可以，不声明就会变成边查边发 —— 名单在执行过程中变化，导致重发、漏发，以及事后无法解释「为什么他收到了」。
3. 3发送意图先落库，再调接口。顺序反过来的系统，一旦进程挂在调用中间，你分不清那条消息到底发没发。

// 示意逻辑，字段与错误结构以线上文档为准
const taskId = await outbox.create({ campaignId, snapshotId, toId });

const res = await http.post("https://manager.wecomapi.com/message/sendText", {
  guid:    accountGuid,
  toId:    toId,
  content: renderTemplate(templateId, vars),
});

// 成功 / 失败 / 超时未知，三种终态分开记，不要合并成布尔值
await outbox.settle(taskId, res);

「超时未知」必须是一个独立终态。把它并进失败，补偿逻辑会重发；并进成功，对账时会少一条。这个字段在上线第一周看着多余，到第一次网络抖动的时候会救你一整天。

标签类：调用很简单，难的是谁有权写

打标签的调用没什么难度，麻烦全在多方写入上。标签几乎是营销系统里唯一被三方同时改的数据：人工在会话里手动打、自动化规则按行为打、外部系统按订单同步打。

• 每个标签定一个唯一写入方。允许多方写的标签，最终会变成谁最后跑谁说了算。
• 冲突按来源优先级解决，优先级写在一处配置里，不要散在各个任务的代码里。
• 自动打的和人工打的要能区分。人工修正过的标签，自动规则默认不覆盖 —— 否则销售改一次，第二天被脚本改回去，第三次他就不改了。

另一条硬规矩：别用标签存流程状态。「当前处于第几步」「上次触达时间」这类东西属于你自己的库。写进标签体系会让标签数量随流程组合爆炸，而且标签的写入是最终一致的，拿它当状态机的持久层，判断条件迟早会读到旧值并触发一次不该发生的触达。

回流类：平台给行为，转化得你自己接住

这一类最容易被跳过，因为它不产生任何可见效果。但它是整套系统里唯一能回答「值不值得继续做」的部分，跳过它等于把营销做成了一次性投放。

要分清两段数据的来源：平台侧能给的是行为 —— 消息发出去了、对方回了一句、有人进了群；转化只可能来自你自己的业务系统 —— 下单、续费、报名成功。用 wecomapi 的事件回调接住行为侧，用业务库接住转化侧，两段靠发送时生成的归因标识串起来，这是唯一可靠的拼法。

• 归因标识必须在触达之前就存在，事后关联一定对不齐
• 归因窗口要显式定义：一条消息发出后多久内的转化算它的？7 天和 30 天算出来的结论完全不同，而这个数字定了就别频繁改，否则历史数据没法比
• 回流迟到是常态，报表要能按天整体重算，不要在事件到达时就地累加
• 行为信号和转化信号分开存，别提前合成一个「效果」字段，合成之后就拆不回去了

还有一处几乎人人踩：所有比率的分母必须来自发送侧自己的记录，不能拿平台事件反推。前面那个「超时未知」的终态在事件里根本不会出现，用事件反推发送量会把分母算小，回复率和转化率跟着一起虚高 —— 而且虚高得不多，正好落在「看着还算合理」的区间里，几个月都不会有人怀疑。

调用量估错的地方，几乎都在读

排期时大家算的都是写：一万人的活动就是一万次发送。先顶不住的却往往是读 —— 发出去之前要确认这个人还在名单里、没退订、没被另一条流程刚碰过、频次预算还有余量，一条消息背后挂着四五次查询，量级立刻翻上去一个档。

1. 1能冻结的判据一律冻结进名单快照。分层结果、内容选择、客户属性这些，在生成名单那一刻求值一次就够；发送时再查一遍不只是慢，还会让同一批人前后适用两套标准 —— 上午发的和下午发的，实际跑的规则已经不是同一版了。
2. 2必须实时查的只有退订和人工态两项。它们的共同点是晚一秒就会造成不可撤回的错误，其余判据过期一小时都算不上事故。把这两项做成发送出口前的一次本地查询，别塞回上游编排里，否则每加一条流程就要重新实现一遍，也就迟早会漏掉一条。
3. 3快照里要连判断依据一起存，不能只存收件人 ID。一个活动分三批发、中途改过一次分层规则，只存 ID 的后果是你看到三批人的表现差得很远，却没有任何办法复原当时各自是按什么口径挑出来的。

落到实现上，发送阶段应该薄到一眼能看完：取一条待发记录、做两项实时检查、调一次 wecomapi 的发送接口、回写终态。这四步之外冒出来的任何查询，都值得先问一句它为什么不能提前到名单生成的时候做完。

拼成一条链路，接缝在这三处

三类各自做对了，还会在交界处出问题。以下三处是实际项目里返工率最高的。

1. 1标签变更触发触达，必须去抖。一次批量导入会瞬间产生成千上万条标签变更，直接接到触达上，等于自己给自己发起一次压测。合并窗口和按账号限速两个都要，只做一个不够。
2. 2触达失败不要回滚标签。标签记的是事实（这个人属于哪一类），触达记的是结果（这次有没有发出去），两本账。混在一起之后，重试逻辑会开始修改客户属性，而没有人会想到去那里找 bug。
3. 3回流改标签走批量异步。在回调里同步改标签，会让一次转化高峰把标签写入的并发顶满，进而拖垮正在跑的触达任务 —— 效果最好的那天，系统最容易崩。