1. 核心概念

在企业微信中，调用 API 并非直接“申请”一个通用的钥匙，而是通过‌创建自建应用‌来获取专属的身份凭证（Secret）。每个应用拥有独立的权限范围，需根据业务需求配置。

2. 前置准备

• ‌管理员权限‌：你需要是企业微信的管理员或具有应用管理权限的成员。
• ‌**企业 ID (CorpID)**‌：企业的唯一标识，全局通用。

3. 详细操作步骤

第一步：获取企业 ID (CorpID)

1. 登录 企业微信管理后台。
2. 点击左侧菜单 ‌**【我的企业】**‌。
3. 在页面底部找到 ‌**“企业ID”**‌，点击复制并保存。

第二步：创建自建应用

1. 点击左侧菜单 ‌**【应用管理】‌ > ‌【应用】‌ > ‌【创建应用】**‌。
2. 填写应用信息：
   • ‌应用名称‌：例如“AI客服助手”或“客户数据同步”。
   • ‌应用头像‌：上传图标。
   • ‌可见范围‌：选择哪些成员可以使用该应用（通常选全员或特定部门）。
3. 点击 ‌**【创建应用】**‌ 按钮。

第三步：获取应用 Secret (CorpSecret)

1. 创建成功后，进入该应用的详情页。
2. 找到 ‌**“AgentId”‌ 和 ‌“Secret”**‌ 栏目。
3. 点击 Secret 旁边的 ‌**“查看”‌ 或 ‌“重新获取”**‌。
4. 扫码验证后，系统将显示一串字符，即为 CorpSecret。

   ⚠️ ‌重要提示‌：Secret 只会显示一次，请务必立即复制并妥善保存。如果丢失，只能重置，重置后旧 Secret 将失效。

第四步：配置可信 IP (必做)

为了安全，企业微信要求调用 API 的服务器 IP 必须在白名单内。

1. 在应用详情页，找到 ‌**“企业可信IP”**‌ 配置项。
2. 点击 ‌**“配置”**‌。
3. 输入你服务器出口的公网 IP 地址（如果是本地测试，可查询本机公网 IP）。
4. 点击确定保存。

   ❌ 如果不配置可信 IP，调用接口时会返回错误码 60020 (not allow to access from your ip)。

第五步：配置接口权限

不同 API 需要不同的权限，需在对应模块中授权该应用。

• ‌示例：获取客户列表‌
  1. 进入 ‌**【客户与上下游】‌ > ‌【客户联系】**‌。
  2. 找到 ‌**“可调用的应用”‌ 或 ‌“权限配置”**‌。
  3. 将刚才创建的应用添加进去。
• ‌示例：会话存档‌
  1. 进入 ‌**【管理工具】‌ > ‌【会话存档】**‌。
  2. 开启功能并授权应用。

4. 接口调用流程

获取到 CorpID 和 Secret 后，调用 API 的标准流程如下：

1. 获取 Access Token

所有接口调用都需要先获取 access_token。

• ‌请求 URL‌:

  text
  GET https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=ID&corpsecret=SECRET
  

• ‌参数‌:
  • corpid: 企业 ID
  • corpsecret: 应用的 Secret
• ‌返回‌:

  json
  {
    "errcode": 0,
    "errmsg": "ok",
    "access_token": "ACCESS_TOKEN_STRING",
    "expires_in": 7200
  }
  

• ‌注意‌: access_token 有效期为 2 小时（7200秒），建议服务端缓存，不要每次请求都重新获取。

2. 调用业务接口

使用获取到的 access_token 调用具体业务接口。

• ‌示例：获取外部联系人列表‌

  text
  GET https://qyapi.weixin.qq.com/cgi-bin/externalcontact/list?access_token=ACCESS_TOKEN&userid=USERID
  

5. 常见问题排查

表格

| 错误码 | 含义 | 解决方案 | | :----- | :------------------------------- | :------------------------------------- | | 40014 | invalid access_token | Token 过期或无效，请重新获取 | | 60020 | not allow to access from your ip | 未配置可信 IP 或 IP 填写错误 | | 48002 | no api permission | 应用未在对应模块（如客户联系）中授权 | | 40001 | invalid credential | Secret 错误或已重置，请检查最新 Secret |

6. 最佳实践建议

1. ‌安全性‌：严禁将 CorpSecret 硬编码在前端代码或公开仓库中。
2. ‌Token 缓存‌：使用 Redis 或内存缓存存储 access_token，避免频繁请求导致限流。
3. ‌多应用隔离‌：建议为不同业务场景（如 CRM、OA、AI 机器人）创建不同的应用，以便精细化控制权限和审计日志。