企业微信API怎么用？

wen python案例 2026-07-21 3

本文目录导读：

企业微信API怎么用？

第一步：准备工作
第二步：核心接入流程
第三步：常用API示例（以发送应用消息为例）
你必须知道的几个关键概念
推荐开发路径
常见坑点提醒

企业微信API的使用主要分为开发前的准备、核心接入流程和具体功能调用三个步骤，下面为你梳理一个清晰的使用指南。

第一步：准备工作

在使用API前,你需要先在企业微信管理后台完成以下配置：

注册企业微信：你需要有一个企业的管理员账号。
创建自建应用：
- 进入「应用管理」 -> 「自建」 -> 「创建应用」。
- 填写应用名称、Logo，并选择可见范围（哪些成员可以使用）。
- 创建成功后,你会获得两个关键信息：
  - 企业ID（CorpID）：企业的唯一标识，在「我的企业」->「企业信息」中查看。
  - 应用Secret（CorpSecret）：应用的密钥，用于获取access_token（访问令牌）。请务必保管好，不要泄露。
配置应用权限：
- 在应用详情页,点击「权限管理」，你需要根据API功能（如发消息、获取成员信息等）添加对应的权限。权限的添加需要企业微信管理员扫码确认。
配置IP白名单（强烈建议）：
在「我的企业」->「安全管理」->「IP白名单」中，将你的服务器公网IP加入白名单，这样可以防止未授权的服务器访问你的API。

第二步：核心接入流程

所有企业微信API的调用都基于一个核心凭证：access_token。

流程如下：

获取 access_token
- 请求方式：GET
- 请求地址：
```
https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=YOUR_CORPID&corpsecret=YOUR_CORPSECRET
```
- 将 YOUR_CORPID 和 YOUR_CORPSECRET 替换为第一步获取的值。
- 成功响应示例：
```
{
    "errcode": 0,
    "errmsg": "ok",
    "access_token": "YOUR_ACCESS_TOKEN",
    "expires_in": 7200
}
```
- 重要说明：
  - access_token 有效期为 7200秒（2小时）。
  - 你需要自己实现缓存机制（存到本地文件、数据库或Redis），在过期前重新获取，避免每次请求都去获取新的token（企业微信对获取token的频率有限制）。
调用具体功能API
- 你获得的 access_token 会作为查询参数拼接到所有后续API的URL后面。
- 通用请求地址格式：
```
https://qyapi.weixin.qq.com/cgi-bin/具体接口路径?access_token=YOUR_ACCESS_TOKEN
```
  （发消息的地址是 https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=YOUR_ACCESS_TOKEN）

第三步：常用API示例（以发送应用消息为例）

这是最常用的功能,可以将系统消息推送给企业微信用户。

API：https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=ACCESS_TOKEN
请求方式：POST
请求头：Content-Type: application/json

请求体示例（发送文本消息给某个用户）：

{
    "touser": "USER_ID",          // 用户的UserID，可在通讯录里查看
    "toparty": "",                 // 部门ID（可选）
    "totag": "",                   // 标签ID（可选）
    "msgtype": "text",
    "agentid": 1000002,            // 你的应用AgentId（在应用详情页查看）
    "text": {
        "content": "你好，这是一条来自API的测试消息！"
    },
    "safe": 0,                      // 0：普通消息，1：保密消息
    "enable_id_trans": 0,
    "enable_duplicate_check": 0
}

成功响应：

{
    "errcode": 0,
    "errmsg": "ok",
    "invaliduser": "",   // 如果部分用户发送失败，这里会列出
    "invalidparty": "",
    "invalidtag": ""
}

你必须知道的几个关键概念

UserID：用户在企业的唯一标识（不是手机号，也不是微信号），可以在管理后台「通讯录」中查看，或通过user/getuserinfo接口根据OAuth2.0的code换取。
AgentId：每个自建应用在创建时生成的唯一ID。
Access_Token：通行证，必须按上述方式获取并缓存。
时区：企业微信API使用的时间戳是Unix毫秒级时间戳（如 1678886400000）。
错误码：所有API返回的json中都包含 errcode 字段。0 表示成功，非0表示失败（如 40014 表示access_token无效）。

常见坑点提醒

Access_Token 必须缓存：频繁请求会导致频率限制（45009）。
IP白名单：如果遇到 60020 错误，通常是你访问API的IP没有加到白名单里。
消息发送失败：检查 touser 的UserID是否正确，以及该用户是否在你的应用可见范围内。
图片/文件上传：需要使用POST multipart/form-data方式上传，并先获取一个临时素材media_id，然后通过media_id发送。

如果你有具体的需求（比如发图文、获取用户详情、实现OAuth2.0登录等），可以告诉我，我可以给你更具体的代码示例。