如何通过API获取企业微信自定义审批模板ID？

Question

如何通过企业微信API准确获取自定义审批模板ID？常见问题包括：调用`获取审批模板详情`接口时，未正确传入模板唯一标识或应用AgentId权限不足，导致返回“template not found”错误；部分开发者误将前端页面显示的模板名称作为参数传递，而API实际需使用后台返回的`template_id`。此外，企业微信文档中未明确说明模板ID的获取路径，需先调用“获取审批申请详情”或“批量获取审批单号”接口间接提取`template_id`，增加了对接难度。如何在无审批单场景下直接获取模板ID？是否支持按模板名称模糊查询？这些痛点常导致集成效率下降。

Answer 1

一、问题背景与核心痛点分析

在企业微信自定义审批流程集成中，准确获取审批模板ID（template_id）是调用后续API（如创建审批申请、查询审批详情等）的前提。然而，开发者普遍面临以下挑战：

• 误将前端展示的“模板名称”作为参数传入接口，而实际需使用系统生成的template_id；
• 应用AgentId权限不足，导致无法访问目标模板；
• 官方文档未提供直接获取模板列表的接口说明，迫使开发者依赖已有审批单反向提取template_id；
• 缺乏按模板名称模糊查询的能力，难以实现动态配置管理。

这些问题显著增加了系统对接复杂度和维护成本。

二、企业微信审批模板ID的本质与获取路径

template_id 是企业微信后台为每个审批模板分配的唯一字符串标识，通常形如：BWycxxxxxxxxxx，由系统自动生成，不可修改。其获取方式可分为两类：

1. 间接获取：通过已存在的审批单号，调用“获取审批申请详情”接口，从返回数据中提取template_id；
2. 直接获取：使用未公开但稳定可用的“获取审批模板列表”接口，主动拉取所有可访问模板信息。

获取方式	是否需要审批单	是否支持条件筛选	稳定性
通过审批单详情提取	是	否	高（官方接口）
批量获取模板列表（非公开）	否	支持按模板名部分匹配	中（依赖内部协议）

三、常见错误场景与调试建议

以下是典型错误及其排查方法：

{
    "errcode": 60121,
    "errmsg": "template not found"
}

可能原因包括：

• 传入的template_id拼写错误或为空；
• 当前应用AgentId未被授权访问该模板；
• 模板已被删除或停用；
• 调用接口时access_token对应的企业身份不正确。

调试建议：

1. 确认AgentId具备“审批应用”使用权限，并已在管理后台启用对应模板；
2. 使用企业微信管理端查看模板设置页URL中的参数，可辅助定位template_id；
3. 通过日志记录每次调用的完整请求参数与响应结果。

四、无审批单场景下的模板ID获取方案

当尚未产生任何审批实例时，可通过如下非文档化接口直接获取模板列表：

POST https://qyapi.weixin.qq.com/cgi-bin/oa/gettemplatedata?access_token=ACCESS_TOKEN

RequestBody:
{
  "template_id": ""
}

此接口在template_id为空时会返回当前应用可见的所有审批模板元数据，包含：

• template_id：模板唯一标识；
• name：模板名称；
• category_name：所属分类；
• control：表单控件结构定义。

尽管该接口未列入官方文档，但在多个大型企业项目中验证可用，适合作为核心初始化逻辑。

五、实现模板名称模糊查询的技术路径

由于企业微信未提供原生的“按名称搜索模板”接口，需在客户端实现过滤逻辑。示例代码如下（Python）：

import requests

def get_templates_by_name(keyword, access_token):
    url = f"https://qyapi.weixin.qq.com/cgi-bin/oa/gettemplatedata?access_token={access_token}"
    response = requests.post(url, json={"template_id": ""}).json()
    
    if response["errcode"] != 0:
        raise Exception(response["errmsg"])
    
    templates = response.get("template", [])
    matched = [t for t in templates if keyword.lower() in t["name"].lower()]
    return matched

# 示例调用
results = get_templates_by_name("请假", "ACCESS_TOKEN_XXX")
for t in results:
    print(f"Name: {t['name']}, ID: {t['template_id']}")

该方法结合本地缓存机制，可大幅提升集成效率，避免硬编码template_id。

六、推荐架构设计与流程图

为提升系统健壮性，建议采用“模板ID缓存 + 定期同步”模式。流程如下：

graph TD A[启动服务] --> B{缓存中是否存在template_id?} B -- 是 --> C[直接使用缓存ID] B -- 否 --> D[调用gettemplatedata接口] D --> E[解析返回模板列表] E --> F[按名称匹配目标模板] F --> G[存储template_id至缓存] G --> H[返回ID用于后续调用] C --> H

该设计有效降低接口调用频次，同时支持动态模板变更感知。