通讯录API

• 简介
  • 使用须知
  • 名词解释
  • 参数解释
• 部门API
  • 查询部门
  • 创建部门
  • 修改部门
  • 删除部门
• 成员API
  • 查询部门成员
  • 查询成员
  • 查询成员（根据userId查询）
  • 添加成员
  • 修改成员
  • 删除成员
  • 批量删除成员
• 批量管理API
  • 全量导入部门
  • 增量导入用户
• 角色API
  • 查询角色组成员
  • 查询角色组
  • 查询所有角色组
  • 创建角色组
  • 修改角色组
  • 删除角色组
• 外部联系人API
  • 查询所有外部分组
  • 查询外部分组成员
  • 查询外部成员
  • 查询外部分组

简介

本章介绍关于通过webapi方式来操作通讯录，对部门、角色、成员与外部联系人等属性进行功能操作。

• 功能操作：查询、添加、修改、删除。

注意事项：

1. 每个通讯录都是一棵部门树形结构，且根部门的部门编号都是1。
2. 普通模式的企业通讯录，支持全部功能操作接口。
3. 集成模式的企业通讯录，仅支持查询操作接口。

• 通讯录模式查阅团队和通讯录了解。

使用须知

开发前，请仔细阅读开发指南，获得API所需统一访问地址与认证请求头。

• POST请求头

{"Authorization": "Bearer YOUR_APIKEY"}

• YOUR_APIKEY请阅读开发指南了解。

名词解释

名称	说明
dept_no	部门编号
role_no	角色组编号
uniqueid	企业内用户ID

• 部门编号可在前端查看，也可通过查询全部部门信息了解。
• 角色组编号通过查询全部角色组信息了解。

参数解释

• 部门实体结构（department）

属性	类型	说明
dept_no	number	部门编号，企业内唯一
name	string	部门名称
parent_no	number	部门的父级部门编号

• 用户实体结构（user）

属性	类型	说明
_id	string	用户ID，全局唯一
username	string	用户名
name	string	昵称
category	number	用户状态(-1表示被邀请的人尚未同意其邀请, 同意后自动变为2, 0表示团队创建者, 2表示普通成员)
uniqueid	string	企业内用户ID
remark	string	备注
title	string	职称
departments	number[]	成员所在部门编号列表

部门API

查询部门

POST /api/v2/department/{dept_no}/department_list

根据部门编号查询（递归）该部门下的所有子部门信息。

• 请求地址：

POST /api/v2/department/1/department_list

根部门编号固定为数字1，根据根部门编号查询，可获取通讯录全部部门信息。

• 请求参数：

{
    "has_child": true
}

名称	必填	类型	说明
has_child	否	Boolean	{"has_child":true}查询该部门下所有子部门信息。 {"has_child":false}或空参数{}只查询该部门信息。

• 响应内容：

{
    "departments": [{
        "dept_no": 1,
        "name": "默认部门",
        "parent_no": 0
    },
    {
        "dept_no": 2,
        "name": "部门A",
        "parent_no": 1
    },
    {
        "dept_no": 3,
        "name": "部门B",
        "parent_no": 1
    }]
}

返回该部门下所有子部门列表。

参数	类型	说明
departments	array	指定部门下的子部门列表
departments.dept_no	number	部门编号
departments.name	string	部门名称
departments.parent_no	number	父部门编号

创建部门

POST /api/v2/department/create

• 请求参数：

{
    "name":"部门名称",
    "parent_no":1,
    "dept_no":2
}

参数	必填	类型	说明
name	是	string	部门名称
parent_no	否	number	父部门编号，不传默认为根部门编号1
dept_no	否	number	部门编号，不传自动生成（上限 100000 ）

• 响应内容：

{
    "department": {
        "dept_no": 2,
        "parent_no": 1,
        "name": "部门名称"
    }
}

返回创建的部门信息。

参数	类型	说明
department	json	包含部门信息的子集
department.dept_no	number	部门编号
department.parent_no	number	父部门编号
department.name	string	部门名称

修改部门

POST /api/v2/department/{dept_no}/update

根据部门编号修改部门名称。（该接口只能修改部门名称）

• 请求参数：

{
    "name": "部门新名称"
}

参数	必填	类型	说明
name	是	string	部门名称

• 响应内容：

{
    "department": {
        "dept_no": 2,
        "parent_no": 1,
        "name": "部门新名称"
    }
}

