WechatAuthtimeController（企业微信集成管理）

管理企业域的企业微信集成配置：微信代理类型/CorpID/Secret/外网 host、扫码登录代理应用、企业微信应用列表/详情/菜单、企业微信标签及成员、企业微信组织架构同步与查询、临时素材上传/下载/列表/删除。

• 类级基址：${myapps.context-path.manager:}/api/authtime（完整路径：{manager-context}/api/authtime<相对路径>）
• Tag：微信配置模块
• 控制器源码：obpm-manager/src/main/java/cn/myapps/manager/authtime/controller/wechat/WechatAuthtimeController.java
• 公共说明：
• 类继承 BaseAuthTimeController，通过其 success(errmsg, data) / error(errcode, errmsg, errors) 返回统一 Resource（字段 errcode/errmsg/data/errors，结构见 ../index.md「统一响应结构」）。
• 几乎所有端点在 try/catch 内捕获 Exception 并 e.printStackTrace() 后返回 errcode=500、errmsg=e.getMessage()、data=null（HTTP 状态码仍为 200）。
• 鉴权说明见 index.md「鉴权说明」。
• 路径变量 domainid 为企业域 id；applicationid 为软件 id；agentid 为企业微信应用 id；tagid 为企业微信标签 id；mediaid 为企业微信临时素材 id。

---

1. 微信配置

查询指定企业域的企业微信集成配置（代理类型、CorpID、通讯录 Secret、外网 serverHost、扫码登录代理应用的 AgentId/Secret/CallbackUrl），并列出该域下所有软件的 weixinAgentId 与 weixinSecret。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/domain/{domainid}/wechat（完整：{manager-context}/api/authtime/domain/{domainid}/wechat）
• 鉴权：是（需管理员 accessToken，详见 index.md「鉴权说明」）
• Tag：微信配置模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id

请求示例

GET /api/authtime/domain/__P1UD2yVWpnFpUedONr/domain/wechat HTTP/1.1

响应

结构：统一 Resource（见 ../index.md「统一响应结构」）。 data：JSONObject，字段： - weixinProxyType (string)：微信代理类型 - weixinCorpID (string)：企业微信 CorpID - weixinCorpSecret (string)：通讯录同步 Secret - serverHost (string)：外网访问 host - weixinQrCodeAgentId (string)：扫码登录代理应用 AgentId - weixinQrCodeSecret (string)：扫码登录代理应用 Secret - weixinQrCodeCallbackUrl (string)：扫码登录回调 URL - apps (array\<JSONObject>)：软件列表，元素字段 id/name/description/weixinAgentId/weixinSecret

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": {
    "weixinProxyType": "ENTERPRISE_WECHAT",
    "weixinCorpID": "ww1234567890abcdef",
    "weixinCorpSecret": "***",
    "serverHost": "https://example.com",
    "weixinQrCodeAgentId": "1000002",
    "weixinQrCodeSecret": "***",
    "weixinQrCodeCallbackUrl": "https://example.com/manager/api/qrcode/callback",
    "apps": [
      { "id": "__APPID1", "name": "协同办公", "description": "", "weixinAgentId": "1000003", "weixinSecret": "***" }
    ]
  },
  "errors": null
}

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

2. 保存微信配置

更新企业域的企业微信集成配置（代理类型、CorpID、通讯录 Secret、外网 host、扫码登录代理应用 AgentId/Secret/CallbackUrl）。仅在字段非空且与原值不同时更新；任一字段变更会触发 doCreateOrUpdate 与微信 Secret 缓存清理。

• 接口类型：REST 资源
• 请求方式：PUT
• 请求路径：/domain/{domainid}/wechat（完整：{manager-context}/api/authtime/domain/{domainid}/wechat）
• 鉴权：是
• Tag：微信配置模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id

请求体

JSON 对象（application/json）：

