微信企业号开发之如何管理通讯录-微信企业号管理平台

企业号通讯录具备完全开放的接口，你的应用可以调用这些接口管理部门、成员和标签。

你的应用也可以使用部门、成员、标签发消息，或更改应用的可见范围。

注意，每个部门的直属员工上限为1000个；出于安全考虑，某些接口需要在管理端有明确的授权。

一、管理部门

1、创建部门

请求说明

Https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/department/create?access_token=ACCESS_TOKEN

请求包结构体为:

{ 
   "name": "邮箱产品组", 
   "parentid": "1" 
}

参数说明

参数	必须	说明
access_token	是	调用接口凭证
name	是	部门名称。长度限制为1~64个字符
parentid	是	父亲部门id。根部门id为1

权限说明

管理员须拥有“操作通讯录”的接口权限，以及父部门的管理权限。

返回结果

{ 
   "errcode": 0, 
   "errmsg": "created", 
   "id": 2 
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
id	创建的部门id。

2、更新部门

请求说明

Https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/department/update?access_token=ACCESS_TOKEN

请求包结构体为（如果非必须的字段未指定，则不更新该字段之前的设置值）:

{ 
   "id": 2, 
   "name": "邮箱产品部" 
}

参数说明

参数	必须	说明
access_token	是	调用接口凭证
id	是	部门id。
name	否	更新的部门名称。长度限制为0~64个字符。修改部门名称时指定该参数

权限说明

管理员须拥有“操作通讯录”的接口权限，以及该部门的管理权限。

返回结果

{ 
   "errcode": 0, 
   "errmsg": "updated" 
}

3、删除部门

请求说明

Https请求方式: GET

https://qyapi.weixin.qq.com/cgi-bin/department/delete?access_token=ACCESS_TOKEN&id=1&id=2

参数说明

参数	必须	说明
access_token	是	调用接口凭证
id	是	部门id。（注：不能删除根部门；不能删除含有子部门、成员的部门）

权限说明

管理员须拥有“操作通讯录”的接口权限，以及该部门的管理权限。

返回结果

{ 
   "errcode": 0, 
   "errmsg": "deleted" 
}

4、获取部门列表

请求说明

Https请求方式: GET

https://qyapi.weixin.qq.com/cgi-bin/department/list?access_token=ACCESS_TOKEN

参数说明

参数	必须	说明
access_token	是	调用接口凭证

权限说明

管理员须拥有’获取部门列表’的接口权限，以及对部门的查看权限。

返回结果

{ 
   "errcode": 0, 
   "errmsg": "ok", 
   "department": [ 
       { 
           "id": 1, 
           "name": "广州研发中心", 
           "parentid": 0 
       }, 
       { 
           "id": 2 
           "name": "邮箱产品部", 
           "parentid": 1 
       } 
   ] 
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
department	部门列表数据
id	部门id
name	部门名称
parentid	父亲部门id。根部门为1

#p#

二、管理成员

1、创建成员

请求说明

Https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/user/create?access_token=ACCESS_TOKEN

请求包结构体为:

{ 
   "userid": "zhangsan", 
   "name": "张三", 
   "department": [1, 2], 
   "position": "产品经理", 
   "mobile": "15913215421", 
   "gender": 1, 
   "tel": "62394", 
   "email": "zhangsan@gzdev.com", 
   "weixinid": "zhangsan4dev" 
}

参数说明

参数	必须	说明
access_token	是	调用接口凭证
userid	是	员工UserID。对应管理端的帐号，企业内必须唯一
name	是	成员名称。长度为1~64个字符
department	否	成员所属部门id列表。注意，每个部门的直属员工上限为1000个
position	否	职位信息。长度为0~64个字符
mobile	否	手机号码。企业内必须唯一，mobile/weixinid/email三者不能同时为空
gender	否	性别。gender=0表示男，=1表示女。默认gender=0
tel	否	办公电话。长度为0~64个字符
email	否	邮箱。长度为0~64个字符。企业内必须唯一
weixinid	否	微信号。企业内必须唯一

权限说明

管理员须拥有“操作通讯录”的接口权限，以及指定部门的管理权限。

返回结果

{ 
   "errcode": 0, 
   "errmsg": "created" 
}

2、更新成员

请求说明

Https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/user/update?access_token=ACCESS_TOKEN

请求包示例如下（如果非必须的字段未指定，则不更新该字段之前的设置值）:

{ 
   "userid": "zhangsan", 
   "name": "李四", 
   "department": [1], 
   "position": "后台工程师", 
   "mobile": "15913215421", 
   "gender": 1, 
   "tel": "62394", 
   "email": "zhangsan@gzdev.com", 
   "weixinid": "lisifordev", 
   "enable": 1 
}

参数说明

参数	必须	说明
access_token	是	调用接口凭证
userid	是	员工UserID。对应管理端的帐号，企业内必须唯一
name	否	成员名称。长度为0~64个字符
department	否	成员所属部门id列表。注意，每个部门的直属员工上限为1000个
position	否	职位信息。长度为0~64个字符
mobile	否	手机号码。企业内必须唯一，更新后的成员mobile/weixinid/email三者不能同时为空
gender	否	性别。gender=0表示男，=1表示女。默认gender=0
tel	否	办公电话。长度为0~64个字符。必须企业内唯一
email	否	邮箱。长度为0~64个字符。企业内必须唯一
weixinid	否	微信号。企业内必须唯一
enable	否	启用/禁用成员。1表示启用成员，0表示禁用成员

权限说明

管理员须拥有“操作通讯录”的接口权限，以及指定部门、成员的管理权限。

返回结果

{ 
   "errcode": 0, 
   "errmsg": "updated" 
}

3、删除成员

请求说明

Https请求方式: GET

https://qyapi.weixin.qq.com/cgi-bin/user/delete?access_token=ACCESS_TOKEN&userid=lisi

参数说明

参数	必须	说明
access_token	是	调用接口凭证
userid	是	员工UserID。对应管理端的帐号

权限说明

管理员须拥有“操作通讯录”的接口权限，以及指定部门、成员的管理权限。

返回结果

{ 
   "errcode": 0, 
   "errmsg": "deleted" 
}

4、获取成员

请求说明

Https请求方式: GET

https://qyapi.weixin.qq.com/cgi-bin/user/get?access_token=ACCESS_TOKEN&userid=lisi

参数说明

参数	必须	说明
access_token	是	调用接口凭证
userid	是	员工UserID

返回结果

{ 
   "errcode": 0, 
   "errmsg": "ok", 
   "userid": "zhangsan", 
   "name": "李四", 
   "department": [1, 2], 
   "position": "后台工程师", 
   "mobile": "15913215421", 
   "gender": 1, 
   "tel": "62394", 
   "email": "zhangsan@gzdev.com", 
   "weixinid": "lisifordev",   
   "avatar": "http://wx.qlogo.cn/mmopen/ajNVdqHZLLA3WJ6DSZUfiakYe37PKnQhBIeOQBO4czqrnZDS79FH5Wm5m4X69TBicnHFlhiafvDwklOpZeXYQQ2icg/0", 
   "status": 1 
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
userid	员工UserID
name	成员名称
department	成员所属部门id列表
position	职位信息
mobile	手机号码
gender	性别。gender=0表示男，=1表示女
tel	办公电话
email	邮箱
weixinid	微信号
avatar	头像url。注：如果要获取小图将url***的"/0"改成"/64"即可
status	关注状态: 1=已关注，2=已冻结，4=未关注

权限说明

管理员须拥有’获取成员’的接口权限，以及成员的查看权限。

5、获取部门成员

请求说明

Https请求方式: GET

https://qyapi.weixin.qq.com/cgi-bin/user/simplelist?access_token=ACCESS_TOKEN&department_id=1&fetch_child=0&status=0

参数说明

参数	必须	说明
access_token	是	调用接口凭证
department_id	是	获取的部门id
fetch_child	否	1/0：是否递归获取子部门下面的成员
status	否	0获取全部员工，1获取已关注成员列表，2获取禁用成员列表，4获取未关注成员列表。status可叠加

权限说明

管理员须拥有’获取部门成员’的接口权限，以及指定部门的查看权限。

返回结果

{ 
   "errcode": 0, 
   "errmsg": "ok", 
   "userlist": [ 
           { 
                  "userid": "zhangsan", 
                  "name": "李四" 
           } 
     ] 
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
userlist	成员列表
userid	员工UserID
name	成员名称

#p#

三、管理标签

1、创建标签

请求说明

Https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/tag/create?access_token=ACCESS_TOKEN

注：标签锁默认为未加锁状态

请求包结构体为:

{ 
   "tagname": "UI" 
}

参数说明

参数	必须	说明
access_token	是	调用接口凭证
tagname	是	标签名称。长度为1~64个字符，标签不可与其他同组的标签重名，也不可与全局标签重名

权限说明

无限定。

返回结果

{ 
   "errcode": 0, 
   "errmsg": "created" 
   "tagid": "1" 
}

2、更新标签名字

请求说明

Https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/tag/update?access_token=ACCESS_TOKEN

请求包示例如下:

{ 
   "tagid": "1", 
   "tagname": "UI design" 
}

参数说明

参数	必须	说明
access_token	是	调用接口凭证
tagid	是	标签ID
tagname	是	标签名称。最长64个字符

权限说明

管理员必须是指定标签的创建者。

返回结果

{ 
   "errcode": 0, 
   "errmsg": "updated" 
}

3、删除标签

请求说明

Https请求方式: GET

https://qyapi.weixin.qq.com/cgi-bin/tag/delete?access_token=ACCESS_TOKEN&tagid=1

参数说明

参数	必须	说明
access_token	是	调用接口凭证
tagid	是	标签ID

权限说明

管理员必须是指定标签的创建者，并且标签的成员列表为空。

返回结果

{ 
   "errcode": 0, 
   "errmsg": "deleted" 
}

4、获取标签成员

请求说明

Https请求方式: GET

https://qyapi.weixin.qq.com/cgi-bin/tag/get?access_token=ACCESS_TOKEN&tagid=1

参数说明

参数	必须	说明
access_token	是	调用接口凭证
tagid	是	标签ID

权限说明

管理员须拥有“获取标签成员”的接口权限，标签须对管理员可见；返回列表仅包含管理员管辖范围的成员。

返回结果

{ 
   "errcode": 0, 
   "errmsg": "ok", 
   "userlist": [ 
         { 
             "userid": "zhangsan", 
             "name": "李四" 
         } 
     ] 
}

参数	说明
errcode	错误码
errmsg	错误消息
userlist	成员列表
userid	员工UserID

5、增加标签成员

请求说明

Https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/tag/addtagusers?access_token=ACCESS_TOKEN

请求包示例如下:

{ 
   "tagid": "1", 
   "userlist":[ "user1","user2"] 
}

参数说明

参数	必须	说明
access_token	是	调用接口凭证
tagid	是	标签ID
userlist	是	企业员工ID列表

权限说明

标签对管理员可见且未加锁，成员属于管理员管辖范围。

返回结果

a)正确时返回

{ 
   "errcode": 0, 
   "errmsg": "ok" 
}

b)若部分userid非法，则返回

{ 
   "errcode": 0, 
   "errmsg": "invalid userlist failed" 
   "invalidlist"："usr1|usr2|usr" 
}

c)当包含userid全部非法时返回

{ 
   "errcode": 40070, 
   "errmsg": "all list invalid " 
}

参数	说明
errcode	错误码
errmsg	错误消息
invalidlist	不在权限内的员工ID列表，以“\|”分隔

6、删除标签成员

请求说明

Https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/tag/deltagusers?access_token=ACCESS_TOKEN

请求包如下

{ 
   "tagid": "1", 
   "userlist":[ "user1","user2"] 
}

参数说明

参数	必须	说明
access_token	是	调用接口凭证
tagid	是	标签ID
userlist	是	企业员工ID列表

权限说明

标签对管理员可见且未加锁，成员属于管理员管辖范围。

返回结果

a)正确时返回

{ 
   "errcode": 0, 
   "errmsg": "deleted" 
}

b)若部分userid非法，则返回

{ 
   "errcode": 0, 
   "errmsg": "invalid userlist failed" 
   "invalidlist"："usr1|usr2|usr" 
}

c)当包含的userid全部非法时返回

{ 
   "errcode": 40031, 
   "errmsg": "all list invalid" 
}

参数	说明
errcode	错误码
errmsg	错误消息
invalidlist	不在权限内的或者非法的员工ID列表，以“\|”分隔