返回修改后的部门信息。

参数	类型	说明
department	json	包含部门信息的子集
department.dept_no	number	部门编号
department.parent_no	number	父部门编号
department.name	string	部门名称

删除部门

POST /api/v2/department/{dept_no}/delete

根据部门编号删除部门。

• 请求参数：

{}

• 响应内容：

{
    "status": "success"
}

返回删除结果。

参数	类型	说明
status	string	返回请求结果，success为成功。

成员API

查询部门成员

POST /api/v2/department/{dept_no}/member_list

根据部门编号查询（递归）该部门下所有成员信息。

• 请求参数：

{
    "has_child": true
}

参数	必填	类型	说明
has_child	否	Boolean	是否递归获取所有成员。 默认为false，即只获取当前部门下的成员，而不获取其子部门的成员。

• 响应内容：

{
    "users": [{
        "_id": "519311e456fcb477cbf840d0",
        "name": "昵称壹号",
        "username": "用户账号名",
        "category": "0",
        "uniqueid": "企业内用户ID",
        "remark": "备注",
        "title": "职称",
        "departments": [1, 2],
        "roles": [1, 2]
    },
    {
        "_id": "527d12785b907ace343dcbd0",
        "name": "昵称贰号",
        "username": "用户账号名",
        "category": "2",
        "uniqueid": "企业内用户ID",
        "remark": "备注",
        "title": "职称",
        "departments": [],
        "roles": []
    }]
}

返回部门下所有成员列表。

参数	类型	说明
users	array	包含成员信息的数组
users._id	string	用户userId
users.name	string	用户昵称
users.username	string	用户账号名
users.category	number	用户状态 -1：表示被邀请的人尚未同意其邀请，同意后自动变为2 0：表示团队创建者 2：表示普通成员
users.uniqueid	string	企业内用户ID
users.remark	string	备注
users.title	string	职称
users.departments	number[]	用户所属的部门ID列表
users.roles	number[]	用户所属的角色组ID列表

查询成员

POST /api/v3/user/{uniqueid}/user_retrieve

根据企业内用户ID查询该成员信息。

新旧差异：新版查询返回成员信息中，增加roles成员所在角色组编号列表。

• 请求参数：

{}

• 响应内容：

{
    "user": {
        "_id": "527d12785b907ace343dcbd0",
        "name": "瑾瑜沐珄",
        "username": "用户账号名",
        "category": "2",
        "uniqueid": "JinYuMuSheng",
        "remark": "备注",
        "title": "职称",
        "departments": [1, 2, 3],
        "roles": [1, 2]
    }
}

返回查询到的成员信息。

参数	类型	说明
user	json	包含成员信息的子集
user._id	string	用户userId
user.name	string	用户昵称
user.username	string	用户账号名
user.category	number	用户状态 -1：表示被邀请的人尚未同意其邀请，同意后自动变为2 0：表示团队创建者 2：表示普通成员
user.uniqueid	string	企业内用户ID
user.remark	string	备注
user.title	string	职称
user.departments	number[]	用户所属的部门ID列表
user.roles	number[]	用户所属的角色组ID列表

查询成员（根据userId查询）

POST /api/v3/user/{_id}/user_info

根据用户userId查询该成员信息。

• 请求参数：

{}

• 响应内容：

{
    "user": {
        "_id": "527d12785b907ace343dcbd0",
        "name": "瑾瑜沐珄",
        "username": "用户账号名",
        "category": "2",
        "uniqueid": "JinYuMuSheng",
        "remark": "备注",
        "title": "职称",
        "departments": [1, 2, 3],
        "roles": [1, 2]
    }
}

返回查询到的成员信息。

参数	类型	说明
user	json	包含成员信息的子集
user._id	string	用户userId
user.name	string	用户昵称
user.username	string	用户账号名
user.category	number	用户状态 -1：表示被邀请的人尚未同意其邀请，同意后自动变为2 0：表示团队创建者 2：表示普通成员
user.uniqueid	string	企业内用户ID
user.remark	string	备注
user.title	string	职称
user.departments	number[]	用户所属的部门ID列表
user.roles	number[]	用户所属的角色组ID列表

添加成员

POST /api/v2/user/create

在指定部门下添加一位成员，该成员用户自动激活（可直接通过单点登录进行访问，并且会占用1个用户数），但是没有手机、邮箱和密码等个人注册信息。

