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

企业微信提供了丰富的API用于接收用户添加事件、发送消息、管理标签等。今天从实战角度给出API集成的最佳实践附带伪代码。一、核心API清单API用途频率限制获取access_token调用其他API的前提2000次/分钟添加外部联系人通过好友每个号300人/天发送文本消息发欢迎语每个号600条/分钟添加标签打标签每个号100次/分钟获取客户详情查询用户信息每个号60次/分钟二、回调配置接收用户添加事件企微支持配置回调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(targetasync_process, args(user_id, wecom_id)) thread.start() return success异步处理函数pythondef 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)三、主动发送消息pythondef send_message(user_id, content): token get_access_token(wecom_id) url fhttps://qyapi.weixin.qq.com/cgi-bin/externalcontact/send?access_token{token} payload { touser: user_id, msgtype: text, text: {content: content} } response requests.post(url, jsonpayload) # 处理限频如果返回45009等待1秒后重试 if response.json()[errcode] 45009: time.sleep(1) return send_message(user_id, content) return response.json()四、access_token管理access_token有效期2小时需缓存并定时刷新。pythonclass 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 fhttps://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会返回各种错误码需要分类处理错误码含义处理策略40014token无效强制刷新token后重试45009调用频率超限等待1秒后重试最多3次45035用户不是外部联系人忽略48002API权限不足检查应用权限配置重试装饰器示例pythondef retry_on_limit(max_retries3): 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 * (i1)) continue return result return None return wrapper return decorator六、企销宝的API封装企销宝将这些API封装成统一的RESTful接口开发者无需处理token、限频、重试等细节。调用示例textPOST https://api.qixiaobao.com/v1/send { user_id: xxx, content: 欢迎语, channel: douyin }返回结果包含成功/失败状态以及耗时统计。总结3个要点核心API添加事件回调、发送消息、打标签。技术要点token缓存、异步处理、重试机制、错误分类。第三方封装可大幅降低开发成本。行动建议 先用企微官方文档跑通回调流程再逐步接入自动化逻辑。觉得代码干货收藏转发给你的后端开发。