企业微信-通讯录管理-成员管理以及部门管理

官方文档
通讯录管理的相关接口可以对企业微信里面部门、成员、标签等通讯录信息进行查询、添加、修改、删除等操作。

一、开启企业微信通讯录相关权限

我们使用通讯录管理的相关接口，原则上需要使用 通讯录管理的 secret，但实际上我们也可以使用企业内应用 secret。
但是使用应用 secret 只能进行“查询”、“邀请”等非写操作，而且只能操作应用可见范围内的通讯录。

获取通讯录管理 secret 的流程：

1. 进入企业微信管理后台，在“管理工具” — “通讯录同步”开启“API 接口同步”

2. 默认是只读通讯录，在改状态下我们只能调用读取类型的 API 接口，我们将接口设置为“API 编辑通讯录”。设置为 API 接口通讯录后我们就可以调用编辑类型的 API 接口了。
   
3. 我们在开启“API 编辑通讯录”时还可以设置“开启手动编辑”，但是我们需要设置接收事件的 URL 才可以同步更新数据源。

4. 点击“查看 Secret”来获取 Secret 以供后面我们使用接口使用。

二、成员管理

1.创建成员

• 请求地址：https://qyapi.weixin.qq.com/cgi-bin/user/create
• 请求方式：POST
• Token:通过 Secret 获取（所有请求都需要 Token，后面将不再强调）
• 请求体：

{
    
  "userid": "zhangsan",//用户id，任意编写，不可重复，必填项
  "name": "张三",//用户名，必填项
  "alias": "jackzhang",//用户别名，非必填项
  "department": [2],//部门列表，默认第一个部门id为1其他顺延，可在通讯录内查看，必填项
  "mobile": "+86 15355392295"//手机号，非必填项
}

• 返回结果：

	{
     "errcode": 0, "errmsg": "created" }
//errcode	返回码,为 0 则请求成功
//errmsg	对返回码的文本描述内容，created是添加
//其他请求返回结果大体相同，下面我们主要对不同的地方进行解释

• 请求结果

• 请求体参数：

• 注意：
  a.手机号码企业内唯一，手机号和邮箱两者不可都为空
  b.该接口仅通讯录同步助手或第三方通讯录应用可调用。
  c.每个部门下的部门、成员总数不能超过 3 万个。

2.读取成员

• 请求地址：https://qyapi.weixin.qq.com/cgi-bin/user/get?access_token=ACCESS_TOKEN&userid=USERID
• 请求方式：GET
• URL 参数说明：
  access_token：必填，调用接口凭证
  userid：必填，成员 UserID。对应管理端的帐号，企业内必须唯一。不区分大小写，长度为 1~64 个字节
• 返回结果：

	{
    "errcode":0,
    "errmsg":"ok",
    "userid":"zhangsan",
    "name":"张三",
    "department":[2],
    "position":"",
    "mobile":"15355392295",
    "gender":"0",
    "email":"",
    "avatar":"",
    "status":4,
    "isleader":0,
    "extattr":{
    "attrs":[]},
    "telephone":"",
    "enable":1,
    "hide_mobile":0,
    "order":[0],
    "main_department":2,
    "qr_code":"https://open.work.weixin.qq.com/wwopen/userQRCode?vcode=vcf173435ef4ab2387",
    "alias":"jackzhang",
    "is_leader_in_dept":[0],
    "thumb_avatar":""}
    //在返回结果里面暂时添加成员时可设置的所有参数，参数未设置则默认为空，参数代表函数与添加成员时参数含义相同
    //userid就是成员的账号

3.更新成员

• 请求地址：https://qyapi.weixin.qq.com/cgi-bin/user/update?access_token=ACCESS_TOKEN
• 请求方式：POST
• 请求体：

{
    
  "userid": "zhangsan",
  "name": "李四"
}
//将 张三 用户名修改为 李四

• 返回结果：

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

