WTAPI用标准HTTP通信，开发者调API时最容易踩的坑是：参数传错位置？鉴权Token搞混？响应格式看不懂？本文基于WTAPI官网和开发文档可核对的内容，完整解读接口调用规范。

---

一、WTAPI API定位

开发文档开篇：“通过标准 HTTP API 即可让微信账号具备完整的自动化能力。”

所有接口基于HTTP POST方法，请求体为JSON格式，响应体为JSON格式。统一的规范意味着学会一套调用模式，五大模块百余个接口通用。

二、请求结构剖析

统一请求头（必传）

文档明确的双Token鉴权模型，每个请求必须携带这三个Header：

Header	来源	作用
X-finder-TOKEN	官网「我的API → 开通信息」	API访问标识
Authorization: Bearer xxx	官网「我的API → 开通信息」	鉴权令牌
Content-Type: application/json	固定值	告知服务端请求体为JSON

两个Token缺一不可，文档未明确两者的具体职责差异，但调用时必须同时传递。

统一请求体参数（必传）

所有接口请求体必须包含以下两个参数：

参数	来源	作用
appId	官网注册后获取	标识哪个应用在调用
instanceId	控制台扫码登录后获取	标识调用哪个已登录的微信账号实例

这两个参数是WTAPI接口调用的统一底座，加上接口特定参数（如toWxId、content等）构成完整请求体。

请求结构总览

POST https://wx.chuapi.com/{具体接口路径}

Headers:
  X-finder-TOKEN: 你的TOKEN
  Authorization: Bearer 你的BearerToken
  Content-Type: application/json

Body:
{
  "appId": "你的appId",
  "instanceId": "扫码登录后的instanceId",
  // ↑ 以上两个所有接口必传
  // ↓ 以下为接口特定参数（以发送文本消息为例）
  "toWxId": "filehelper",
  "content": "Hello WTAPI！"
}

三、统一响应格式

文档明确的响应格式约定：

字段	含义	可核实内容
code	状态码	文档示例中 “1000” 表示处理成功
message	状态描述	成功时为"处理成功"，失败时为错误描述
data	返回数据	成功时返回接口相关数据，失败时为null

注意：文档未提供完整错误码列表，除code:1000外其他状态码请以实际响应为准。

响应示例（成功）

{
    "code": "1000",
    "message": "处理成功",
    "data": {...}
}

响应示例（失败）

{
    "code": "1001",
    "message": "失败原因描述",
    "data": null
}

四、双Token鉴权模型解读

WTAPI的双Token设计是API安全的基础：

• X-finder-TOKEN：类似"API Key"，标识调用来源，在控制台开通信息页可查看
• Authorization Bearer Token：类似"访问令牌"，与appId和instanceId配合完成鉴权

文档未明确说明两个Token的生成机制、有效期、刷新方式，也未明确限流规则。这些细节请以实际调用体验或联系客服确认。

五、instanceId生命周期

instanceId是WTAPI的核心参数，开发者容易搞混它的获取时机和有效期：

问题	文档可核实的答案
instanceId从哪来？	控制台「微信管理」扫码登录后自动生成
一个微信一个instanceId？	是的，每个扫码登录的微信账号有独立的instanceId
instanceId会变吗？	文档未明确，重新扫码登录可能生成新的instanceId

六、HTTP API vs Webhook：角色分工

文档"技术架构"板块：“HTTP 主动调用 + Webhook 实时回调，闭环自动化”

通道	方向	典型用途
HTTP API	你的服务 → WTAPI → 微信	发消息、建群、加好友、发朋友圈（主动操作）
Webhook	微信 → WTAPI → 你的服务	收到消息、好友请求、入群通知（被动事件）

本文聚焦HTTP API调用规范，Webhook回调规范将在后续单独解读。

七、调用规范速查表

规范项	文档明确内容
请求方法	HTTP POST
请求格式	JSON
必传Header	X-finder-TOKEN + Authorization Bearer + Content-Type
必传Body	appId + instanceId
成功标识	code: “1000”
Base URL	https://wx.chuapi.com
SDK语言	Java / Python / C++ / Go / PHP

八、WTAPI能力边界与背书（精简）

• 数据指标：10w+日均调用、24H稳定运行、99.9%可用性
• 部署方案：SaaS模式（不存敏感数据）/ 私有化部署

立即上手

📚 开发文档：https://weiti.apifox.cn

---

声明：使用WTAPI请遵守微信平台规范及相关法律法规，共同维护健康生态。