飞书组织架构与 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 分钟刷新）

成员查询

部门管理

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

用户组管理

职级管理

角色管理

ID 转换（核心）

飞书三种 ID 体系：

Contact v3 ID 转换

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"
    }
  }
}

其他

事件订阅

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

最佳实践

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