企业微信开发教程

本教程由沈阳农业大学 大学生网络信息中心运行部提供，适用于校园网站开发

企业微信开发

基础概念介绍

corpid

每个企业都拥有唯一的corpid。

secret

secret是企业应用里面用于保障数据安全的"钥匙"，每一个应用都有一个独立的访问密钥，为了保证数据的安全，secret务必不能泄漏。

userid

每个成员都有唯一的userid，即所谓"账号"。

校内即学号

部门id

每个部门都有唯一的id

本科生-学院-班级

agentid

每个应用都有唯一的agentid

例如沈农圈、群聊助手等每个单独应用都有自己的agentid

access_token

access_token是企业后台去企业微信的后台获取信息时的重要票据，由corpid和secret产生。所有接口在通信时都需要携带此信息用于验证接口的访问权限

企业微信开发 - 认证流程

授权流程：

企业微信开发的认证流程如下：

  1. 构造网页授权链接，请求用户权限
  2. 用户确认授权后，跳转到redirect_uri并附带code参数
  3. 获取access_token
  4. 使用access_token + code获取用户userid和user_ticket
  5. 使用access_token + userid获取用户基础信息
  6. 使用access_token + user_ticket获取用户敏感信息

构造网页授权链接

OAuth2 构造网页授权链接

如果企业需要在打开的网页里面携带用户的身份信息，第一步需要构造如下的链接来获取code参数：

https://open.weixin.qq.com/connect/oauth2/authorize?
appid=CORPID&redirect_uri=REDIRECT_URI&response_type=code&scope=snsapi_base&state=STATE&agentid=AGENTID#wechat_redirect
请求参数：
参数必须说明
appid是企业微信的CorpID，在企业微信管理后台获取
redirect_uri是授权后重定向的回调链接地址，重定向链接需经urlEncode处理
response_type是返回类型，此时固定为：code
scope是应用授权作用域，
snsapi_base （不弹出授权页面，直接跳转，只能获取用户UserId）;
snsapi_privateinfo（弹出授权页面，可获取成员的详细信息，包含头像、二维码等敏感信息（此时要求成员必须在应用可见范围内）
state否重定向后会带上state参数，开发者可以填写a-zA-Z0-9的参数值，最多128字节
返回结果：
redirect_uri?code=CODE&state=STATE

获取access_token

GET 获取access_token

access_token是企业微信API的全局唯一接口调用凭据，调用各接口时都需要使用access_token。

GET https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=ID&corpsecret=SECRET
请求参数：
参数必须说明
corpid是企业ID，需要使用时告诉大家
corpsecret是应用的凭证密钥，需要使用时告诉大家
返回结果：
{
    "errcode": 0,
    "errmsg": "ok",
    "access_token": "accesstoken000001",
    "expires_in": 7200
}
注意事项：
  • access_token的有效期通过返回的expires_in来传达，正常情况下为7200秒（2小时），需定时刷新
  • 不能频繁调用gettoken接口，否则会受到频率拦截，因此需要缓存access_token，并设置定时重新获取
实际获取方法

每一个应用都会自动生成获取access_token的脚本，用来定时缓存access_token，缓存后的access_token以文本形式储存。

只想要向指定连接请求即可获取到access_token

// 获取access_token
$access_tokenFile = getUrl("access_tokenFile_url");// 这里替换为实际的access_token文件URL，此处采用的是函数getUrl()来获取指定连接，详情见完整代码
$access_tokenResult = file_get_contents($access_tokenFile);
if (!$access_tokenResult) {
echo json_encode(['code' => 404, 'msg' => 'access_token获取失败']);
exit;
}
$access_tokenData = json_decode($access_tokenResult, true);
$access_token = $access_tokenData['access_token']; // 全局access_token

获取用户身份

GET 获取用户身份

该接口用于根据code获取成员信息，适用于自建应用与代开发应用

