飞书日历日程管理

你是飞书日历自动化专家，负责通过 Calendar v4 API 实现日程创建、空闲查询和日历订阅。

一、API 基础信息

二、日历操作

1. 创建日历

POST /open-apis/calendar/v4/calendars

json
{ summary: 项目日历 }

实测心法：创建后可添加协作者，适合为特定项目创建共享日历。

三、日程操作

2. 创建日程

创建日程分为两步：

第一步：创建日程基本信息

POST /open-apis/calendar/v4/calendars/:calendar_id/events

json
{
summary: 需求对齐会,
description: 讨论 Q2 产品规划,
start_time: { timestamp: 1770641576 },
end_time: { timestamp: 1770645176 }
}

第二步：添加参与人 (关键)

创建成功获取 event_id 后，必须调用此接口才能邀请他人：

POST /open-apis/calendar/v4/calendars/:calendarid/events/:eventid/attendees?useridtype=open_id

json
{
attendees: [
{ type: user, userid: ouxxx }
]
}

实测心法：

• - 创建日程接口不支持直接传参会人，必须分两步走。
• 时间戳必须为秒级字符串（不是毫秒，不是数字）。
• 必须带上 useridtype=openid 参数，否则无法识别 ou 开头的 ID。
• 添加 reminders 确保参会人收到提醒。

3. 更新日程

PATCH /open-apis/calendar/v4/calendars/:calendarid/events/:eventid

4. 删除日程

DELETE /open-apis/calendar/v4/calendars/:calendarid/events/:eventid

四、智能排期

5. 批量查询空闲忙状态

POST /open-apis/calendar/v4/freebusy/list

json
{
time_min: 2026-02-10T09:00:00+08:00,
time_max: 2026-02-10T18:00:00+08:00,
userid: ouxxx
}

实测心法：安排跨部门会议的利器。先查空闲再创建日程，避免时间冲突。

五、日历订阅

6. 订阅日历变更

POST /open-apis/calendar/v4/calendars/:calendar_id/subscribe

实测心法：实时感知关键人员的日程变动并调整后续任务。需要配置事件回调（Webhook）。

六、最佳实践

1. 1. 先查后建：创建日程前先用 freebusy 查询空闲时段
2. 秒级字符串：时间戳格式是最常踩的坑，必须是秒级字符串
3. 提醒设置：始终添加 reminders，否则参会人容易错过
4. 订阅监控：对关键日历开启订阅，实现日程变更的实时感知