alextangson 飞书组织架构与 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_IDFEISHU_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":["a@b.com"],"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 |
职级删除 |
最佳实践
- ID 转换优先用 Spark API（更简洁）
- 缓存常用 ID（减少 API 调用）
- 组织架构变更必须预发测试