API 文档

WeAPI 提供标准 RESTful API 接口，采用 JWT 和 API Key 双重认证方式。所有接口均返回 JSON 格式数据。

平台概述

WeAPI 是一个基于 HTTP 的 RESTful API 服务，为开发者提供稳定可靠的微信消息收发能力。通过标准化的 API 接口，你可以轻松将微信消息通道集成到自己的业务系统中。

平台核心能力包括：

API 基础地址为：https://api.40hh.cn。所有接口请求和响应均为 JSON 格式，请正确设置 Content-Type: application/json 请求头。

速率限制： 免费版 100 次/日，基础版 1,000 次/日，专业版 5,000 次/日，企业版 50,000 次/日。超出限制将返回 429 状态码。

快速开始

从注册到完成第一次 API 调用只需 5 分钟：

  1. 注册账号 — 在 注册页面 填写用户名和密码完成注册
  2. 登录控制台 — 使用注册的用户名和密码 登录控制台
  3. 创建 API Key — 在控制台的 API Key 管理页面创建新的密钥
  4. 调用接口 — 使用 API Key 调用消息发送接口，开始收发消息
提示： 新注册用户自动获得免费版额度，无需付费即可开始体验。

接入指南

以下三步帮助你快速完成 WeAPI 的接入：

第一步：创建 API Key

登录 WeAPI 控制台，在"API Key 管理"页面点击"创建密钥"，输入名称（如"生产环境"），即可生成一个 API Key。请妥善保存。

第二步：扫码登录微信账号

在控制台的"账号管理"页面，点击"添加账号"获取登录二维码，使用微信扫描二维码完成授权登录。登录成功后，账号状态将变为"在线"。

第三步：调用消息接口

使用 API Key 调用消息发送接口，向指定联系人发送消息：

curl -X POST "https://api.40hh.cn/api/v1/messages/send-text" \
  -H "Authorization: Bearer gw_live_你的APIKey" \
  -H "Content-Type: application/json" \
  -d '{
    "toWxid": "wxid_目标联系人的wxid",
    "content": "你好，这是一条来自 WeAPI 的测试消息"
  }'

认证方式

WeAPI 支持两种认证方式，可根据使用场景选择：

JWT 认证（控制台用户）

通过注册/登录接口获取 JWT Token，适用于控制台用户身份认证。在请求头中携带：

Authorization: Bearer <your_jwt_token>

API Key 认证（服务端调用）

在控制台生成 API Key，适用于服务端自动化调用。在请求头中携带：

Authorization: Bearer <your_api_key>
区别： JWT Token 用于控制台用户身份认证，有效期较短；API Key 权限范围更广，适合服务端长期自动化调用。API Key 以 gw_live_ 开头。

注册

POST /api/v1/auth/register 创建新用户账号

请求参数

参数名类型必填说明
usernamestring是用户名，3-32 个字符
emailstring否邮箱地址
passwordstring是密码，至少 8 位

请求示例

curl -X POST "https://api.40hh.cn/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "myuser",
    "password": "mypassword123"
  }'

响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "userId": "u_abc123",
    "username": "myuser",
    "token": "eyJhbGciOiJIUzI1NiIs..."
  }
}

登录

POST /api/v1/auth/login 用户登录获取 Token

请求参数

参数名类型必填说明
usernamestring是用户名或邮箱
passwordstring是登录密码

请求示例

curl -X POST "https://api.40hh.cn/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "myuser",
    "password": "mypassword123"
  }'

响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "expiresAt": "2026-07-27T14:00:00Z"
  }
}

个人资料

GET /api/v1/profile 获取当前用户信息

请求头

参数名类型必填说明
Authorizationstring是Bearer Token 或 API Key

请求示例

curl -X GET "https://api.40hh.cn/api/v1/profile" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "userId": "u_abc123",
    "username": "myuser",
    "email": "user@example.com",
    "plan": "basic",
    "createdAt": "2026-06-01T08:00:00Z"
  }
}

API Key 列表

GET /api/v1/keys 获取当前用户的所有 API Key

请求参数

参数名类型必填说明
pageint否页码，默认 1
pageSizeint否每页数量，默认 20

请求示例

