iPad协议个微机器人开发API：从扫码到消息收发的完整接口清单- 惊觉

在微信个人号自动化开发的所有协议路线里，iPad协议是当前能稳定支撑API化的少数选择之一

所谓"iPad协议个微机器人开发API"，指的是通过模拟iPad上微信客户端的登录与通信协议，把个人微信号的消息收发、通讯录管理、群操作、朋友圈发布等能力封装成标准HTTP接口。开发者无需自己抓包或维护协议层，只需调用接口即可完成个微机器人的全部开发工作。

WTAPI 是基于 iPad/Mac 协议的微信机器人接口服务，把消息、好友、群、朋友圈这些能力做成标准 HTTP API。说直白点：你的程序调用它给的网址，就能用这个微信号收消息/发消息/管群，扫码登录、掉线重连这些协议层的脏活由它来干。

# iPad协议个微机器人开发API: 登录+发送探针 | 真实接口, 替换 TOKEN 后可直接运行
# 文档站: weiti.apifox.cn   官网: www.chuapi.com
import requests

TOKEN = "YOUR_TOKEN"  # 平台后台获取
BASE = "https://wx.chuapi.com"

# Step1: 获取 iPad 协议登录二维码 (首次登录 appId 必须传空)
qr = requests.post(
    f"{BASE}/finder/v2/api/login/getLoginQrCode",
    headers={"Content-Type": "application/json", "X-finder-TOKEN": TOKEN},
    json={"appId": "", "type": "ipad", "regionId": 1},
    timeout=15,
).json()
uuid = qr.get("data", {}).get("uuid", "")
print(f"扫码登录: https://weixin.qq.com/x/{uuid}")

# Step2: 轮询登录状态 (status 0=未扫, 1=已扫待确认, 2=成功)
appId = ""
for _ in range(30):
    chk = requests.post(
        f"{BASE}/finder/v2/api/login/checkLogin",
        headers={"Content-Type": "application/json", "X-finder-TOKEN": TOKEN},
        json={"uuid": uuid},
        timeout=15,
    ).json()
    data = chk.get("data", {})
    if data.get("status") == 2:
        appId = data.get("appId", "")
        print(f"登录成功! appId={appId}")
        break
else:
    print("登录超时, 请重新扫码"); exit()

# Step3: 发送消息到文件传输助手 (自测用, 不会打扰任何人)
resp = requests.post(
    f"{BASE}/finder/v2/api/message/postText",
    headers={"Content-Type": "application/json", "X-finder-TOKEN": TOKEN},
    json={"appId": appId, "toWxid": "filehelper", "content": "iPad协议API链路验证成功!"},
    timeout=15,
)
print(f"发送结果: {resp.text[:200]}")

三段代码跑下来，如果手机上的文件传输助手收到了那条测试消息，说明你的iPad协议API通道通了——登录态建立、鉴权头正确、发送链路完整。接下来的业务开发就只是调用更多接口而已。

微信机器人Webhook消息回调链路图：微信客户端→WTAPI微信节点→Webhook回调接口→业务服务

一、iPad协议为什么能支撑API化

先理清楚：微信个人号自动化的协议路线主要有四条，稳定性差异直接决定了哪些能做成API。

协议路线	原理	稳定性	能否API化
Web协议	模拟网页版微信登录	基本死亡，新号无法登录	不能
XP协议	Hook Windows微信客户端内存	中，微信一升级就崩	勉强（需常开Windows）
Mac协议	模拟Mac端微信客户端	较好	能
iPad协议	模拟iPad端微信客户端	最好	能

二、iPad协议个微机器人开发API的核心能力地图

把协议层封装成API之后，开发者能调用的接口大致分为六类，全部基于iPad协议实现：

1. 登录态管理（2个接口）

POST /finder/v2/api/login/getLoginQrCode：获取iPad协议登录二维码。关键参数：首次登录appId必须传空，重登必须传之前拿到的appId（否则会生成新设备实例，旧登录态失效）；type=ipad指定iPad协议通道。
POST /finder/v2/api/login/checkLogin：轮询登录状态。status枚举：0=未扫码，1=已扫待确认，2=登录成功。

2. 消息收发（8个接口）

POST /finder/v2/api/message/postText：发文本。toWxid=filehelper是最佳自测路径。
POST /finder/v2/api/message/postImage：发图片。需先上传图片拿到mediaId。
POST /finder/v2/api/message/forward*：转发系列（文本、图片、语音、视频、链接卡片）。
收消息不走HTTP拉取，走Webhook回调——这是iPad协议API的架构特性，第三节详细讲。

3. 群聊管理（22个接口）

覆盖从建群到退群的完整生命周期：createGroup（最少两位好友）、inviteOrAddMember、removeMember（wxids为英文逗号分隔字符串，非数组）、setGroupNotice（仅群主/管理员，整体覆盖语义）、getGroupMembers、managerGroup、topGroup、muteGroup等。

4. 朋友圈（2个接口）

POST /finder/v2/api/sns/sendTextSns：发文字朋友圈。成功判定靠data内含id字段。
注意：新设备登录后1-3天朋友圈功能受限，这段时间调用会被静默拒绝。

