企微API集成指南——从回调到主动发送，全流程代码解析

企业微信提供了丰富的API，用于接收用户添加事件、发送消息、管理标签等。今天从实战角度，给出API集成的最佳实践，附带伪代码。

一、核心API清单

二、回调配置：接收用户添加事件

企微支持配置回调URL，当用户添加企微时，企微会POST消息到你的服务器。

回调处理逻辑：

python

# Flask示例 @app.route('/wecom/callback', methods=['POST']) def handle_add_contact(): data = request.json if data['Event'] == 'add_external_contact': user_id = data['ExternalUserID'] wecom_id = data['ToUserName'] # 哪个企微号收到添加 # 异步处理，避免超时 thread = Thread(target=async_process, args=(user_id, wecom_id)) thread.start() return "success"

异步处理函数：

python

def async_process(user_id, wecom_id): # 1. 打标签（根据来源渠道，来源信息从活码系统获取） source = get_source_by_user(user_id) # 从Redis查 add_label(user_id, source) # 2. 发送欢迎语 welcome_msg = get_welcome_template(source) send_message(user_id, welcome_msg) # 3. 记录统计 incr_stats(source, 'add')

三、主动发送消息

python

def send_message(user_id, content): token = get_access_token(wecom_id) url = f"https://qyapi.weixin.qq.com/cgi-bin/externalcontact/send?access_token={token}" payload = { "touser": user_id, "msgtype": "text", "text": {"content": content} } response = requests.post(url, json=payload) # 处理限频：如果返回45009，等待1秒后重试 if response.json()['errcode'] == 45009: time.sleep(1) return send_message(user_id, content) return response.json()

四、access_token管理

access_token有效期2小时，需缓存并定时刷新。

python

class TokenManager: def __init__(self, corp_id, secret): self.corp_id = corp_id self.secret = secret self.token = None self.expire_at = 0 def get_token(self): if time.time() > self.expire_at: self.refresh() return self.token def refresh(self): url = f"https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid={self.corp_id}&corpsecret={self.secret}" resp = requests.get(url).json() self.token = resp['access_token'] self.expire_at = time.time() + 7000 # 提前200秒刷新

五、错误处理与重试机制

企微API会返回各种错误码，需要分类处理：

重试装饰器示例：

python

def retry_on_limit(max_retries=3): def decorator(func): def wrapper(*args, **kwargs): for i in range(max_retries): result = func(*args, **kwargs) if result.get('errcode') == 45009: time.sleep(1 * (i+1)) continue return result return None return wrapper return decorator

六、企销宝的API封装

企销宝将这些API封装成统一的RESTful接口，开发者无需处理token、限频、重试等细节。调用示例：

text

POST https://api.qixiaobao.com/v1/send { "user_id": "xxx", "content": "欢迎语", "channel": "douyin" }

返回结果包含成功/失败状态，以及耗时统计。

总结3个要点：

• 核心API：添加事件回调、发送消息、打标签。

• 技术要点：token缓存、异步处理、重试机制、错误分类。

• 第三方封装可大幅降低开发成本。
  行动建议： 先用企微官方文档跑通回调流程，再逐步接入自动化逻辑。
  觉得代码干货？收藏+转发给你的后端开发。