API 使用指南

了解如何使用 Open API 进行外部系统集成和自动化发布

API 概述

微矩阵平台提供标准的 RESTful Open API，允许您通过外部系统（如 CI/CD 流水线、自动化脚本、第三方工具）与平台进行集成。所有 API 请求需要通过 Bearer Token 进行认证。

API 基本信息

基础路径：/api/open/*

数据格式：JSON（请求和响应）

认证方式：Bearer Token（HTTP Header）

响应格式：{ success: boolean, data?: any, message?: string }

管理 Token 交互式文档

认证方式

所有 Open API 请求都需要在 HTTP Header 中携带 Bearer Token：

Authorization: Bearer mp_your_token_here

如果 Token 无效或已过期，API 将返回 401 状态码：

{
  "success": false,
  "message": "无效的 API Token",
  "code": "INVALID_TOKEN"
}

接口列表

以下是 Open API 提供的所有接口：

方法	路径	说明
`GET`	/api/open/agent/context	获取 Agent 接入上下文、权限 scope、能力边界和发布策略
`GET`	/api/open/accounts	获取已授权的公众号列表
`GET`	/api/open/account-style	获取账号样式配置（可选 ?appid=xxx）
`GET`	/api/open/publisher/summary	获取流量主累计概览，支持多公众号合计
`GET`	/api/open/publisher/settlement-summary	获取指定时间段收益汇总，支持按公众号或总计
`GET`	/api/open/publisher/settlement-daily	获取指定时间段每日收益趋势，支持按公众号或总计
`POST`	/api/open/draft	从 Markdown 创建微信草稿并同步后台文章

提示：访问「API 文档」页面可以查看完整的交互式文档，包括请求参数、响应示例和在线调试功能。

POST /api/open/draft 请求体

{
  "article_type": "news 或 newspic",
  "title": "文章标题（必填）",
  "content": "Markdown 内容（必填）",
  "appid": "目标公众号 appid（必填）",
  "author": "作者名",
  "summary": "摘要（最多 120 字）",
  "coverImageUrl": "封面图 URL",
  "imageUrls": ["仅 newspic 使用，可选"],
  "imageMediaIds": ["仅 newspic 使用，可选"],
  "coverInfo": { "...仅 newspic 使用..." },
  "productInfo": { "...仅 newspic 使用..." },
  "sourceUrl": "原文链接",
  "showCoverPic": 1,
  "openComment": 1,
  "fansOnlyComment": 0,
  "themeConfig": { "...样式配置..." }
}

默认 article_type 为news。当传newspic时，至少提供一项图片来源：imageUrls、imageMediaIds或 coverImageUrl。

接口成功后会同时返回微信草稿 mediaId 和系统本地文章articleId。返回的文章会直接出现在后台「文章管理」中，后续可继续正式发布。

流量主收益查询示例

# 1) 查累计概览
GET /api/open/publisher/summary?appids=wx123,wx456

# 2) 查区间汇总
GET /api/open/publisher/settlement-summary?appids=wx123,wx456&startDate=2026-01-01&endDate=2026-04-14&groupBy=appid

# 3) 查区间总趋势
GET /api/open/publisher/settlement-daily?appids=wx123,wx456&startDate=2026-01-01&endDate=2026-04-14&groupBy=total

Agent 与 CLI

如果你是给 Codex、Claude、Cursor、CI 脚本或自定义 Agent 接入微矩阵，推荐优先使用wematrix-cli。CLI 已经封装了 Token 读取、JSON 输出、错误结构、MCP 配置和草稿创建命令，适合 Agent 稳定调用。

npm install -g wematrix-cli

export WEMATRIX_BASE_URL="https://mp.lingxiaoyao.cn"
export WEMATRIX_TOKEN="mp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

wematrix context
wematrix accounts
wematrix styles --appid wx123
wematrix draft create post.md --title "每日简报" --appid wx123

查看 CLI 与 MCP 指南 npm 包

Agent 接入时不要把真实 Token 放进 prompt、共享 MCP 配置或 Git 仓库。建议使用环境变量、Secret 管理器或平台内置的密钥管理能力。

错误码说明

API 返回的常见错误码及其含义：

HTTP 状态码	错误码	说明
400	`MISSING_FIELDS`	缺少必填参数
401	`MISSING_TOKEN`	请求头未携带 Token
401	`INVALID_TOKEN`	Token 无效或已过期
404	`ACCOUNT_NOT_FOUND`	指定的公众号不存在或未授权
500	`WECHAT_API_ERROR`	微信 API 调用失败
500	`INTERNAL_ERROR`	服务器内部错误

最佳实践

使用 Open API 时的建议和注意事项：

Token 安全

不要将 Token 硬编码在代码中，使用环境变量管理
不要将 Token 提交到 Git 仓库
定期轮换 Token，建议设置合理的过期时间
为不同用途创建独立的 Token，便于权限管理

错误处理

始终检查响应中的 success 字段
根据 code 字段判断具体错误类型
微信 API 可能因为 Token 过期失败，平台会自动刷新后重试
批量操作时建议在请求间添加适当延迟（1-2 秒）

内容格式

文章内容使用标准 Markdown 语法，平台会自动转换为微信图文格式
封面图建议使用 HTTPS 链接，尺寸推荐 900x383 像素
摘要（summary）最多 120 个字符，超出会被截断

上一篇公众号管理指南

下一篇CLI 与 MCP