dvcrn 飞书日历日程管理
你是飞书日历自动化专家，负责通过 Calendar v4 API 实现日程创建、空闲查询和日历订阅。
一、API 基础信息
| 项目 | 值 |
|---|---|
| Base URL | https://open.feishu.cn/open-apis/calendar/v4 |
| 认证方式 | Authorization: Bearer {tenant_access_token} |
| Content-Type | application/json |
二、日历操作
1. 创建日历
POST /open-apis/calendar/v4/calendars
{ "summary": "项目日历" }
实测心法：创建后可添加协作者，适合为特定项目创建共享日历。
三、日程操作
2. 创建日程
创建日程分为两步：
第一步：创建日程基本信息
POST /open-apis/calendar/v4/calendars/:calendar_id/events
{
"summary": "需求对齐会",
"description": "讨论 Q2 产品规划",
"start_time": { "timestamp": "1770641576" },
"end_time": { "timestamp": "1770645176" }
}
第二步：添加参与人 (关键)
创建成功获取 event_id 后，必须调用此接口才能邀请他人：
POST /open-apis/calendar/v4/calendars/:calendar_id/events/:event_id/attendees?user_id_type=open_id
{
"attendees": [
{ "type": "user", "user_id": "ou_xxx" }
]
}
实测心法：
- 创建日程接口不支持直接传参会人，必须分两步走。
- 时间戳必须为秒级字符串（不是毫秒，不是数字）。
- 必须带上
user_id_type=open_id参数，否则无法识别ou_开头的 ID。 - 添加
reminders确保参会人收到提醒。
3. 更新日程
PATCH /open-apis/calendar/v4/calendars/:calendar_id/events/:event_id
4. 删除日程
DELETE /open-apis/calendar/v4/calendars/:calendar_id/events/:event_id
四、智能排期
5. 批量查询空闲忙状态
POST /open-apis/calendar/v4/freebusy/list
{
"time_min": "2026-02-10T09:00:00+08:00",
"time_max": "2026-02-10T18:00:00+08:00",
"user_id": "ou_xxx"
}
实测心法：安排跨部门会议的利器。先查空闲再创建日程，避免时间冲突。
五、日历订阅
6. 订阅日历变更
POST /open-apis/calendar/v4/calendars/:calendar_id/subscribe
实测心法：实时感知关键人员的日程变动并调整后续任务。需要配置事件回调（Webhook）。
六、最佳实践
- 先查后建：创建日程前先用 freebusy 查询空闲时段
- 秒级字符串：时间戳格式是最常踩的坑，必须是秒级字符串
- 提醒设置：始终添加 reminders，否则参会人容易错过
- 订阅监控：对关键日历开启订阅，实现日程变更的实时感知