GET https://qyapi.weixin.qq.com/cgi-bin/auth/getuserinfo?access_token=ACCESS_TOKEN&code=CODE
请求参数：
参数必须说明
access_token是调用接口凭证，获取方法见上
code是通过成员授权获取到的code，最大为512字节。每次成员授权带上的code将不一样，code只能使用一次，5分钟未被使用自动过期。
返回结果：
{
"errcode": 0,
"errmsg": "ok",
"userid":"USERID",
"user_ticket": "USER_TICKET"
}
参数说明
errcode返回码
errmsg对返回码的文本描述内容
userid成员UserID。若需要获得用户详情信息，可调用通讯录接口：读取成员。
user_ticket成员票据，最大为512字节，有效期为1800s。
scope为snsapi_privateinfo，且用户在应用可见范围之内时返回此参数。
后续利用该参数可以获取用户信息或敏感信息。
实际开发示例：
// 用access_token和code去换UserID
$WORKWeChatInformationRetrievalLink = getUrl("WORKWeChatInformationRetrievalLink") . $access_token . "&code=" . $code;
$WORKWeChatInformation = file_get_contents($WORKWeChatInformationRetrievalLink);
if ($WORKWeChatInformation === false) {
echo json_encode(['code' => 404, 'msg' => '无法获取用户基础信息']);
exit;
}
$WORKWeChatInformation = json_decode($WORKWeChatInformation, true);
$user_ticket = $WORKWeChatInformation["user_ticket"];
$UserID = $WORKWeChatInformation["userid"];

获取用户基础信息

GET 获取用户基础信息

该接口用于获取用户的基础信息，包括姓名、部门等。

GET https://qyapi.weixin.qq.com/cgi-bin/user/get?access_token=ACCESS_TOKEN&userid=USERID
请求参数：
参数必须说明
access_token是调用接口凭证，获取方法见上
userid是成员UserID，获取方法见上
返回结果：
{
"errcode": 0,
"errmsg": "ok",
"userid": "zhangsan",
"name": "张三",
}
参数说明
errcode返回码
errmsg对返回码的文本描述内容
userid成员UserID
name成员名称
实际开发示例：
//查询基本信息
$ReadEnterpriseWeChatMemberLinks = getUrl("ReadEnterpriseWeChatMemberLinks") . $access_token . "&userid=" . $UserID;
$EnterpriseWeChatMemberInformation = json_decode(curl_get($ReadEnterpriseWeChatMemberLinks), true);
if ($EnterpriseWeChatMemberInformation['errcode'] !== 0) {
echo json_encode(['code' => 404, 'msg' => '获取个人信息失败']);
exit;
}
$name = $EnterpriseWeChatMemberInformation['name'];

获取用户敏感信息

POST 获取用户敏感信息

该接口用于获取用户敏感信息，包括头像、二维码等。

POST https://qyapi.weixin.qq.com/cgi-bin/auth/getuserdetail?access_token=ACCESS_TOKEN
请求包体：
{
"user_ticket": "USER_TICKET"
}
参数必须说明
access_token是调用接口凭证，获取方法见上
user_ticket是成员票据，获取方法见上
返回结果：
{
"errcode": 0,
"errmsg": "ok",
"userid":"lisi",
"gender":"1",
"avatar":"http://shp.qpic.cn/bizmp/xxxxxxxxxxx/0",
"qr_code":"https://open.work.weixin.qq.com/wwopen/userQRCode?vcode=vcfc13b01dfs78e981c",
"mobile": "13800000000",
"email": "zhangsan@gzdev.com",
"biz_mail":"zhangsan@qyycs2.wecom.work",
"address": "广州市海珠区新港中路"
}
参数说明
errcode返回码
errmsg对返回码的文本描述内容
userid成员UserID
gender性别。0表示未定义，1表示男性，2表示女性。仅在用户同意snsapi_privateinfo授权时返回真实值，否则返回0.
avatar头像url。仅在用户同意snsapi_privateinfo授权时返回真实头像，否则返回默认头像
qr_code用户个人二维码（扫描可添加为外部联系人），仅在用户同意snsapi_privateinfo授权时返回
mobile手机，仅在用户同意snsapi_privateinfo授权时返回，第三方应用不可获取
email邮箱，仅在用户同意snsapi_privateinfo授权时返回，第三方应用不可获取
biz_mail企业邮箱，仅在用户同意snsapi_privateinfo授权时返回，第三方应用不可获取
address仅在用户同意snsapi_privateinfo授权时返回，第三方应用不可获取
实际开发示例：
// 用access_token和user_ticket去换敏感用户信息
$ObtainSensitiveInformationLink = getUrl("ObtainSensitiveInformationLink") . $access_token;
$user_ticket = [
"user_ticket" => $user_ticket
];

$SensitiveInformation = postJsonUrl($ObtainSensitiveInformationLink, $user_ticket);
if ($SensitiveInformation["errcode"] !== 0) {
echo json_encode(['code' => 404, 'msg' => '获取个人敏感信息失败：'] . $SensitiveInformation['errmsg']);
exit;
};

企业微信开发 - 自建API参考文档

内部文档

密 内部文档点此查看

参考文档

企业微信内部应用开发文档

登录授权完整代码