字段	类型	必填	说明
weixinProxyType	string	否	微信代理类型；空或与原值相同则不更新
weixinCorpID	string	否	企业微信 CorpID；空或与原值相同则不更新
weixinCorpSecret	string	否	通讯录同步 Secret；空或与原值相同则不更新
serverHost	string	否	外网访问 host；空或与原值相同则不更新
weixinQrCodeAgentId	string	否	扫码登录代理应用 AgentId；与原值不同即更新（含空值）
weixinQrCodeSecret	string	否	扫码登录代理应用 Secret；与原值不同即更新（含空值）
weixinQrCodeCallbackUrl	string	否	扫码登录回调 URL；与原值不同即更新（含空值）

注：源码中扫码登录 Secret 的比较存在历史写法（!StringUtils.equals(weixinCorpSecret, domain.getWeixinQrCodeSecret())），实际取值为请求体中的 weixinQrCodeSecret，与比较变量名不一致——此处按语义描述。

请求示例

PUT /api/authtime/domain/__P1UD2yVWpnFpUedONr/domain/wechat HTTP/1.1
Content-Type: application/json

{
  "weixinProxyType": "ENTERPRISE_WECHAT",
  "weixinCorpID": "ww1234567890abcdef",
  "weixinCorpSecret": "new-secret",
  "serverHost": "https://example.com",
  "weixinQrCodeAgentId": "1000002",
  "weixinQrCodeSecret": "new-qrcode-secret",
  "weixinQrCodeCallbackUrl": "https://example.com/manager/api/qrcode/callback"
}

响应

结构：统一 Resource。 data：字符串 "保存成功"。

成功示例：

{ "errcode": 0, "errmsg": "ok", "data": "保存成功", "errors": null }

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

3. 外网访问地址验证

校验所给企业微信 CorpID + 通讯录 Secret 能否换取 accessToken，并验证 serverHost 外网可访问其移动端静态首页。两步均通过才返回成功。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/domain/{domainid}/wechat/corp/{corpid}/corpsecret/{corpsecret}（完整：{manager-context}/api/authtime/domain/{domainid}/wechat/corp/{corpid}/corpsecret/{corpsecret}）
• 鉴权：是
• Tag：微信配置模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
corpid	path	string	是	企业微信 CorpID
corpsecret	path	string	是	通讯录同步 Secret
serverHost	query	string	是	待验证的外网 host；内部将其中的 /obpm 替换为 /，再拼 /static/mobile/index.html 验证

请求示例

GET /api/authtime/domain/__P1UD2yVWpnFpUedONr/domain/wechat/corp/ww1234567890abcdef/corpsecret/xxx-secret?serverHost=https://example.com/obpm HTTP/1.1

响应

结构：统一 Resource。 data：字符串 "验证成功" / 验证失败时 data=null。

条件	errcode	errmsg	data
取 accessToken 返回 null	1	验证失败	null
serverHost 静态页 HTTP 状态非 200	500	serverHost (<host>) 无法访问	null
验证成功	0	ok	验证成功
抛异常	500	<异常信息>	null

成功示例：

{ "errcode": 0, "errmsg": "ok", "data": "验证成功", "errors": null }

失败示例：

{ "errcode": 500, "errmsg": "serverHost (https://example.com) 无法访问", "data": null, "errors": null }

---

4. 同步微信企业号组织架构到企业域

调用 DomainProcess.synchFromWeixin 从企业微信拉取组织架构并同步到本地企业域。

• 接口类型：REST 资源
• 请求方式：PUT
• 请求路径：/domain/{domainid}/synchfromwechat（完整：{manager-context}/api/authtime/domain/{domainid}/synchfromwechat）
• 鉴权：是
• Tag：微信配置模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id

请求示例

PUT /api/authtime/domain/__P1UD2yVWpnFpUedONr/domain/synchfromwechat HTTP/1.1

响应

结构：统一 Resource。 data：net.sf.json.JSONObject，企业微信同步接口返回的结果（含 errcode/errmsg 等字段，由企业微信 API 决定）。

注：本端点未捕获异常，抛出时由 Spring 默认异常处理（HTTP 500，无统一 Resource 体）。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": { "errcode": 0, "errmsg": "ok", "invaliduser": [], "invalidparty": [] },
  "errors": null
}

---

5. 同步企业域组织架构到微信企业号

调用 DomainProcess.synch2Weixin 把本地企业域组织架构推送到企业微信。