• 请求参数：

{
    "uniqueid": "WangXiaoMei",
    "name": "王小美",
    "departments":[1],
    "title":"职称",
    "remark":"备注"
}

参数	必填	类型	说明
uniqueid	否	string	企业内用户ID，不传则与昵称一致，中文昵称则会转为拼音
name	是	string	昵称
departments	否	number[]	用户所属部门ID列表，不传则在默认根部门。
title	否	string	职称
remark	否	string	备注

• 响应内容：

{
    "user": {
        "_id": "5af1d4d266362ef16d5214da",
        "name": "王小美",
        "username": "user_vpgvnh29118",
        "category": "2",
        "uniqueid": "WangXiaoMei",
        "remark": "备注",
        "title": "职称",
        "departments": [1],
        "roles": []
    }
}

返回新添加的成员信息。

参数	类型	说明
user	json	包含成员信息的子集
user._id	string	用户userId
user.name	string	用户昵称
user.username	string	用户账号名
user.category	number	用户状态 -1：表示被邀请的人尚未同意其邀请，同意后自动变为2 0：表示团队创建者 2：表示普通成员
user.uniqueid	string	企业内用户ID
user.remark	string	备注
user.title	string	职称
user.departments	number[]	用户所属的部门ID列表
user.roles	number[]	用户所属的角色组ID列表

修改成员

POST /api/v2/user/{uniqueid}/update

根据企业内用户ID修改该成员信息，比如昵称、备注、职称、归属部门。

注意：企业内用户ID不允许修改。

• 请求参数：

{
    "name": "王小美",
    "remark": "12月2日加入",
    "title": "月海亭秘书",
    "departments": [1]
}

参数	必填	类型	说明
name	否	string	昵称
remark	否	string	备注
title	否	string	备注
departments	否	number[]	用户所属部门列表

• 响应内容：

{
    "user": {
        "_id": "5af1d4d266362ef16d5214da",
        "name": "王小美",
        "username": "user_vpgvnh29118",
        "category": "2",
        "uniqueid": "WangXiaoMei",
        "remark": "备注",
        "title": "职称",
        "departments": [1],
        "roles": []
    }
}

返回修改后的成员信息。

参数	类型	说明
user	json	包含成员信息的子集
user._id	string	用户userId
user.name	string	用户昵称
user.username	string	用户账号名
user.category	number	用户状态 -1：表示被邀请的人尚未同意其邀请，同意后自动变为2 0：表示团队创建者 2：表示普通成员
user.uniqueid	string	企业内用户ID
user.remark	string	备注
user.title	string	职称
user.departments	number[]	用户所属的部门ID列表
user.roles	number[]	用户所属的角色组ID列表

删除成员

POST /api/v2/user/{uniqueid}/delete

根据企业内用户ID删除该成员信息。

从通讯录中彻底删除指定企业内用户ID的用户，并非离职状态。

• 请求参数：

{}

• 响应内容：

{
    "status": "success"
}

返回删除结果。

参数	类型	说明
status	string	返回请求结果，success为成功。

批量删除成员

POST /api/v2/user/batch_delete

• 请求参数：

{
    "uniqueids": [
        "企业内用户ID1",
        "企业内用户ID2",
        "企业内用户ID3"
    ]
}

参数	必填	类型	说明
usernames	是	string[]	企业内用户ID列表

• 响应内容：

{
    "status": "success"
}

返回删除结果。

参数	类型	说明
status	string	返回请求结果，success为成功。

批量管理API

功能特点：以下2个接口的是用于批量导入新增与覆盖更新使用。

全量导入部门

POST /api/v2/department/import

本接口以dept_no（部门编号）为主键，全量覆盖企业内的通讯录部门树。

• 注意事项：

1. 部门编号为数字类型且唯一。
2. 除了根部门以外所有部门的父部门必须存在。如果新导入列表中不存在根部门, 则会自动插入根部门, 且部门名称为企业名称。
3. 同级部门名称不能有重复。
4. 部门层级不能超过16级。
5. 如果导入数据存在，且现有企业通讯录中也存在，则更新该部门的信息。
6. 如果导入数据存在，而现有企业通讯录中不存在，则新建该部门。
7. 如果导入数据不存在，但现有企业通讯录中存在，则继续判断该部门下是否存在子部门和成员，如果都没有则自动删除该部门，否则继续保留。
8. 该接口允许导入的部门数上限为1000。
9. 该接口调用执行期间，将无法同时调用其他对通讯录的修改、删除、新增接口。

