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} を使用します。

業務 API が無効な token、期限切れ、または 401 を返した場合は、強制的に更新した後、元のリクエストを 1 回だけ再試行します。

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 体系は 3 種類あります。

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. 组织架构变更必须预发测试