Common.brand
Docs.badge

API 对接指南

查看生成 Key、测试接口以及在你自己的服务里完成对接的完整步骤。

如果你希望把公众号订阅消息接入自己的系统，推荐按照下面的顺序完成：

  1. 在网页端进入“个人中心 > API Key 管理”或独立的 API Key 页面
  2. 创建一个新的 API Key
  3. 先在后台里直接测试 API，确认 Key 可用
  4. 再把同一个 Key 配置到你的服务中

第一步：创建 API Key

点击打开 API Key 页面

在 API Key 管理页中输入一个便于识别的名称，例如：

  • 运营后台同步
  • 飞书机器人
  • 数据仓库增量拉取

创建后，你仍然可以在后台再次查看和复制这个 Key，但仍建议妥善保管，避免泄露。

第二步：在后台测试接口

统一 API Key 管理页已经内置了测试能力：

  • 粘贴刚生成的 Key
  • 点击“测试 API”
  • 确认可以返回订阅消息

如果这里已经能成功返回，说明鉴权和接口地址都没有问题。

第三步：在你的服务里发起请求

请求地址：

GET https://api.fafafa.ai/api/v1/wechat/messages

这里的域名部分来自系统环境变量 WORKER_PUBLIC_BASE_URL，页面会基于这个值自动拼接完整接口地址。

鉴权方式：

Authorization: Bearer YOUR_API_KEY

示例请求：

curl 'https://api.fafafa.ai/api/v1/wechat/messages?page=1&pageSize=20' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json'

推荐接入策略

首次拉取

使用 page 和 pageSize 分页读取历史消息，先完成初始化。

增量拉取

保存你上一次成功处理的时间，然后带上 since 参数，只拉取这个时间之后的新消息。

curl 'https://api.fafafa.ai/api/v1/wechat/messages?since=2026-03-19T00:00:00.000Z&page=1&pageSize=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

幂等处理

建议按文章唯一标识或原文链接去重，避免重复入库。

常见联调建议

  • Key 泄露后，直接在后台删除旧 Key，并重新创建一个
  • 测试环境和生产环境建议使用不同名称的 Key，便于排查
  • 同一个 Key 也可以复用于 MD 文件导入 API，不需要额外再申请一套
  • 如果你的系统暂时没有消息返回，先确认网页端是否已有有效订阅

建议继续在网页端完成的操作

  • 新增订阅
  • 取消订阅
  • 查看额度和套餐
  • 创建、删除和轮换 API Key

API 更适合“消费订阅消息”，网页端更适合做日常管理。