curl -X GET "https://api.40hh.cn/api/v1/keys" \
  -H "Authorization: Bearer gw_live_3c9x..."

响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "total": 3,
    "items": [
      {
        "keyId": "ak_abc123",
        "name": "生产环境",
        "prefix": "gw_live_",
        "status": "active",
        "createdAt": "2026-06-15T10:00:00Z"
      }
    ]
  }
}

创建 API Key

POST /api/v1/keys 创建新的 API Key

请求参数

参数名类型必填说明
namestring是API Key 名称标识
expiresInint否过期天数，不传则永不过期

请求示例

curl -X POST "https://api.40hh.cn/api/v1/keys" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "测试环境",
    "expiresIn": 90
  }'

响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "keyId": "ak_def456",
    "name": "测试环境",
    "apiKey": "gw_live_7x8y9z0a1b2c3d4e",
    "expiresAt": "2026-09-25T10:00:00Z"
  }
}

账号列表

GET /api/v1/accounts 获取已绑定的微信账号列表

请求参数

参数名类型必填说明
statusstring否筛选状态：online / offline / all

请求示例

curl -X GET "https://api.40hh.cn/api/v1/accounts" \
  -H "Authorization: Bearer gw_live_3c9x..."

响应示例

{
  "code": 0,
  "message": "ok",
  "data": [
    {
      "accountId": "wa_001",
      "wxid": "wxid_abc123",
      "nickname": "客服-小明",
      "avatar": "https://...",
      "status": "online",
      "lastActiveAt": "2026-06-27T10:30:00Z"
    }
  ]
}

获取登录二维码

POST /api/v1/accounts/:id/login-qr 获取微信扫码登录二维码

路径参数

参数名类型必填说明
idstring是账号 ID（路径参数）

请求示例

curl -X POST "https://api.40hh.cn/api/v1/accounts/wa_001/login-qr" \
  -H "Authorization: Bearer gw_live_3c9x..." \
  -H "Content-Type: application/json" \
  -d '{}'

响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "qrUrl": "https://api.40hh.cn/qr/abc123",
    "qrBase64": "data:image/png;base64,iVBORw0KGgo...",
    "expiresAt": "2026-06-27T11:00:00Z",
    "loginId": "li_xyz789"
  }
}

发送文本消息

POST /api/v1/messages/send-text 发送文本消息到微信

请求参数

参数名类型必填说明
toWxidstring是接收方微信号（联系人 wxid 或群 id）
contentstring是消息内容，最多 2048 字
accountIdstring否指定发送账号，默认使用主账号

请求示例

curl -X POST "https://api.40hh.cn/api/v1/messages/send-text" \
  -H "Authorization: Bearer gw_live_3c9x..." \
  -H "Content-Type: application/json" \
  -d '{
    "toWxid": "wxid_abc123def456",
    "content": "您好，您的验证码是 2048，5 分钟内有效。"
  }'

响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "msgId": "msg_xyz789",
    "status": "sent",
    "timestamp": 1719480000
  }
}

消息历史

GET /api/v1/messages 查询消息发送历史

请求参数

参数名类型必填说明
wxidstring否按联系人筛选
startTimestring否开始时间，ISO 8601 格式
endTimestring否结束时间，ISO 8601 格式
pageint否页码，默认 1
pageSizeint否每页数量，默认 20

请求示例

curl -X GET "https://api.40hh.cn/api/v1/messages?page=1&pageSize=20" \
  -H "Authorization: Bearer gw_live_3c9x..."

响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "total": 128,
    "items": [
      {
        "msgId": "msg_xyz789",
        "type": "text",
        "content": "您好，您的验证码是 2048",
        "toWxid": "wxid_abc123",
        "status": "sent",
        "createdAt": "2026-06-27T10:00:00Z"
      }
    ]
  }
}

联系人列表

GET /api/v1/contacts 获取微信联系人列表

请求参数

参数名类型必填说明
accountIdstring否指定账号 ID，默认使用主账号
keywordstring否搜索关键词

请求示例

curl -X GET "https://api.40hh.cn/api/v1/contacts" \
  -H "Authorization: Bearer gw_live_3c9x..."

响应示例

{
  "code": 0,
  "message": "ok",
  "data": [
    {
      "wxid": "wxid_def456",
      "nickname": "张三",
      "remark": "客户-张三",
      "avatar": "https://..."
    }
  ]
}