• 接口类型：REST 资源
• 请求方式：PUT
• 请求路径：/domain/{domainid}/synch2wechat（完整：{manager-context}/api/authtime/domain/{domainid}/synch2wechat）
• 鉴权：是
• Tag：微信配置模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id

请求示例

PUT /api/authtime/domain/__P1UD2yVWpnFpUedONr/domain/synch2wechat HTTP/1.1

响应

结构：统一 Resource。 data：net.sf.json.JSONObject，企业微信同步接口返回的结果。

注：本端点未捕获异常，抛出时由 Spring 默认异常处理（HTTP 500，无统一 Resource 体）。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": { "errcode": 0, "errmsg": "ok" },
  "errors": null
}

---

6. 生成跳转链接

按企业域的企业微信 CorpID、应用 AgentId 与外网 host，生成 OAuth2 跳转链接（用于「进入系统」入口）。applicationid 取值为 KMAPPID 时生成 KMS 移动端入口；否则按软件 id 拼接 runtime 移动端入口。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/domain/{domainid}/application/{applicationid}/getwechaturl（完整：{manager-context}/api/authtime/domain/{domainid}/application/{applicationid}/getwechaturl）
• 鉴权：是
• Tag：微信配置模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
applicationid	path	string	是	软件 id；特殊值 KMAPPID 走 KMS 入口分支

请求示例

GET /api/authtime/domain/__P1UD2yVWpnFpUedONr/application/__APPID1/getwechaturl HTTP/1.1

响应

结构：统一 Resource。 data：Map<String, String>，键固定为「进入系统」，值为 OAuth2 跳转 URL。

条件	errcode	errmsg	data
AgentId 为空	500	WeixinAgentId为空	null
CorpID 为空	500	WeixinCorpID为空	null
软件 id 非 KMAPPID 且软件不存在	1	查不对应的软件	null
成功	0	ok	{ "进入系统": "<OAuth2 URL>" }
抛异常	500	<异常信息>	null

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": {
    "进入系统": "https://open.weixin.qq.com/connect/oauth2/authorize?appid=ww...&redirect_uri=...&response_type=code&scope=snsapi_base&agentid=1000003&state=__P1UD2yVWpnFpUedONr#wechat_redirect"
  },
  "errors": null
}

---

7. 保存微信应用 AgentId

更新指定企业域下指定软件的企业微信应用 AgentId。

• 接口类型：REST 资源
• 请求方式：PUT
• 请求路径：/domain/{domainid}/application/{applicationid}/updateWeixinAgentId（完整：{manager-context}/api/authtime/domain/{domainid}/application/{applicationid}/updateWeixinAgentId）
• 鉴权：是
• Tag：微信配置模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
applicationid	path	string	是	软件 id
id	query	string	是	企业微信应用 AgentId

请求示例

PUT /api/authtime/domain/__P1UD2yVWpnFpUedONr/application/__APPID1/updateWeixinAgentId?id=1000003 HTTP/1.1

响应

结构：统一 Resource。 data：字符串 "保存成功"。

成功示例：

{ "errcode": 0, "errmsg": "ok", "data": "保存成功", "errors": null }

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

8. 保存微信应用 secret

更新指定企业域下指定软件的企业微信应用 Secret。

• 接口类型：REST 资源
• 请求方式：PUT
• 请求路径：/domain/{domainid}/application/{applicationid}/updateWeixinSecret（完整：{manager-context}/api/authtime/domain/{domainid}/application/{applicationid}/updateWeixinSecret）
• 鉴权：是
• Tag：微信配置模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
applicationid	path	string	是	软件 id
secret	query	string	是	企业微信应用 Secret

请求示例

PUT /api/authtime/domain/__P1UD2yVWpnFpUedONr/application/__APPID1/updateWeixinSecret?secret=xxx HTTP/1.1

响应

结构：统一 Resource。 data：字符串 "保存成功"。

成功示例：

{ "errcode": 0, "errmsg": "ok", "data": "保存成功", "errors": null }

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

9. 获取企业微信应用列表

