文章简介:企业号通讯录具备完全开放的接口,你的应用可以调用这些接口管理部门、成员和标签。你的应用也可以使用部门、成员、标签发消息,或更改应用的可见范围。 |
企业号通讯录具备完全开放的接口,你的应用可以调用这些接口管理部门、成员和标签。
你的应用也可以使用部门、成员、标签发消息,或更改应用的可见范围。
注意,每个部门的直属员工上限为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 |
返回码 |
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个字符。修改部门名称时指定该参数 |
管理员须拥有“操作通讯录”的接口权限,以及该部门的管理权限。
3、删除部门
Https请求方式: GET
https://qyapi.weixin.qq.com/cgi-bin/department/delete?access_token=ACCESS_TOKEN&id=1&id=2
参数 |
必须 |
说明 |
---|
access_token |
是 |
调用接口凭证 |
id |
是 |
部门id。(注:不能删除根部门;不能删除含有子部门、成员的部门) |
管理员须拥有“操作通讯录”的接口权限,以及该部门的管理权限。
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 |
二、管理成员
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 |
否 |
微信号。企业内必须唯一 |
管理员须拥有“操作通讯录”的接口权限,以及指定部门的管理权限。
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表示禁用成员 |
管理员须拥有“操作通讯录”的接口权限,以及指定部门、成员的管理权限。
3、删除成员
Https请求方式: GET
https://qyapi.weixin.qq.com/cgi-bin/user/delete?access_token=ACCESS_TOKEN&userid=lisi
参数 |
必须 |
说明 |
---|
access_token |
是 |
调用接口凭证 |
userid |
是 |
员工UserID。对应管理端的帐号 |
管理员须拥有“操作通讯录”的接口权限,以及指定部门、成员的管理权限。
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 |
返回码 |
errmsg |
对返回码的文本描述内容 |
userlist |
成员列表 |
userid |
员工UserID |
name |
成员名称 |
三、管理标签
1、创建标签
Https请求方式: POST
https://qyapi.weixin.qq.com/cgi-bin/tag/create?access_token=ACCESS_TOKEN
注:标签锁默认为未加锁状态
请求包结构体为:
- {
- "tagname": "UI"
- }
参数 |
必须 |
说明 |
---|
access_token |
是 |
调用接口凭证 |
tagname |
是 |
标签名称。长度为1~64个字符,标签不可与其他同组的标签重名,也不可与全局标签重名 |
无限定。
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个字符 |
管理员必须是指定标签的创建者。
3、删除标签
Https请求方式: GET
https://qyapi.weixin.qq.com/cgi-bin/tag/delete?access_token=ACCESS_TOKEN&tagid=1
参数 |
必须 |
说明 |
---|
access_token |
是 |
调用接口凭证 |
tagid |
是 |
标签ID |
管理员必须是指定标签的创建者,并且标签的成员列表为空。
4、获取标签成员
Https请求方式: GET
https://qyapi.weixin.qq.com/cgi-bin/tag/get?access_token=ACCESS_TOKEN&tagid=1
参数 |
必须 |
说明 |
---|
access_token |
是 |
调用接口凭证 |
tagid |
是 |
标签ID |
管理员须拥有“获取标签成员”的接口权限,标签须对管理员可见;返回列表仅包含管理员管辖范围的成员。
参数 |
说明 |
---|
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列表,以“|”分隔 |
该文章在 2014/12/2 0:47:33 编辑过