Home.ISV · 多平台自动化运营接口

统一 ISV 平台对外接口 · 微信 / 抖音 / 支付宝 等平台自动化运营对接 · 在线文档

一、概述

Home.ISV 作为各平台的第三方/代授权载体，将公众号/生活号等自动化运营能力以标准 REST API 暴露，供内部团队项目（如 AI.Uniserver）直接调用，无需各项目自行实现平台加解密与 token 管理。

基础地址 https://isv.shhome.net

二、鉴权

在 appsettings.json 配置 ApiGateway:ApiKey 非空后，所有 /api/... 接口必须携带请求头：

X-Api-Key: <配置的密钥>

未携带或错误返回 401。未配置 ApiKey（默认）则接口开放，请部署在可信网络/网关之后。

三、统一响应结构

{
  "success": true,        // 仅表示 HTTP 传输层成功（2xx）
  "httpCode": 200,        // HTTP 状态码
  "data": { },            // 下游平台原始 JSON 响应（透传）
  "error": null           // 平台层错误（账号未授权 / token 获取失败等）
}
⚠️ success:true 仅代表请求成功到达平台并收到响应。平台业务错误（如 errcode != 0）体现在 data.errcode / data.errmsg 中，不会使 success 变 false。调用方务必判断 data.errcode === 0。

四、通用跨平台代理（对讲机接口）推荐

适用于任意平台、任意 operation。调用方只需指定 platform、目标 appId、下游 path 与 body，由平台适配器负责拼接 token / 签名 / 加密。

方法路径说明
POST/api/{platform}/call/{appId}?path=下游接口路径透传 body 到下游平台 POST 接口
GET/api/{platform}/call/{appId}?path=下游接口路径下游为 GET 的接口（body 忽略）
GET/api/{platform}/authorizers某平台已授权账号列表
GET/api/{platform}/account/{appId}账号基本信息

platform 取值：weixin | douyin | alipay（新平台在 ISVPlatformFactory 注册后即自动生效）。

示例：给微信公众平台创建菜单（通用代理） 
# platform=weixin，path 为微信官方接口路径（不含 host 与 token）
curl -X POST "https://isv.shhome.net/api/weixin/call/wx1234567890abcdef?path=cgi-bin/menu/create" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_KEY" \
  -d '{"button":[{"type":"view","name":"官网","url":"https://www.shhome.net"}]}'
示例：抖音获取授权账号信息（同一套代理，仅换 platform） 
curl "https://isv.shhome.net/api/douyin/call/aw_appid_example?path=some/douyin/api/path" \
  -H "X-Api-Key: YOUR_KEY"

💡 扩展新平台（如支付宝）：只需在解决方案中新增对应 IISVPlatform 实现并注册到 ISVPlatformFactory，上述所有通用接口即自动支持 platform=alipay，无需新增任何端点。

五、微信便捷接口（公众号专用）

针对微信公众平台的高频操作提供的语义化便捷端点，等价于对应通用代理的封装。

方法路径说明
GET/api/weixin/menu/{appId}获取自定义菜单
POST/api/weixin/menu/{appId}创建自定义菜单（body 透传微信格式）
DELETE/api/weixin/menu/{appId}删除自定义菜单
GET/api/weixin/articles/{appId}?offset=0&count=20图文/文章素材列表
POST/api/weixin/articles/{appId}新增图文素材（草稿箱）
GET/api/weixin/material/{appId}?mediaId=xxx素材详情
POST/api/weixin/message/custom/{appId}发送客服消息
POST/api/weixin/message/template/{appId}发送模板消息
POST/api/weixin/mass/{appId}群发消息
示例：获取图文素材列表（公众号文章） 
curl "https://isv.shhome.net/api/weixin/articles/wx1234567890abcdef?offset=0&count=10" \
  -H "X-Api-Key: YOUR_KEY"

六、错误码速查

HTTPsuccess含义处理
200true到达平台，业务结果看 data.errcode判断 data.errcode===0
400false参数错误（如 path 缺省）检查请求参数
401false缺少/错误 X-Api-Key检查密钥
404false未找到账号 / 不支持的平台确认 appId 已授权、platform 已注册
500false平台异常（token 获取失败等）查看 error，联系 ISV 维护方

下游平台常见业务错误码见 data.errcode：40001 token 过期（平台自动刷新，重试）、40013 AppId 非法、48001 未授权该 API、45009 接口超限。

七、在线测试（通用代理）

八、接入步骤（供调用方团队）

  1. 确认目标账号已完成授权流程（由 Home.ISV 授权管理页或 /api/admin/preauth-url 引导）。
  2. 调用 GET /api/{platform}/authorizers 确认 appId 在列表且 status=1。
  3. 使用通用代理 /api/{platform}/call/{appId}?path=... 或微信便捷端点，body 透传平台官方 JSON。
  4. 解析 data（即平台原始返回）对接业务逻辑。
  5. 启用鉴权后，每次请求携带 X-Api-Key。

微信官方文档：https://developers.weixin.qq.com/doc/offiaccount/ · 接口实现：Home.ISV.Web/Controllers/IsvApiController.cs / WeiXinApiController.cs

九、前端弹窗授权集成（GEO 等）

通过弹窗完成微信授权并自动回传授权账号基础信息给父页面，无需轮询。

  1. 父页面用 window.open('https://isv.shhome.net/weixin/auth/windows') 打开授权弹窗（该页自动跳转微信授权）。
  2. 用户在弹窗内扫码授权，微信回调 /weixin/auth?popup=1，服务端返回基础信息并通过 postMessage 回传父页面。
  3. 父页面监听 message 事件即可拿到 authorizer（含 appId / nickName / accountType / status / enterpriseId），弹窗随后自动关闭。
前端示例代码 
// 父页面（如 GEO）
const win = window.open('https://isv.shhome.net/weixin/auth/windows', 'weixinAuth', 'width=800,height=640');

window.addEventListener('message', (e) => {
  const msg = e.data;
  if (msg && msg.type === 'isv-weixin-auth' && msg.success) {
    const a = msg.authorizer; // { appId, nickName, accountType, status, enterpriseId }
    console.log('授权成功：', a.nickName, a.appId);
    // TODO: 将基础信息提交/展示
  }
});

回传数据结构：{ type:'isv-weixin-auth', success:true, authorizer:{ appId, nickName, accountType, status, enterpriseId } }

绑定企业：授权 URL 携带 ?enterpriseId=xxx（如 /weixin/auth/windows?enterpriseId=123），回调时自动关联到对应企业。