• 请求体参数：与创建成员相同

• 注意：
  a.若该成员已经激活了企业微信，则不可以通过该接口修改其手机号和邮箱了，如若修改则会被系统直接忽略，也不会报错。

4.删除成员

• 请求地址：https://qyapi.weixin.qq.com/cgi-bin/user/delete?access_token=ACCESS_TOKEN&userid=USERID
• 请求方式：GET
• URL 参数说明：
  access_token：必填，调用接口凭证
  userid：必填，成员 UserID。对应管理端的帐号，企业内必须唯一。不区分大小写，长度为 1~64 个字节
• 返回结果：

{
    
    //与读取成员用法基本相同
    //下面的返回结果若与前面描述的类似，则不再一一展示
   "errcode": 0,
   "errmsg": "deleted"
}

• 注意：
  a.若是绑定了腾讯企业邮，则会同时删除邮箱帐号。

5.批量删除成员

• 请求地址：https://qyapi.weixin.qq.com/cgi-bin/user/batchdelete?access_token=ACCESS_TOKEN
• 请求方式：POST
• 请求体：

{
    
   "useridlist": ["zhangsan", "lisi"]
}
//useridlist是成员UserID列表。对应管理端的帐号。最多支持200个。若存在无效UserID，直接返回错误
//这里删除了id是 zhangsan 和 lisi 的成员

6.获取部门成员

• 请求地址：https://qyapi.weixin.qq.com/cgi-bin/user/simplelist?access_token=ACCESS_TOKEN&department_id=DEPARTMENT_ID&fetch_child=FETCH_CHILD
• 请求方式：GET
• URL 参数说明：
  access_token：必填，调用接口凭证
  department_id：必填，获取的部门 id
  fetch_child：非必填，是否递归获取子部门下面的成员：1-递归获取，0-只获取本部门
• 返回结果：

//测试时部门id使用的是 1，奇异果平台企业
//由于奇异果部门成员过多，这里只展示了一部分作为例子
	{
    
    "errcode":0,
    "errmsg":"ok",
    "userlist":[//用户列表
    {
    "userid":"MaoYingYong",//成员UserID。对应管理端的帐号
    "name":"毛英勇",//成员名称
    "department":[1]//成员所属部门列表，列表项为部门ID
    },
    {
    "userid":"d41d8cd98f00b204e9800998ecf8427e",
    "name":"āáǎà",
    "department":[1]},
    {
    "userid":"MoDaoBuXiaoHun",
    "name":"莫道不消魂",
    "department":[1]},
    {
    "userid":"peach.z",
    "name":"PEACH.Z",
    "department":[1]},
    {
    "userid":"Guang",
    "name":"程光远",
    "department":[1]}
    ]
    }

7.获取部门成员详情

• 请求地址：https://qyapi.weixin.qq.com/cgi-bin/user/list?access_token=ACCESS_TOKEN&department_id=DEPARTMENT_ID&fetch_child=FETCH_CHILD
• 请求方式：GET
• URL 参数说明：
  access_token：必填，调用接口凭证
  department_id：必填，获取的部门 id
  fetch_child：非必填，是否递归获取子部门下面的成员：1-递归获取，0-只获取本部门
• 返回结果：与获取部门成员相似，只不过是返回的结果里面展示了每个成员的详细信息，详细信息的参数与创建成员参数相同

8.二次验证

• 请求地址：https://qyapi.weixin.qq.com/cgi-bin/user/authsucc?access_token=ACCESS_TOKEN&userid=USERID

• 请求方式：GET

• 接口介绍：
  此接口可以满足安全性要求高的企业进行成员验证。开启二次验证后，当且仅当成员登录时，需跳转至企业自定义的页面进行验证。验证频率可在设置页面选择。
  企业在开启二次验证时，必须在管理端填写企业二次验证页面的 url。

  

9.邀请成员