• 请求参数：

{
    "departments": [{
        "dept_no": 2,
        "name": "部门名称1",
        "parent_no": 1
    },
    {
        "dept_no": 3,
        "name": "部门名称2",
        "parent_no": 2
    }]
}

参数	必填	类型	说明
departments	是	array	部门列表
departments.name	是	string	部门名称
departments.dept_no	是	number	部门编号（上限 1000）

• 响应内容：

{
    "status": "success"
}

返回导入结果。

参数	类型	说明
status	string	返回请求结果，success为成功。

增量导入用户

POST /api/v2/user/import

本接口以企业内的username（用户账号名）为主键，更新创建企业成员。

• 注意事项：

1. 企业内唯一ID在企业内唯一，仅支持字母,数字,下划线32位内。
2. 用户昵称最长为26个字符。
3. 所有用户必须在部门下，如果导入用户不存在部门，则会移动到根部门下。
4. 通过该接口导入的用户会自动激活，且没有邮箱、密码、手机号等信息，可以配合单点登录功能实现企业用户登录。
5. 如果导入数据存在，但是现有企业通讯录中不存在该用户，则新建成员。
6. 如果导入数据存在，且现有企业通讯录中存在该用户，则更新成员信息。
7. 该接口不会执行删除成员操作。
8. 该接口每次调用允许导入的用户数为2000。
9. 该接口调用执行期间，将无法同时调用其他对通讯录的修改、删除、新增接口。

• 请求参数：

{
    "users": [{
        "uniqueid": "XiaoMing",
        "name": "小明",
        "departments": [1, 2]
    },
    {
        "uniqueid": "XiaoHua",
        "name": "小花",
        "departments": [1]
    }]
}

参数	必填	类型	说明
users	是	array	用户列表
users.uniqueid	是	string	用户编号
users.name	是	string	昵称
users.departments	是	number[]	所在部门编号列表

• 响应内容：

{
    "status": "success"
}

返回导入结果。

参数	类型	说明
status	string	返回请求结果，success为成功。

角色API

查询角色组成员

POST /api/v3/role/{role_no}/member_list

根据角色组编号查询该角色组内所有成员信息。

• 请求参数：

{}

• 响应内容：

{
    "users": [{
        "_id": "519311e456fcb477cbf840d0",
        "name": "创建管理员",
        "username": "user",
        "category": "0",
        "uniqueid": "ChuangJianGuanLiYuan",
        "remark": "",
        "title": "",
        "departments": [1, 2],
        "roles": [1]
    },
    {
        "_id": "5af1d4d266362ef16d5214da",
        "name": "王小美",
        "username": "user_vpgvnh29118",
        "category": "2",
        "uniqueid": "WangXiaoMei",
        "remark": "备注",
        "title": "职称",
        "departments": [1],
        "roles": [1]
    },
    {
        "_id": "52df6abbc3072b3db32b81a6",
        "name": "钟离",
        "username": "user_eqjtyt79726",
        "category": "2",
        "uniqueid": "ZhongLi",
        "remark": "备注",
        "title": "职称",
        "departments": [1],
        "roles": [1]
    }]
}

返回该角色组内所有成员列表。

参数	类型	说明
users	array	包含成员信息的数组
users._id	string	用户userId
users.name	string	用户昵称
users.username	string	用户账号名
users.category	number	用户状态 -1：表示被邀请的人尚未同意其邀请，同意后自动变为2 0：表示团队创建者 2：表示普通成员
users.uniqueid	string	企业内用户ID
users.remark	string	备注
users.title	string	职称
users.departments	number[]	用户所属的部门ID列表
users.roles	number[]	用户所属的角色组ID列表

查询角色组

POST /api/v3/role/{role_no}/info

根据角色组编号查询该角色组信息。

• 请求参数：

{}

• 响应内容：

{
    "role": {
        "role_no": 1,
        "name": "角色1"
    }
}

返回角色组信息。

参数	类型	说明
role	json	包含角色组信息的子集
role.role_no	number	角色组编号
role.name	string	角色组名称

查询所有角色组

POST /api/v3/role/role_list

查询所有角色组信息。

• 请求参数：

{}

• 响应内容：

