最近有不少同学私信问我：个人微信 API 如何接入？有没有完整的开发流程？遇到过哪些坑？

作为一名有两年微信自动化开发经验的开发者，我将自己的实战经验整理成这篇教程。内容涵盖从获取凭证到生产部署的完整流程，以及我遇到过的典型问题与解决方案。

如果你正在准备接入个人微信 API，这篇文章应该能帮你节省大量的调试时间。

一、Eyun 平台简介

Eyun 是一个个人微信执行与调度平台，提供标准的 RESTful API，让 AI Agent、CRM、ERP 等业务系统能够直接驱动微信执行消息发送、事件回调与任务编排等操作。

核心能力

• 消息发送：支持文字、图片、文件等多种格式
• 事件回调：实时将微信消息推送至您的业务系统
• 多账号管理：同时管理数百到数千个微信号
• 执行编排：支持复杂的业务流程自动化

---

二、开发流程总览

整个 API 调用的开发流程可拆分为五个阶段：

每个阶段都有明确的目标和注意事项，下面将逐一拆解。

---

三、第一阶段：获取凭证

目标

获取调用 API 所需的凭证与权限。

操作步骤

1. 打开 Eyun 开发者页面 并注册账号
2. 进入「API 开通信息」页面
3. 保存以下两个关键信息：
   • API 地址：https://api.wkteam.cn
   • API Key：类似 sk-xxx... 的长字符串

常见问题

Q：API Key 遗忘了怎么办？
A：您可以在控制台撤销旧的 Key 并重新生成。请注意，重新生成后，旧的 Key 将立即失效，您需要同步更新所有调用方的配置。

Q：凭证可以多人共用吗？
A：从技术上讲可以，但不推荐这样做。建议为每个服务使用独立的凭证，以便于权限管理和问题排查。

四、第二阶段：登录实例

目标

登录微信实例，获取实例标识（wId）。

操作步骤

1. 在控制台进入「微信管理」
2. 点击「扫码登录」
3. 手机微信扫码确认
4. 保存登录信息：
   • wId：实例 ID，调用接口时必须传入。
   • wcId：微信 ID，重登时需要。

常见问题

Q：wId 和 wcId 有什么区别？
A：wId 是登录的“凭证”，用于标识当前登录的实例。wcId 是微信账号的唯一标识，类似于微信号。所有 API 调用都需要传递 wId。

Q：登录后多久会掉线？
A：首次登录后 24 小时内可能掉线一次，之后会稳定一段时间。掉线后重新登录即可。

五、第三阶段：基础调用

目标

跑通第一个 API 调用，验证链路是否通畅。

最小可用示例

用 curl 发送一条测试消息到文件传输助手：

curl -X POST https://api.wkteam.cn/sendText \
  -H "Content-Type: application/json" \
  -H "Authorization: sk-xxx..." \
  -d '{
    "wcId": "filehelper",
    "content": "Hello WeChat"
  }'

测试要点：

• 用filehelper（文件传输助手）做测试，不会打扰真实用户
• 成功标志：手机微信收到测试消息
• 响应返回code: "1000"

常见问题

Q：返回“鉴权失败”怎么办？
A：检查 API Key 是否正确，是否多传或少传了字符。注意 Authorization 请求头的格式。

Q：返回“资源不存在”怎么办？
A：检查 wcId 是否正确。好友 ID 通常为 wxid_xxx，群 ID 以 @chatroom 结尾。

Q：接口返回成功，但手机没收到消息？
A：可能原因：1）微信实例已下线；2）网络延迟；3）消息被微信安全机制拦截。

六、第四阶段：异常处理

目标

建立完整的错误处理机制，保障系统稳定运行。

核心机制

1. 错误码分类处理

错误码	含义	处理方式
1000	成功	正常处理
1001	参数错误	检查并修正参数
1002	鉴权失败	重新获取 API Key
1005	频率超限	等待一段时间后重试
2001	网络异常	重试或切换网络

2. 重试策略

只对临时性错误（网络超时、频率限制）重试，参数错误、鉴权失败不重试。

def call_with_retry(api_func, max_retry=3):
    """带重试的 API 调用"""
    for i in range(max_retry):
        result = api_func()
        if result.get("code") == "1000":
            return result
        elif result.get("code") == "1005":
            time.sleep(2 ** i)  # 指数退避
        elif result.get("code") in ("1001", "1002"):
            return result  # 永久错误直接返回
    return result

3. 日志记录

每次 API 调用都要记录：时间、接口名、请求参数、响应结果、耗时。出现问题时可快速定位。

常见问题

Q：重试后仍然失败怎么办？
A：超过最大重试次数后，系统会记录日志并返回错误。此时可考虑切换备用凭证或账号。

Q：如何避免重复重试？
A：为每次请求添加唯一 ID，由服务端进行去重处理，以避免向用户发送重复消息。

七、第五阶段：生产部署

目标

将开发完成的 API 稳定部署到生产环境。

关键配置

1. 凭证管理

• API Key 应存储在环境变量中，避免硬编码到代码里。
• 支持多 Key 轮询，以降低单个 Key 被限流的风险。

2. 限流控制

• 全局每秒最多 5 次调用
• 单用户每分钟最多 30 次调用
• 高峰期可使用队列进行异步处理。

3. 监控告警

• API 调用成功率低于 95% 时触发告警
• 平均响应时间超过 1 秒时触发告警
• 错误码分布：1005（限流）占比过高告警

八、开发流程检查清单

阶段	检查项	完成标准
获取凭证	API Key 是否正确	能成功调用接口
登录实例	wId 是否有效	实例状态为在线
基础调用	消息能否正常发送	FileHelper 能收到测试消息
异常处理	错误码是否分类处理	临时性错误自动重试
生产部署	监控告警是否配置	异常能及时发现

---

九、总结

个人微信API 的开发流程，核心就是五步法：获取凭证 → 登录实例 → 基础调用 → 异常处理 → 生产部署。

每个阶段都有明确的目标和注意事项，遵循此流程能避免大部分常见问题。常见问题主要集中在：

• 凭证和实例 ID 混用
• 未实现重试机制导致临时性错误演变为永久性故障
• 日志记录不完善导致问题排查困难

掌握这套流程后，基本能够独立完成微信API的接入与部署工作。