群列表

GET /api/v1/groups 获取微信群列表

请求参数

参数名类型必填说明
accountIdstring否指定账号 ID，默认使用主账号

请求示例

curl -X GET "https://api.40hh.cn/api/v1/groups" \
  -H "Authorization: Bearer gw_live_3c9x..."

响应示例

{
  "code": 0,
  "message": "ok",
  "data": [
    {
      "groupWxid": "xxx_group_id",
      "name": "项目讨论群",
      "memberCount": 42,
      "ownerWxid": "wxid_abc123"
    }
  ]
}

Webhook 管理

GET /api/v1/webhooks 查询 Webhook 列表

请求示例

curl -X GET "https://api.40hh.cn/api/v1/webhooks" \
  -H "Authorization: Bearer gw_live_3c9x..."

响应示例

{
  "code": 0,
  "message": "ok",
  "data": [
    {
      "webhookId": "wh_001",
      "url": "https://your-server.com/webhook",
      "events": ["message.receive", "message.send"],
      "status": "active",
      "createdAt": "2026-06-20T08:00:00Z"
    }
  ]
}
POST /api/v1/webhooks 创建 Webhook

请求参数

参数名类型必填说明
urlstring是回调地址，HTTPS
eventsarray是订阅事件列表
secretstring否签名密钥

请求示例

curl -X POST "https://api.40hh.cn/api/v1/webhooks" \
  -H "Authorization: Bearer gw_live_3c9x..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["message.receive"],
    "secret": "your_webhook_secret"
  }'

响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "webhookId": "wh_002",
    "url": "https://your-server.com/webhook",
    "events": ["message.receive"],
    "status": "active",
    "createdAt": "2026-06-27T12:00:00Z"
  }
}
PUT /api/v1/webhooks/:id 更新 Webhook 配置

请求参数

参数名类型必填说明
statusstring否active / paused

请求示例

curl -X PUT "https://api.40hh.cn/api/v1/webhooks/wh_001" \
  -H "Authorization: Bearer gw_live_3c9x..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "paused"
  }'

响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "webhookId": "wh_001",
    "status": "paused"
  }
}
DELETE /api/v1/webhooks/:id 删除 Webhook

请求示例

curl -X DELETE "https://api.40hh.cn/api/v1/webhooks/wh_001" \
  -H "Authorization: Bearer gw_live_3c9x..."

响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "webhookId": "wh_001",
    "deleted": true
  }
}

套餐列表

GET /api/v1/plans 获取所有可用套餐

请求示例

curl -X GET "https://api.40hh.cn/api/v1/plans"

响应示例

{
  "code": 0,
  "message": "ok",
  "data": [
    { "planId": "free", "name": "免费版", "price": 0, "requestsPerDay": 100, "maxAccounts": 1 },
    { "planId": "basic", "name": "基础版", "price": 9900, "requestsPerDay": 1000, "maxAccounts": 3 },
    { "planId": "pro", "name": "专业版", "price": 29900, "requestsPerDay": 5000, "maxAccounts": 10 },
    { "planId": "enterprise", "name": "企业版", "price": 99900, "requestsPerDay": 50000, "maxAccounts": 50 }
  ]
}

创建订阅

POST /api/v1/subscriptions 创建套餐订阅订单

请求参数

参数名类型必填说明
planIdstring是套餐 ID
periodstring否monthly / yearly

请求示例

curl -X POST "https://api.40hh.cn/api/v1/subscriptions" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "planId": "basic",
    "period": "monthly"
  }'

响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "subscriptionId": "sub_abc123",
    "planId": "basic",
    "period": "monthly",
    "status": "active",
    "expiresAt": "2026-07-27T12:00:00Z"
  }
}

SDK 示例

以下示例展示如何使用不同语言调用 WeAPI 接口发送消息。

Python 示例

# pip install requests
import requests

API_KEY = "gw_live_your_api_key"
BASE_URL = "https://api.40hh.cn"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# 发送文本消息
payload = {"toWxid": "wxid_abc123", "content": "你好，这是一条来自 WeAPI 的消息"}
resp = requests.post(f"{BASE_URL}/api/v1/messages/send-text", headers=headers, json=payload)
print(resp.json())