{
    "roles": [{
        "role_no": 1,
        "name": "角色1"
    },
    {
        "role_no": 2,
        "name": "角色2"
    },
    {
        "role_no": 3,
        "name": "角色3"
    }]
}

返回所有角色组信息。

参数	类型	说明
roles	array	包含角色组信息的子集
roles.role_no	number	角色组编号
roles.name	string	角色组名称

创建角色组

POST /api/v3/role/create

• 请求参数：

{
    "role_no": 1,
    "name": "角色1"
}

参数	必填	类型	说明
role_no	是	number	角色组编号
name	是	string	角色组名称

• 响应内容：

{
    "role": {
        "role_no": 1,
        "name": "角色1"
    }
}

返回创建的角色组信息。

参数	类型	说明
role	json	包含角色组信息的子集
role.role_no	number	角色组编号
role.name	string	角色组名称

修改角色组

POST /api/v3/role/{role_no}/update

根据角色组编号修改角色组名称。（该接口只能修改角色组名称）

• 请求参数：

{
    "name": "新角色名"
}

参数	必填	类型	说明
name	是	string	角色组名称

• 响应内容：

{
    "role": {
        "role_no": 1,
        "name": "新角色名"
    }
}

返回创建的角色组信息。

参数	类型	说明
role	json	包含角色组信息的子集
role.role_no	number	角色组编号
role.name	string	角色组名称

删除角色组

POST /api/v3/role/{role_no}/delete

根据角色组编号删除角色组。

• 请求参数：

{}

• 响应内容：

{
    "status": "success"
}

返回删除结果。

参数	类型	说明
status	string	返回请求结果，success为成功。

外部联系人API

查询所有外部分组

POST /api/v3/outsider/outsider_list

查询所有外部联系人的分组信息。

• 请求参数：

{}

• 响应内容：

{
    "outsiders": [{
        "group_id": "1f7021f7877b588d8089c5f5",
        "name": "默认分组"
    },
    {
        "group_id": "0fe24147c55a9ebef3717eb7",
        "name": "新建分组1"
    }]
}

返回所有外部联系人分组信息。

参数	类型	说明
outsiders	array	包含成员信息的数组
outsiders.group_id	number	分组ID
outsiders.name	string	分组名称

查询外部分组成员

POST /api/v3/outsider/{group_id}/member_list

根据分组ID查询该外部联系人分组内所有成员信息。

• 请求参数：

{}

• 响应内容：

{
    "users": [{
        "_id": "519311e456fcb477cbf840d0",
        "group_id": "1f7021f7877b588d8089c5f5",
        "uniqueid": "企业内用户ID",
        "name": "昵称壹号",
        "remark": "备注"
    },
    {
        "_id": "54fd6049d90c842ac53ab95d",
        "group_id": "1f7021f7877b588d8089c5f5",
        "uniqueid": "企业内用户ID",
        "name": "昵称贰号",
        "remark": "备注",
    }]
}

返回外部分组内所有成员列表。

参数	类型	说明
users	array	包含成员信息的数组
users._id	string	用户userId
users.group_id	string	外部分组ID
users.uniqueid	string	企业内用户ID
users.name	string	用户昵称
users.remark	string	备注

查询外部成员

POST /api/v3/outsider/{userId}/user_info

根据userId查询外部联系人的成员信息。

• 请求参数：

{}

• 响应内容：

{
    "user": {
        "_id": "519311e456fcb477cbf840d0",
        "group_id": "1f7021f7877b588d8089c5f5",
        "uniqueid": "企业内用户ID",
        "name": "昵称壹号",
        "remark": "备注"
    }
}

返回外部分组内所有成员列表。

参数	类型	说明
user	json	包含外部成员信息的子集
user._id	string	用户userId
user.group_id	string	外部分组ID
user.uniqueid	string	企业内用户ID
user.name	string	用户昵称
user.remark	string	备注

查询外部分组

POST /api/v3/outsider/{group_id}/info

根据分组ID查询外部联系人的分组信息。

• 请求参数：

{}

• 响应内容：

{
    "outsider": {
        "group_id": "1f7021f7877b588d8089c5f5",
        "name": "默认分组"
    }
}

返回外部联系人分组信息。

参数	类型	说明
outsiders	json	包含外部分组信息的子集
outsiders.group_id	number	分组ID
outsiders.name	string	分组名称