通讯录API
阅读人数：
458
注意事项:
每个通讯录都是一棵部门树，且根部门的部门编号都是1；
普通模式的企业以下接口全部支持；
集成模式的企业仅支持获取部门列表、获取部门成员和获取成员信息接口；
部门实体结构（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 - （递归）获取部门列表
能够（递归）获取指定部门id的所有子部门。
请求参数：
| 参数 | 必需 | 类型 | 说明 |
| has_child | Boolean | 是否递归获取所有子部门。默认为false，即只获取一级子部门 |
请求数据样例：
递归获取当前企业的根部门下所有部门列表。 注：数字1为根部门编号。
POST /api/v2/department/1/department_list
{
"has_child": true
}
响应内容：
| 参数 | 类型 | 含义 |
| departments | array | 当前指定部门下的子部门列表 |
| departments[].dept_no | number | 部门编号 |
| departments[].name | string | 部门名称 |
| departments[].parent_no | number | 父部门编号 |
响应数据样例：
{
"departments": [
{
"dept_no": 3,
"name": "webapi添加",
"parent_no": 1 //表示父部门编号
}, {
"dept_no": 33,
"name": "开发",
"parent_no": 3
}
]
}
POST /api/v2/department/create - 创建部门
请求参数：
| 参数 | 必需 | 类型 | 说明 |
| name | 是 | string | 部门名称 |
| parent_no | number | 父部门编号，不传默认为根部门 | |
| dept_no | number | 部门编号，不传自动生成（上限 100000 ） |
请求数据样例：
{
"name": "研发部门",
"parent_no": 1,
"dept_no": 2
}
响应内容：
| 参数 | 类型 | 含义 |
| department | json | 创建的部门信息 |
| department.dept_no | number | 部门编号 |
| department.name | string | 部门名称 |
| department.parent_no | number | 父部门编号 |
响应数据样例：
{
"department": {
"dept_no": 2,
"name": "研发部门",
"parent_no": 1
}
}
POST /api/v2/department/{ dept_no }/update - 修改部门
请求参数：
| 参数 | 必需 | 类型 | 说明 |
| name | 是 | string | 部门名称 |
请求数据样例：
{
"name": "测试部门"
}
响应内容：
| 参数 | 类型 | 含义 |
| department | json | 创建的部门信息 |
| department.dept_no | number | 部门编号 |
| department.name | string | 部门名称 |
| department.parent_no | number | 父部门编号 |
响应数据样例：
{
"department": {
"dept_no": 3,
"name": "测试部门",
"parent_no": 2
}
}
POST /api/v2/department/{ dept_no }/delete - 删除部门
请求参数：
无
响应内容：
| 参数 | 类型 | 说明 |
| status | string | 返回请求结果 |
响应数据样例：
{
"status": "success"
}
成员API
POST /api/v2/department/{ dept_no }/member_list -（递归）获取部门成员
能够（递归）获取指定部门编号下的所有成员。
请求参数：
| 参数 | 必需 | 类型 | 说明 |
| has_child | Boolean | 是否递归获取所有成员。默认为false，即只获取当前部门下的成员，而不获取其子部门的成员 |
请求数据样例：
递归获取当前企业下所有成员列表
{
"has_child": true
}
响应内容：
| 参数 | 含义 |
| users | 当前指定部门下的成员列表 |
单个成员的返回数据结构：
| 参数 | 含义 |
| _id | 用户ID |
| name | 昵称 |
| username | 用户名 |
| category | 用户状态(-1表示被邀请的人尚未同意其邀请, 同意后自动变为2, 0表示团队创建者, 2表示普通成员) |
| uniqueid | 企业内用户ID |
| remark | 备注 |
| title | 职称 |
| departments | 用户所属的部门ID列表 |
响应数据样例：
{
"users": [
{
"_id": "575ffc5e885898ce0d2afe43",
"name": "xiaoyun",
"username": "xiaoyun",
"category": "2",
"uniqueid": "XiaoYun",
"remark": "",
"title": "",
"departments": [
1,
3
]
},
{
"_id": "55cb7d57f7a190e382857119",
"name": "小宝",
"username": "xiaobao",
"category": "2",
"uniqueid": "110911062",
"remark": "领导",
"title": "教授",
"departments": [
1
]
},
{
"_id": "5ae9b2e763476bd11c13c9ba",
"name": "测试02",
"username": "ceshi",
"category": "2",
"uniqueid": "100005",
"remark": "测试号",
"title": "",
"departments": [
2
]
}
]
}
POST /api/v2/user/{ uniqueid }/user_retrieve - 获取成员信息
请求参数：无
响应内容：
| 参数 | 含义 |
| user | 成员信息，同单个成员的返回数据结构 |
响应数据样例：
{
"user": {
"_id": "575ffc5e885898ce0d2afe43",
"name": "xiaoyun",
"username": "xiaoyun",
"category": "2",
"uniqueid": "XiaoYun",
"remark": "",
"title": "",
"departments": [
1,
3
]
}
}
POST /api/v2/user/create - 添加成员
在指定部门下添加一位成员，该成员用户自动激活（可直接通过单点登录进行访问，并且会占用1个用户数），但是没有手机、邮箱和密码等个人注册信息。
请求参数
| 参数 | 必需 | 类型 | 说明 |
| name | 是 | string | 昵称 |
| departments | numer[] | 用户所属部门列表 | |
| uniqueid | string | 成员编号 | |
| remark | string | 备注 | |
| title | string | 职称 |
请求数据样例：
{
"uniqueid": "GaoCenXing3",
"name": "小高3",
"remark":"6月1",
"title":"会员",
"departments": [
1
]
}
响应内容：
| 参数 | 类型 | 说明 |
| usre | json | 新添加的该成员信息，同单个成员的返回数据结构 |
响应数据样例：
{
"user": {
"_id": "575ffc5e885898ce0d2afe55",
"name": "小高3",
"username": "bby_8zzhth90591",
"category": "2",
"uniqueid": "GaoCenXing3",
"remark": "6月1",
"title": "会员",
"departments": [
1
]
}
}
POST /api/v2/user/{ uniqueid }/update - 修改成员
修改指定成员的信息，比如部门、昵称、备注、职称。
注意：企业内用户ID不允许修改。
请求参数
| 参数 | 必需 | 类型 | 说明 |
| name | string | 昵称 | |
| departments | numer[] | 用户所属部门列表 | |
| remark | string | 备注 | |
| title | string | 职称 |
请求数据样例：
{
"name": "Gcx",
"remark":"5月30号加入",
"title":"荣誉会长",
"departments": [
7
]
}
响应内容：
| 参数 | 类型 | 说明 |
| usre | json | 修改后的该成员信息，同单个成员的返回数据结构 |
响应数据样例：
{
"user": {
"_id": "51616fa9c2668f496283094c",
"name": "Gcx",
"username": "bby_qvsusl53003",
"category": "2",
"uniqueid": "GaoCenXing",
"remark": "5月30号加入",
"title": "荣誉会长",
"departments": [
7
]
}
}
POST /api/v2/user/{ uniqueid }/delete - 删除成员
从通讯录中删除指定企业内用户ID的用户。
请求参数
无
响应内容：
| 参数 | 类型 | 说明 |
| status | string | 返回请求结果 |
响应数据样例：
{
"status": "success"
}
POST /api/v2/user/batch_delete - 批量删除成员
请求参数
| 参数 | 必需 | 类型 | 说明 | usernames | 是 | array | 用户编号列表 |
请求数据样例：
{
"uniqueids": [
"CeShiDaoRu",
"CC"
]
}
响应内容：
| 参数 | 类型 | 说明 |
| status | string | 返回请求结果 |
响应数据样例：
{
"status": "success"
}
批量管理API
POST /api/v2/department/import - 全量导入部门
本接口以dept_no（部门编号）为主键，全量覆盖企业内的通讯录部门树。
注意事项：
- 部门编号为数字类型且唯一。
- 除了根部门以外所有部门的父部门必须存在。如果新导入列表中不存在根部门, 则会自动插入根部门, 且部门名称为企业名称。
- 同级部门名称不能有重复。
- 部门层级不能超过16级。
- 如果导入数据存在，且现有企业通讯录中也存在，则更新该部门的信息。
- 如果导入数据存在，而现有企业通讯录中不存在，则新建该部门。
- 如果导入数据不存在，但现有企业通讯录中存在，则继续判断该部门下是否存在子部门和成员，如果都没有则自动删除该部门，否则继续保留。
- 该接口允许导入的部门数上限为1000。
- 该接口调用执行期间，将无法同时调用其他对通讯录的修改、删除、新增接口。
请求参数
| 参数 | 必需 | 类型 | 说明 |
| departments | 是 | array | 部门列表 |
| departments[].dept_no | 是 | number | 部门编号（上限 1000） |
| departments[].name | 是 | string | 部门名称 |
| departments[].parent_no | number | 父部门编号，不传默认为根部门下 |
请求数据样例：
{
"departments": [
{
"dept_no": 3,
"name": "部门名称1",
"parent_no": 2
},
{
"dept_no": 2,
"name": "部门名称2",
"parent_no": 1
}
]
}
响应内容：
| 参数 | 类型 | 说明 |
| status | string | 返回请求结果 |
响应数据样例：
{
"status": "success"
}
POST /api/v2/user/import - 增量导入用户
本接口以企业内的username（用户编号）为主键，更新创建企业成员。
注意事项：
- 企业内唯一ID在企业内唯一，仅支持字母,数字,下划线32位内。
- 用户昵称最长为26个字符。
- 所有用户必须在部门下，如果导入用户不存在部门，则会移动到根部门下。
- 通过该接口导入的用户会自动激活，且没有邮箱、密码、手机号等信息，可以配合单点登录功能实现企业用户登录。
- 如果导入数据存在，但是现有企业通讯录中不存在该用户，则新建成员。
- 如果导入数据存在，且现有企业通讯录中存在该用户，则更新成员信息。
- 该接口不会执行删除成员操作。
- 该接口每次调用允许导入的用户数为2000。
- 该接口调用执行期间，将无法同时调用其他对通讯录的修改、删除、新增接口。
请求参数
| 参数 | 必需 | 类型 | 说明 |
| users | 是 | json[] | 用户列表 |
| users[].uniqueid | 是 | string | 用户编号 |
| users[].name | 是 | string | 昵称 |
| users[].departments | 是 | number[] | 所在部门编号列表 |
请求数据样例：
{
"users": [
{
"uniqueid": "GaoCenXing3",
"name": "小高吗",
"departments": [
1,
2
]
},
{
"uniqueid": "xiaoyun",
"name": "小云",
"departments": [
70
]
}
]
}
响应内容：
| 参数 | 类型 | 说明 |
| status | string | 返回请求结果 |
响应数据样例：
{
"status": "success"
}