企业官网建设流程全解析

动手写代码之前，有四个概念必须先搞清楚。这四个概念不明白，后面每个接口都会调得稀里糊涂。

一、标识体系：wId 和 Token 分别是什么

API 体系里有两个关键标识。Token 是你这个应用的身份凭证，调用所有接口都要带上，证明"是哪个开发者在调"。wId 是一个微信实例的标识，证明"操作的是哪个微信号"。

一个 Token 下可以有多个 wId（多开场景），接口调用时两个都要传：Token 放请求头鉴权，wId 放请求参数里指定实例。混淆这两个，是新手最常见的报错原因。

二、收发模型：主动请求和事件回调

程序和微信之间有两条方向相反的通道。主动请求是你调接口（发消息、查列表），HTTP 调用即时返回结果。事件回调是微信把事件推给你（新消息、好友申请、掉线），你需要提前配好 Webhook 地址。

回调有个硬规则：5 秒内必须返回响应，否则触发重试，最多 3 次。这意味着回调里不能干重活，处理逻辑要丢异步队列。

三、消息结构：回调数据长什么样

回调消息是 JSON，关键字段有：消息类型（文本、图片、群消息）、发送人标识（fromUser）、内容（content，类型不同含义不同）、群 ID（群消息才有）、时间戳。

发消息（sendText）则要提供 wId、toUser、content 三个必填参数。收发两端的数据结构对上号，消息闭环才能跑通。

四、错误处理：返回码怎么读

接口返回 JSON 里带 code 字段：1000 成功、1001 参数错误、1002 Token 过期、1004 频率限制。每个非 1000 都有对应处理方式——1002 要重新获取 Token，1004 要退避等待后重试。

不读返回码直接假设成功，是线上事故的常见来源：消息没发出去，程序却以为发了。

四个入门概念对照

最小验证代码

import requests # 1. 主动请求：发消息（理解 Token + wId + 三参数） r = requests.post("https://api.eyunz.com/v1/sendText", headers={"Authorization": "你的Token"}, json={"wId": "你的wId", "toUser": "文件传输助手或自己的wxid", "content": "入门测试"}) print(r.json()) # 4. 读返回码：看到 code=1000 就是通了 # 2. 事件回调：配好地址后，5秒内响应 # @app.post("/webhook") # def cb(): return {"code": "1000"}

落地建议

入门最完整的说明在 Eyun 开发文档。建议学习顺序：先搞懂 Token 和 wId（5 分钟），用最小代码发一条消息（验证鉴权），再配回调收一条消息（理解 5 秒规则），最后研究错误码处理。四个概念都用代码验证过一遍，再开始正式开发，会少踩很多坑。平台开通入口见 Eyun 官网。