调用企业微信 API（QyApiService.getAgents）拉取当前企业可访问的应用列表。AccessToken 由企业域通讯录 Secret 经 WeixinSecretCache 缓存换取。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/domain/{domainid}/wechat/agents（完整：{manager-context}/api/authtime/domain/{domainid}/wechat/agents）
• 鉴权：是
• Tag：微信配置模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id（用于查通讯录 Secret）

请求示例

GET /api/authtime/domain/__P1UD2yVWpnFpUedONr/domain/wechat/agents HTTP/1.1

响应

结构：统一 Resource。 data：List<Agent>，元素为 cn.myapps.common.support.wecom.model.Agent（含 agentid/name/squareLogoUrl 等企业微信标准字段）。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": [
    { "agentid": 1000003, "name": "协同办公", "squareLogoUrl": "https://..." }
  ],
  "errors": null
}

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

10. 获取企业微信应用详情

按应用 id 调用企业微信 API（QyApiService.getAgent）拉取单个应用详情。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/domain/{domainid}/wechat/agents/{agentid}（完整：{manager-context}/api/authtime/domain/{domainid}/wechat/agents/{agentid}）
• 鉴权：是
• Tag：微信配置模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
agentid	path	string	是	企业微信应用 id

请求示例

GET /api/authtime/domain/__P1UD2yVWpnFpUedONr/domain/wechat/agents/1000003 HTTP/1.1

响应

结构：统一 Resource。 data：Agent（企业微信应用详情对象）。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": { "agentid": 1000003, "name": "协同办公", "description": "..." },
  "errors": null
}

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

11. 获取企业微信菜单列表

按应用 id 调用企业微信 API（QyApiService.getMenus）拉取该应用的自定义菜单。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/domain/{domainid}/wechat/agents/{agentid}/menus（完整：{manager-context}/api/authtime/domain/{domainid}/wechat/agents/{agentid}/menus）
• 鉴权：是
• Tag：微信配置模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
agentid	path	string	是	企业微信应用 id

请求示例

GET /api/authtime/domain/__P1UD2yVWpnFpUedONr/domain/wechat/agents/1000003/menus HTTP/1.1

响应

结构：统一 Resource。 data：List<Menu>，元素为 cn.myapps.common.support.wecom.model.Menu。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": [ { "type": "view", "name": "首页", "url": "https://..." } ],
  "errors": null
}

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

12. 保存企业微信菜单

按应用 id 调用企业微信 API（QyApiService.saveMenu）创建/更新该应用的自定义菜单。请求体为企业微信菜单 JSON 文本。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/domain/{domainid}/wechat/agents/{agentid}/menus（完整：{manager-context}/api/authtime/domain/{domainid}/wechat/agents/{agentid}/menus）
• 鉴权：是
• Tag：微信配置模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
agentid	path	string	是	企业微信应用 id
content	body	string	是	企业微信菜单 JSON 文本

请求体

原生字符串（Content-Type: application/json 或 text/plain，控制器按 @RequestBody String 接收），示例：

{
  "button": [
    { "type": "view", "name": "首页", "url": "https://example.com" }
  ]
}

请求示例

POST /api/authtime/domain/__P1UD2yVWpnFpUedONr/domain/wechat/agents/1000003/menus HTTP/1.1
Content-Type: application/json

{ "button": [ { "type": "view", "name": "首页", "url": "https://example.com" } ] }

响应

结构：统一 Resource。 data：null（成功时仅返回 errmsg=ok）。

成功示例：

{ "errcode": 0, "errmsg": "ok", "data": null, "errors": null }

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

13. 获取企业微信标签列表

调用企业微信 API（QyApiService.getTags）拉取企业标签列表。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/domain/{domainid}/wechat/tags（完整：{manager-context}/api/authtime/domain/{domainid}/wechat/tags）
• 鉴权：是
• Tag：微信配置模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id

请求示例

GET /api/authtime/domain/__P1UD2yVWpnFpUedONr/domain/wechat/tags HTTP/1.1

响应

结构：统一 Resource。 data：List<cn.myapps.common.support.wecom.model.Tag>。

