通讯录接口 - 简道云

通讯录接口

1. 开发准备

开发前，请仔细阅读开发指南。

2. 实体结构

2.1 部门实体结构（department）

属性	类型	含义	备注
dept_no	Number	部门编号，企业内唯一	不同企业之间可能存在重复
name	String	部门名称
parent_no	Number	父部门编号	在企业互联接口中(外部部门)不存在
type	Number	部门类型	0: 常规部 2: 企业互联外部部门
status	Number	部门状态	1: 使用中的部门 -1: 集成模式下同步后删除的部门
integrate_id	String	集成模式同步部门关联 ID	仅在集成模式下返回，且在企业互联接口(外部部门)不返回
seq	number	部门排序	部门在父部门内的序号，从小到大排列

2.2 成员实体结构（user）

属性	类型	含义	备注
username	String	成员的编号，企业内唯一	不同企业之间可能存在重复
name	String	昵称
departments	Number[]	成员所在部门编号列表
type	Number	成员类型	0: 常规成员 2: 企业互联外部对接人
status	Number	成员状态	0: 未确认的成员 1: 已加入
integrate_id	String	集成模式同步成员关联 ID	仅在集成模式下返回，且在企业互联接口(外部对接人)不返回

2.3 角色实体结构 (role)

属性	类型	含义	备注
role_no	Number	角色编号，企业内唯一	不同企业之间可能存在重复
group_no	Number	角色组编号，企业内唯一	不同企业之间可能存在重复
name	String	角色名称
type	Number	角色类型	0: 常规角色 2: 企业互联外部角色
status	Number	角色状态	1:使用中
integrate_id	String	集成模式同步成员关联 ID	仅在集成模式下返回，且在企业互联接口(外部对接人)不返回

2.4 角色组实体结构 (role_group)

属性	类型	含义	备注
group_no	Number	角色组编号, 企业内唯一	不同企业之间可能存在重复
name	String	角色组名称
type	Number	角色组类型	0: 常规角色组 2: 企业互联外部角色组
status	Number	角色组状态	1: 使用中
integrate_id	String	集成模式同步角色组关联 ID	仅在集成模式下(飞书除外)，同步的角色组返回

3. 版本说明

当前接口不同版本的主要区别:

接口类型	v1	v2	v4	v5
成员	使用 _id 作为 id	使用 username 作为 id	返回值新增字段 type、status、integrate_id	在 v4 的基础上，接口请求频率提升。
部门	使用 _id 作为id	使用 dept_no 作为 id	返回值新增字段 type、status、integrate_id	在 v4 的基础上，接口请求频率提升。
角色	无	角色使用 role_no 角色组使用 group_no 包含 integrate_id、type 字段	返回值新增字段 status	在 v4 的基础上，接口请求频率提升。
企业互联	无	无	成员使用 username 部门使用 dept_no 包含 type、status 字段	在 v4 的基础上，接口请求频率提升。

4. 注意事项

1）每个通讯录都是一棵部门树，且根部门的部门编号都是 1。

2）对公共模式模式和集成模式支持的程度不同，会在每个接口上备注。

3）由于企业微信/钉钉与简道云通讯录的当前部门规则一致，因此 integrate_id 与 dept_no 的值暂时保持一致；而飞书平台的部门 ID 是由字符串组成，因此与简道云通讯录的部门 dept_no 不一致。integrate_id 与 dept_no 的含义不同，后续更新中不保证使用相同的值，使用时须加以区分。

本章内容：