feishu-approval

Feishu 承認

Approval API を使用して承認インスタンスを作成、照会します。

Base URL: https://open.feishu.cn/open-apis/approval/v4

認証と Token の取得

feishu_skills のルートディレクトリから共有スクリプトを実行します。

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

リクエストヘッダーには、常に Authorization: Bearer ${TOKEN} を使用します。

業務 API が無効または期限切れのトークン、あるいは 401 を返した場合は、強制的に更新してから元のリクエストを 1 回だけ再試行します。

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

環境変数:

• FEISHU_APP_ID
• FEISHU_APP_SECRET

ローカルキャッシュ: ./.feishu_token_cache.json（有効期限内であればそのまま再利用します。デフォルトでは期限の 5 分前に更新します）

---

承認インスタンス

API	エンドポイント	メソッド	リクエストボディの例	説明
インスタンスの作成	/instances	POST	{"approval_code":"7C46...","user_id":"ou_xxx","form":"{\"widget1\":\"value1\"}"}	承認を申請します
インスタンスの照会	/instances/{instance_id}	GET	-	承認のステータスを取得します
承認操作	/instances/{instance_id}/approve	POST	{"comment":"同意","task_id":"xxx"}	承認／拒否します
承認の取り消し	/instances/{instance_id}/cancel	POST	{"user_id":"ou_xxx"}	申請者が取り消します
承認の転送	/instances/{instance_code}/transfer	POST	{"user_id":"ou_xxx","transfer_user_id":"ou_yyy","comment":"転交"}	他の人に転送します
承認の催促	/instances/{instance_id}/urge	POST	-	催促の通知を送信します
インスタンス一覧の取得	/instances	GET	クエリパラメーター：page_size=50&page_token=xxx&user_id=ou_xxx	フィルターパラメーターに対応しています（ページネーション）
インスタンス詳細の照会	/instances/detail	POST	{"instance_code":"xxx"}	詳細全体を照会します

インスタンスの作成:

{
  "approval_code": "7C468A54-8745-2245-9675-08B7C63E7A85",
  "user_id": "ou_xxx",
  "form": "{\"widget1\":\"value1\"}"
}

---

承認タスク

API	エンドポイント	メソッド	リクエストボディの例	説明
タスク一覧の取得	/tasks	GET	-	未処理タスクを照会します
タスク詳細の取得	/tasks/{task_id}	GET	-	タスク詳細を照会します
タスクの承認	/tasks/{task_id}/approve	POST	{"comment":"同意"}	承認タスクを処理します
タスクの転送	/tasks/{task_id}/transfer	POST	{"transfer_user_id":"ou_xxx"}	タスクを転送します

---

承認定義

API	エンドポイント	メソッド	リクエストボディの例	説明
定義一覧の取得	/approvals	GET	-	すべての承認テンプレートを照会します
定義詳細の取得	/approvals/{approval_code}	GET	-	テンプレートの詳細を照会します
定義フォームの取得	/approvals/{approval_code}/forms	GET	-	フォームのフィールド定義を照会します

---

承認の CC

API	エンドポイント	メソッド	リクエストボディの例	説明
CC 一覧の取得	/cc	GET	-	自分宛ての承認 CC を照会します
CC の既読化	/cc/{instance_id}/read	POST	-	CC を既読としてマークします

---

承認コメント

API	エンドポイント	メソッド	リクエストボディの例	説明
コメントの追加	/instances/{instance_id}/comments	POST	{"content":"コメント内容","user_id":"ou_xxx"}	承認コメントを追加します
コメントの取得	/instances/{instance_id}/comments	GET	-	コメント一覧を照会します

---

よく使うパラメーターの説明

user_id_type: ユーザー ID の種類

• open_id（デフォルト）
• user_id
• union_id

ページネーションパラメーター:

• page_size: 1 ページあたりの件数（デフォルトは 20、最大 100）
• page_token: ページネーショントークン

インスタンスのステータス:

• PENDING: 承認中
• APPROVED: 承認済み
• REJECTED: 拒否済み
• CANCELED: 取り消し済み
• DELETED: 削除済み

---

テスト例

承認定義一覧の取得:

curl -X GET "https://open.feishu.cn/open-apis/approval/v4/approvals?page_size=10" \
  -H "Authorization: Bearer ${TOKEN}"

承認インスタンスの作成:

curl -X POST "https://open.feishu.cn/open-apis/approval/v4/instances" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "approval_code": "7C468A54-8745-2245-9675-08B7C63E7A85",
    "user_id": "ou_xxx",
    "form": "{\"widget1\":\"请假3天\"}"
  }'

インスタンス一覧の照会:

curl -X GET "https://open.feishu.cn/open-apis/approval/v4/instances?page_size=20&user_id=ou_xxx" \
  -H "Authorization: Bearer ${TOKEN}"

---

ベストプラクティス

1. まず承認定義を取得します（form のフィールドを確認します）
2. form は JSON を文字列化する必要があります
3. 承認操作には承認者の権限が必要です
4. ページネーションによる照会：大量のデータは page_token でページネーションします
5. user_id は必須です：インスタンスの作成と一覧の照会では、どちらも user_id の指定が必要です