注：源码中本端点的 Java 方法名误写为 deleteTag，但 @Operation(summary) 为「获取企业微信标签列表」、HTTP 方法为 GET、实际调用的是 QyApiService.getTags，故按语义命名。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": [ { "tagid": 1, "tagname": "总部" } ],
  "errors": null
}

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

14. 创建企业微信标签

调用企业微信 API（QyApiService.createTag）创建标签。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/domain/{domainid}/wechat/tags（完整：{manager-context}/api/authtime/domain/{domainid}/wechat/tags）
• 鉴权：是
• Tag：微信配置模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
content	body	string	是	企业微信创建标签 JSON 文本（如 {"tagname":"总部"}）

请求示例

POST /api/authtime/domain/__P1UD2yVWpnFpUedONr/domain/wechat/tags HTTP/1.1
Content-Type: application/json

{ "tagname": "总部" }

响应

结构：统一 Resource。 data：null。

成功示例：

{ "errcode": 0, "errmsg": "ok", "data": null, "errors": null }

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

15. 更新企业微信标签

将请求体反序列化为 Tag 后调用企业微信 API（QyApiService.updateTag）更新标签。

• 接口类型：REST 资源
• 请求方式：PUT
• 请求路径：/domain/{domainid}/wechat/tags（完整：{manager-context}/api/authtime/domain/{domainid}/wechat/tags）
• 鉴权：是
• Tag：微信配置模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
content	body	string	是	企业微信标签 JSON 文本（如 {"tagid":1,"tagname":"总部"}）

请求示例

PUT /api/authtime/domain/__P1UD2yVWpnFpUedONr/domain/wechat/tags HTTP/1.1
Content-Type: application/json

{ "tagid": 1, "tagname": "集团总部" }

响应

结构：统一 Resource。 data：null。

成功示例：

{ "errcode": 0, "errmsg": "ok", "data": null, "errors": null }

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

16. 删除企业微信标签

按标签 id 调用企业微信 API（QyApiService.deleteTag）删除标签。

• 接口类型：REST 资源
• 请求方式：DELETE
• 请求路径：/domain/{domainid}/wechat/tags/{tagid}（完整：{manager-context}/api/authtime/domain/{domainid}/wechat/tags/{tagid}）
• 鉴权：是
• Tag：微信配置模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
tagid	path	string	是	企业微信标签 id

请求示例

DELETE /api/authtime/domain/__P1UD2yVWpnFpUedONr/domain/wechat/tags/1 HTTP/1.1

响应

结构：统一 Resource。 data：null。

成功示例：

{ "errcode": 0, "errmsg": "ok", "data": null, "errors": null }

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

17. 获取企业微信标签成员

按标签 id 调用企业微信 API（QyApiService.getTabMembers）拉取标签下的成员列表。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/domain/{domainid}/wechat/tags/{tagid}/members（完整：{manager-context}/api/authtime/domain/{domainid}/wechat/tags/{tagid}/members）
• 鉴权：是
• Tag：微信配置模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
tagid	path	string	是	企业微信标签 id

请求示例

GET /api/authtime/domain/__P1UD2yVWpnFpUedONr/domain/wechat/tags/1/members HTTP/1.1

响应

结构：统一 Resource。 data：List<Object>（企业微信标签成员对象，含 userid/name/department 等）。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": [ { "userid": "zhangsan", "name": "张三" } ],
  "errors": null
}

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

18. 添加企业微信标签成员

将请求体原样透传给企业微信 API（QyApiService.addTagMembers）批量添加成员到指定标签。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/domain/{domainid}/wechat/tags/members（完整：{manager-context}/api/authtime/domain/{domainid}/wechat/tags/members）
• 鉴权：是
• Tag：微信配置模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
content	body	string	是	企业微信添加标签成员 JSON 文本（如 {"tagid":1,"userlist":["zhangsan"]}）

请求示例

POST /api/authtime/domain/__P1UD2yVWpnFpUedONr/domain/wechat/tags/members HTTP/1.1
Content-Type: application/json

{ "tagid": 1, "userlist": [ "zhangsan", "lisi" ] }

响应

结构：统一 Resource。 data：null。

成功示例：

{ "errcode": 0, "errmsg": "ok", "data": null, "errors": null }

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