• 请求地址：https://qyapi.weixin.qq.com/cgi-bin/batch/invite?access_token=ACCESS_TOKEN
• 请求方式：POST
• 请求体：

{
    
  "user": ["zhangsan"],
  "party" : [PartyID1, PartyID2],
  "tag" : [TagID1, TagID2]
}

• 请求体参数说明：
  user：非必填， 成员 ID 列表, 最多支持 1000 个。
  party：非必填， 部门 ID 列表，最多支持 100 个。
  tag：非必填， 标签 ID 列表，最多支持 100 个。

• 请求结果

• 注意：
  a.user, party, tag 三者不能同时为空；
  b.如果部分接收人无权限或不存在，邀请仍然执行，但会返回无效的部分（即 invaliduser 或 invalidparty 或 invalidtag）;
  c.同一用户只须邀请一次，被邀请的用户如果未安装企业微信，在 3 天内每天会收到一次通知，最多持续 3 天。

10.手机号获取 userid

• 请求地址：https://qyapi.weixin.qq.com/cgi-bin/user/getuserid?access_token=ACCESS_TOKEN
• 请求方式：POST
• 请求体：

{
    
       "mobile": "13731319326"
}

• 请求体参数说明：
  mobile:必填，手机号码。长度为 5~32 个字节

• 返回参数：

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

• 注意：
  a.请确保手机号的正确性，若出错的次数较多，会导致 1 天不可调用。

三、部门管理

1.创建部门

• 请求地址：https://qyapi.weixin.qq.com/cgi-bin/department/create?access_token=ACCESS_TOKEN
• 请求方式：POST
• 请求体：

{
    
  "name": "龙宝宝测试添加创建部门",
  "name_en": "RDGZ",
  "parentid": 1,
  "order": 300,
  "id": 20
}

• 请求体参数说明：
  name：必填，部门名称。同一个层级的部门名称不能重复。长度限制为 1~32 个字符，字符不能包括:?”<>｜
  name_en：英文名称。同一个层级的部门名称不能重复。需要在管理后台开启多语言支持才能生效。长度限制为 1~32 个字符，字符不能包括:?”<>｜
  parentid：必填，父部门 id，32 位整型
  order：在父部门中的次序值。order 值大的排序靠前。有效的值范围是[0, 2^32)
  id：部门 id，32 位整型，指定时必须大于 1。若不填该参数，将自动生成 id

• 返回参数：

{
    
   "errcode": 0,
   "errmsg": "created",
   "id": 2 //创建部门的id
}

• 请求结果

• 注意：
  a.部门的最大层级为 15 层；部门总数不能超过 3 万个；每个部门下的节点不能超过 3 万个。

2.更新部门

• 请求地址：https://qyapi.weixin.qq.com/cgi-bin/department/update?access_token=ACCESS_TOKEN

• 请求方式：POST

• 请求体：
  与创建部门相同，可以在里面对部门层级，名字等进行修改

• 请求体参数说明：与创建部门相同

3.删除部门

• 请求地址：https://qyapi.weixin.qq.com/cgi-bin/department/delete?access_token=ACCESS_TOKEN&id=ID

• 请求方式：GET

• 参数说明：
  id：部门的 id

• 返回参数

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

• 注意：
  a.不能删除根部门；不能删除含有子部门、成员的部门
  b.第三方仅通讯录应用可以调用。

4.获取部门列表

• 请求地址：https://qyapi.weixin.qq.com/cgi-bin/department/list?access_token=ACCESS_TOKEN&id=ID

• 请求方式：GET

• 参数说明：
  id：部门的 id,如果不填，默认获取全量组织架构

• 返回结果

{
    
   "errcode": 0,
   "errmsg": "ok",
   "department": [
       {
    
           "id": 2,
           "name": "广州研发中心",
           "name_en": "RDGZ",
           "parentid": 1,
           "order": 10
       }
   ]
}

• 返回结果参数说明：与创建部门参数相仿