# 获取联系人列表
resp = requests.get(f"{BASE_URL}/api/v1/contacts", headers=headers)
print(resp.json())

Node.js 示例

// npm install axios
const axios = require('axios')

const API_KEY = 'gw_live_your_api_key'
const BASE_URL = 'https://api.40hh.cn'

const api = axios.create({
  baseURL: BASE_URL,
  headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' }
})

// 发送文本消息
async function sendMessage() {
  const res = await api.post('/api/v1/messages/send-text', { toWxid: 'wxid_abc123', content: '你好' })
  console.log(res.data)
}
sendMessage()

cURL 示例

# 发送文本消息
curl -X POST "https://api.40hh.cn/api/v1/messages/send-text" \
  -H "Authorization: Bearer gw_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "toWxid": "wxid_abc123", "content": "你好" }'

# 获取联系人列表
curl -X GET "https://api.40hh.cn/api/v1/contacts" \
  -H "Authorization: Bearer gw_live_your_api_key"

# 注册新用户
curl -X POST "https://api.40hh.cn/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{ "username": "newuser", "password": "mypassword123" }'

错误码说明

WeAPI 使用统一的 JSON 响应格式，业务错误通过 code 字段标识：

错误码说明处理方式
0成功正常处理返回数据
1001参数错误检查请求参数是否正确
1002认证失败检查 Token 或 API Key 是否有效
1003权限不足当前账号没有操作权限
1004资源不存在请求的资源 ID 无效
1005请求过于频繁超出速率限制，请稍后重试
2001账号未登录先调用登录二维码接口完成微信登录
2002账号已离线微信账号已离线，需重新登录
2003消息发送失败检查目标 wxid 是否有效
3001套餐额度不足升级套餐或等待额度重置
3002套餐已过期续费后即可恢复使用
5001内部服务错误联系技术支持

HTTP 状态码：200 成功，400 参数错误，401 未认证，403 无权限，404 不存在，429 频率超限，500 服务端错误。

套餐与价格

WeAPI 提供四个档位的套餐，满足不同规模的使用需求：

功能项免费版基础版专业版企业版
价格免费¥99/月¥299/月¥999/月
年付优惠-¥990/年¥2,990/年¥9,990/年
每日请求次数100 次1,000 次5,000 次50,000 次
可绑定账号数1 个3 个10 个50 个
消息发送✓✓✓✓
消息接收✓✓✓✓
联系人/群组查询✓✓✓✓
Webhook 回调-✓✓✓
历史消息存储7 天30 天90 天365 天
API Key 数量2 个5 个20 个100 个
技术支持社区工单优先工单专属支持
推荐场景个人体验小团队中型项目企业级
付费方式： 支持支付宝、微信支付。年付享受 8.3 折优惠。

常见问题

WeAPI 是什么？▼

WeAPI 是一个微信消息 API 平台，提供标准 RESTful 接口，帮助开发者将微信消息收发能力集成到自己的业务系统中。

免费版有哪些限制？▼

免费版每日限额 100 次 API 调用，仅支持 1 个微信账号，消息历史保留 7 天，不支持 Webhook 回调。

如何获取 API Key？▼

注册并登录 WeAPI 控制台后，在"API Key 管理"页面点击"创建密钥"即可生成。

API Key 和 JWT Token 有什么区别？▼

JWT Token 通过登录获取，有效期较短（24 小时）。API Key 在控制台生成，可永不过期，推荐服务端场景使用。

如何绑定微信账号？▼

在控制台"账号管理"页面，点击"添加账号"获取登录二维码，使用微信扫码完成授权登录。

超出每日调用限制怎么办？▼

超出后 API 返回 429。可等待次日额度重置，或升级到更高套餐。

Webhook 支持哪些事件？▼

支持：message.receive、message.send、account.login、account.logout、account.status。回调地址需为 HTTPS。

如何取消订阅？▼

在控制台的"订阅管理"页面取消自动续费。取消后当前套餐可使用至到期日，到期后自动降级为免费版。

数据安全如何保障？▼

WeAPI 采用 HTTPS 加密传输，API Key 和 JWT Token 双重认证，消息数据加密存储。