19. 移除企业微信标签成员

将请求体原样透传给企业微信 API（QyApiService.removeTagMembers）从指定标签移除成员。

• 接口类型：REST 资源
• 请求方式：DELETE
• 请求路径：/domain/{domainid}/wechat/tags/members（完整：{manager-context}/api/authtime/domain/{domainid}/wechat/tags/members）
• 鉴权：是
• Tag：微信配置模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
content	body	string	是	企业微信移除标签成员 JSON 文本

请求示例

DELETE /api/authtime/domain/__P1UD2yVWpnFpUedONr/domain/wechat/tags/members HTTP/1.1
Content-Type: application/json

{ "tagid": 1, "userlist": [ "zhangsan" ] }

响应

结构：统一 Resource。 data：null。

成功示例：

{ "errcode": 0, "errmsg": "ok", "data": null, "errors": null }

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

20. 获取企业微信组织（部门和用户）

按 parentid 拉取该父级部门下的子部门列表与用户列表（parentid=0 时只返回根部门，不含用户）。响应里每个部门会标注 hasChild（是否有子部门）。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/domain/{domainid}/wechat/organizations（完整：{manager-context}/api/authtime/domain/{domainid}/wechat/organizations）
• 鉴权：是
• Tag：微信配置模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
parentid	query	string	否	父级部门 id；默认 0（根）。当不为 0 时同时返回该部门下的用户

请求示例

GET /api/authtime/domain/__P1UD2yVWpnFpUedONr/domain/wechat/organizations?parentid=2 HTTP/1.1

响应

结构：统一 Resource。 data：List<Object>，元素为 User 或 Department（cn.myapps.common.support.wecom.model）。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": [
    { "userid": "zhangsan", "name": "张三" },
    { "id": 3, "name": "研发部", "parentid": 2, "hasChild": false }
  ],
  "errors": null
}

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

21. 获取企业微信部门列表

按 parentid 拉取子部门列表（不含用户），每个部门标注 hasChild。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/domain/{domainid}/wechat/departments（完整：{manager-context}/api/authtime/domain/{domainid}/wechat/departments）
• 鉴权：是
• Tag：微信配置模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
parentid	query	string	否	父级部门 id；默认 0（根）

请求示例

GET /api/authtime/domain/__P1UD2yVWpnFpUedONr/domain/wechat/departments?parentid=0 HTTP/1.1

响应

结构：统一 Resource。 data：List<Department>。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": [
    { "id": 2, "name": "总部", "parentid": 0, "hasChild": true }
  ],
  "errors": null
}

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

22. 获取企业微信用户列表

按部门 id 调用企业微信 API（QyApiService.getUsersByDepartment）拉取该部门下的用户列表。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/domain/{domainid}/wechat/departments/{deptId}/users（完整：{manager-context}/api/authtime/domain/{domainid}/wechat/departments/{deptId}/users）
• 鉴权：是
• Tag：微信配置模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
deptId	path	string	是	部门 id（路径变量，必须提供）

请求示例

GET /api/authtime/domain/__P1UD2yVWpnFpUedONr/domain/wechat/departments/2/users HTTP/1.1

响应

结构：统一 Resource。 data：List<User>。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": [ { "userid": "zhangsan", "name": "张三", "department": [ 2 ] } ],
  "errors": null
}

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

23. 上传企业微信文件

接收一个或多个 multipart/form-data 文件，逐个写临时文件后调用企业微信 API（QyApiService.uploadTempMedia）上传为临时素材，并落库 MediaVO。返回上传后的素材元信息列表。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/domain/{domainid}/wechat/medias/upload（完整：{manager-context}/api/authtime/domain/{domainid}/wechat/medias/upload）
• 鉴权：是
• Tag：微信配置模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
type	query	string	是	企业微信素材类型（如 image/voice/video/file）
file	body (form)	file[]	是	一个或多个文件（字段名固定为 file，MultipartFile[]）

请求体

multipart/form-data：

字段	类型	说明
file	binary (可重复)	待上传的文件
(query) type	string	素材类型

请求示例

POST /api/authtime/domain/__P1UD2yVWpnFpUedONr/domain/wechat/medias/upload?type=image HTTP/1.1
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary

------WebKitFormBoundary
Content-Disposition: form-data; name="file"; filename="logo.png"
Content-Type: image/png

<二进制内容>
------WebKitFormBoundary--

响应

结构：统一 Resource。 data：List<MediaVO>，元素含 id（本地 Sequence 生成）、name、size、domainid 及企业微信返回的 media_id/created_at 等。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": [
    {
      "id": "__MEDIA001",
      "name": "logo.png",
      "size": 12345,
      "domainid": "__P1UD2yVWpnFpUedONr",
      "mediaId": "3GQZt7vHb5aFn1E8HpPp_1uVbRTXsdweasfXxSjQjJK9-e7Hj6kLqZ-9xC-CQAYH",
      "createdAt": "2026-08-05 10:00:00"
    }
  ],
  "errors": null
}

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

24. 下载临时素材

按 mediaid 调用企业微信 API（QyApiService.downloadFile）下载临时素材，并通过响应输出流返回二进制内容。

• 接口类型：REST 资源（二进制响应）
• 请求方式：GET
• 请求路径：/domain/{domainid}/wechat/medias/{mediaid}/download（完整：{manager-context}/api/authtime/domain/{domainid}/wechat/medias/{mediaid}/download）
• 鉴权：是
• Tag：微信配置模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
mediaid	path	string	是	企业微信媒体文件 id
fileName	query	string	是	下载保存的文件名（写入 Content-Disposition，做 UTF-8 URL 编码）

请求示例

GET /api/authtime/domain/__P1UD2yVWpnFpUedONr/domain/wechat/medias/3GQZt7vHb5aFn1E8HpPp_1uVbRTX/download?fileName=logo.png HTTP/1.1

响应

结构：二进制流（非 Resource）。

项目	值
HTTP 状态码	200（成功时）
Content-Type	由 Servlet 容器默认决定（通常 application/octet-stream）
Content-Disposition	attachment;fileName=<URL 编码后的 fileName>
Body	企业微信 API 返回的原始文件字节流，直接写入响应输出流

注：本端点方法返回 void，不返回统一 Resource；异常被 try/catch 吞掉（仅 printStackTrace），下载失败时响应体可能为空或残缺。

---

25. 获取临时素材列表

按企业域 id（可选类型）查询本地已落库的临时素材列表（MediaProcess.list）。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/domain/{domainid}/wechat/medias（完整：{manager-context}/api/authtime/domain/{domainid}/wechat/medias）
• 鉴权：是
• Tag：微信配置模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
type	query	string	否	素材类型过滤

请求示例

GET /api/authtime/domain/__P1UD2yVWpnFpUedONr/domain/wechat/medias?type=image HTTP/1.1

响应

结构：统一 Resource。 data：Collection<MediaVO>。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": [
    {
      "id": "__MEDIA001",
      "name": "logo.png",
      "size": 12345,
      "domainid": "__P1UD2yVWpnFpUedONr",
      "mediaId": "3GQZt7vHb5aFn1E8HpPp_1uVbRTXsdweasfXxSjQjJK9-e7Hj6kLqZ-9xC-CQAYH"
    }
  ],
  "errors": null
}

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

26. 删除临时素材

按本地素材 id 数组批量删除临时素材记录（MediaProcess.delete）。

• 接口类型：REST 资源
• 请求方式：DELETE
• 请求路径：/domain/{domainid}/wechat/medias（完整：{manager-context}/api/authtime/domain/{domainid}/wechat/medias）
• 鉴权：是
• Tag：微信配置模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
ids	body	string[]	是	待删除的素材 id 数组（JSON 数组字符串）

请求体

application/json，字符串数组：

[ "__MEDIA001", "__MEDIA002" ]

请求示例

DELETE /api/authtime/domain/__P1UD2yVWpnFpUedONr/domain/wechat/medias HTTP/1.1
Content-Type: application/json

[ "__MEDIA001", "__MEDIA002" ]

响应

结构：统一 Resource。 data：null。

成功示例：

{ "errcode": 0, "errmsg": "ok", "data": null, "errors": null }

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---