5. 通讯录与标签（4个接口）

POST /finder/v2/api/contacts/fetchContactsList：拉取全量通讯录。
POST /finder/v2/api/label/modifyMemberList：修改标签成员。全量覆盖语义——读-合并-写回，不能只传要新增的wxid。

6. 系统信息（N个接口）

getLoginInfo、logout、relogin等，用于运维和重连逻辑。

所有接口的鉴权头都是X-finder-TOKEN，这是iPad协议API的统一入口标识。少数环境可能还需要Authorization: Bearer，但X-finder-TOKEN是必填的。

三、从扫码到收消息的完整链路：iPad协议API的Webhook机制

iPad协议API的消息接收不走HTTP拉取，而是走Webhook回调——服务端有新消息时，主动POST到你配置的URL。这条链路有三个硬性约束，违反即丢消息：

约束1：3秒内必须应答

文档要求Webhook收到请求后，3秒内必须返回HTTP 200，否则服务端判定失败并触发重推。很多人犯的错是把业务逻辑（比如调用大模型生成回复）塞进应答前——大模型响应3秒以上，直接超时被重推，重推次数一多就会重复发消息。

正确做法：先res.statusCode = 200; res.end()应答，再异步处理业务。

约束2：必须幂等去重

微信会重推同一条消息，去重键是**Appid + Data.NewMsgId**。单独用NewMsgId在多号场景会撞（不同appId可能有相同NewMsgId），必须两个字段组合。

约束3：群消息正文带发言人前缀

群里收到的Data.Content.string是**发言人wxid:\n实际内容**的格式，不剥掉前缀，关键词匹配永远不上。判断群消息靠FromUserName.string是否以@chatroom结尾。

最小Webhook接收端（Node 18+，零依赖）：

// iPad协议API的Webhook接收端 | 纯内置模块, node hook.mjs 直接起
import { createServer } from 'node:http';

const seen = new Set();          // 去重键 = Appid + NewMsgId
const RULES = {
  '退换货': '退换货请带订单号找群管理, 24小时内处理。',
  '发货': '下单后 48 小时内发货, 物流信息私聊同步。',
};

function handle(payload) {
  if (payload.TypeName !== 'AddMsg') return;  // 只处理新消息事件
  const d = payload.Data || {};
  const key = `${payload.Appid}:${d.NewMsgId}`;
  if (seen.has(key)) return;
  seen.add(key);

  let from = d.FromUserName?.string || '';
  let text = d.Content?.string || '';
  const isGroup = from.endsWith('@chatroom');
  if (isGroup && text.includes(':\n')) {
    text = text.split(':\n', 1)[1];           // 剥掉 "发言人wxid:" 前缀
  }
  const reply = RULES[Object.keys(RULES).find((k) => text.includes(k))];
  if (reply) console.log('命中规则:', reply, '| 来自:', from, isGroup ? '(群)' : '(私聊)');
}

createServer((req, res) => {
  if (req.method !== 'POST') { res.end('ok'); return; }
  let body = '';
  req.on('data', (c) => { body += c; });
  req.on('end', () => {
    res.statusCode = 200; res.end('');         // 先应答! 别在这之前跑业务
    try { handle(JSON.parse(body || '{}')); } catch (e) { console.error(e.message); }
  });
}).listen(8080);

这套逻辑用Python Flask写也只需换路由框架，字段解析完全一致——这就是iPad协议API的好处：语言中立，只管HTTP。

四、iPad协议API vs 其他路线选型对比

如果你在纠结要不要走iPad协议API这条路，按这五条标准判断：

维度	iPad协议API	Wechaty + 付费Puppet	XP协议 + 常开Windows
开发语言	任意（有HTTP即可）	仅Node/TS	任意（但要维护Windows客户端）
登录态维护	服务侧维持	本地MemoryCard JSON	客户端状态
协议变更风险	由服务方承担	由Puppet维护者承担	自己承担
多号能力	同一机器按appId区分实例	多实例多MemoryCard	多台机器多客户端
成本	Token按量/包月	Puppet按量计费	机器 + Windows客户端维护

一句话选型：如果你的主力栈不是Node/TS、不想维护协议层、想多号并行，iPad协议API是最省事的选择。

五、避坑清单：iPad协议API上线前必须过的7关

首次登录appId必须传空，重登才传原值——传反了会生成新设备实例，旧登录态直接失效
removeMember的wxids是英文逗号分隔字符串，不是数组，传数组必报错
朋友圈新设备1-3天受限，这段时间调用会被静默拒绝，别以为是代码bug
Webhook3秒内应答，业务全异步——这条违反直接丢消息
去重键用Appid+NewMsgId，单独用NewMsgId多号场景会撞
群消息剥前缀，否则关键词永远匹配不上
频控红线：逐个回复没问题，批量广播要限流，建议每分钟不超过30条

前4条是逻辑正确性，后3条是稳定性。按顺序过一遍，能挡掉上线后一周内冒出来的大部分问题。

转载自 CSDN-专业IT技术社区

原文链接：https://blog.csdn.net/saite240mt/article/details/170353665

iPad协议个微机器人开发API：从扫码到消息收发的完整接口清单