通讯录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"
}