feishu-contact

飞书组织架构与 ID 转换

通过 Contact v3 API 实现成员搜索、部门管理和 ID 转换。

---

API 基础

Base URL：https://open.feishu.cn/open-apis/contact/v3
认证：Authorization: Bearer {tenant_access_token}

认证与 Token 获取

从 feishu_skills 根目录执行共享脚本：

TOKEN="$(./scripts/get_feishu_token.sh)"

请求头统一使用 Authorization: Bearer ${TOKEN}。

如果业务接口返回 token 无效、过期或 401，强制刷新后仅重试一次原请求：

TOKEN="$(./scripts/get_feishu_token.sh --force-refresh)"

环境变量：

• FEISHU_APP_ID
• FEISHU_APP_SECRET

本地缓存：./.feishu_token_cache.json（未过期直接复用，默认提前 5 分钟刷新）

---

成员查询

API	端点	说明
搜索成员	GET /users/batch_get_id	通过邮箱/手机号获取 OpenID
获取职务	GET /job_titles/{id}	需在管理后台预先维护

---

部门管理

API	端点	方法	请求体示例	说明
获取部门	/departments/{department_id}	GET	-	查询单个部门详情
获取部门列表	/departments	GET	-	支持 parent_department_id 参数
获取父部门路径	/departments/{department_id}/parent	GET	-	获取部门层级路径
创建部门	/departments	POST	{"name":"新部门","parent_department_id":"0"}	需管理员权限
更新部门	/departments/{department_id}	PUT	{"name":"更新后的名称"}	修改部门信息
删除部门	/departments/{department_id}	DELETE	-	删除空部门
入职成员	/users	POST	{"name":"张三","mobile":"138...","department_ids":["od_xxx"]}	创建用户
更新用户	/users/{user_id}	PUT	{"name":"新名字"}	修改用户信息
删除用户	/users/{user_id}	DELETE	-	移除用户
获取用户列表	/users	GET	-	支持 department_id 过滤

⚠️ 创建部门和入职成员需最高权限，建议在预发环境测试。

---

用户组管理

API	端点	方法	请求体示例	说明
获取用户组列表	/groups	GET	-	查询所有用户组
获取用户组	/groups/{group_id}	GET	-	查询单个用户组
创建用户组	/groups	POST	{"name":"项目组","description":"描述"}	创建新用户组
更新用户组	/groups/{group_id}	PUT	{"name":"新名称"}	修改用户组
删除用户组	/groups/{group_id}	DELETE	-	删除用户组
获取组成员	/groups/{group_id}/members	GET	-	查询组成员列表
添加组成员	/groups/{group_id}/members	POST	{"member_id":"ou_xxx","member_type":"user"}	将用户添加到组
移除组成员	/groups/{group_id}/members/{member_id}	DELETE	-	从组中移除用户

---

职级管理

API	端点	方法	请求体示例	说明
获取职级列表	/job_families	GET	-	查询所有职级
获取职级	/job_families/{job_family_id}	GET	-	查询单个职级
创建职级	/job_families	POST	{"name":"高级工程师"}	创建新职级
更新职级	/job_families/{job_family_id}	PUT	{"name":"资深工程师"}	修改职级
删除职级	/job_families/{job_family_id}	DELETE	-	删除职级

---

角色管理

API	端点	方法	请求体示例	说明
获取角色列表	/roles	GET	-	查询所有角色
创建角色	/roles	POST	{"role_name":"管理员"}	创建新角色
更新角色	/roles/{role_id}	PUT	{"role_name":"超级管理员"}	修改角色名称
删除角色	/roles/{role_id}	DELETE	-	删除角色
获取角色成员	/roles/{role_id}/members	GET	-	查询角色下的所有成员
批量添加角色成员	/roles/{role_id}/members/batch_create	POST	{"members":[{"member_id":"ou_xxx","member_type":"user"}]}	批量添加成员
批量删除角色成员	/roles/{role_id}/members/batch_delete	POST	{"members":[{"member_id":"ou_xxx"}]}	批量移除成员

---

ID 转换（核心）

飞书有三种 ID 体系：

ID 类型	说明	使用场景
open_id	应用内唯一	在同一应用内识别用户
user_id	企业内唯一	对接企业内部系统
union_id	跨应用唯一	在同一开发者的多个应用间使用

Contact v3 ID 转换

API	端点	方法	请求体示例	说明
批量获取用户 ID	/users/batch_get_id	POST	{"emails":["[email protected]"],"mobiles":["138xxx"]}	通过邮箱/手机号获取 OpenID
批量获取部门 ID	/departments/batch_get_id	POST	{"department_ids":["od_xxx"]}	部门 ID 转换
获取用户	/users/{user_id}	GET	-	通过 ID 获取用户信息
批量获取用户信息	/users/batch_get	GET	-	参数：user_ids=ou_1,ou_2

ID 转换最佳实践：

通过 GET /users/{user_id} 接口，可一次性获取用户的所有 ID 类型（open_id/user_id/union_id），无需单独转换。

示例：

GET /contact/v3/users/ou_xxx?user_id_type=open_id

响应包含：

{
  "data": {
    "user": {
      "open_id": "ou_xxx",
      "user_id": "7c43cd5f",
      "union_id": "on_xxx"
    }
  }
}

---

其他

API	端点	方法	说明
获取职务列表	/job_titles	GET	查询所有预设职务
获取职务	/job_titles/{job_title_id}	GET	查询单个职务详情
获取办公地点	/places	GET	用于人员地理分布分析
获取人员类型	/employee_types	GET	查询人员类型列表
获取自定义属性	/custom_attr_events	GET	查询自定义属性变更事件
获取授权范围	/scopes	GET	查询应用可访问的部门/用户范围
外部成员访问	/application/v1/applications/{app_id}/user_usable	GET	控制供应商/外包访问权限

事件订阅

通讯录支持 17 个变更事件：

事件类型	说明
contact.user.created_v3	用户创建
contact.user.updated_v3	用户信息更新
contact.user.deleted_v3	用户删除
contact.dept.created_v3	部门创建
contact.dept.updated_v3	部门更新
contact.dept.deleted_v3	部门删除
contact.employee_type.created_v3	人员类型创建
contact.employee_type.updated_v3	人员类型更新
contact.employee_type.deleted_v3	人员类型删除
contact.job_family.created_v3	职级创建
contact.job_family.updated_v3	职级更新
contact.job_family.deleted_v3	职级删除

---

最佳实践

1. ID 转换优先用 Spark API（更简洁）
2. 缓存常用 ID（减少 API 调用）
3. 组织架构变更必须预发测试