综合新闻
飞书 - 日历集成 配置与优化
2026-05-04 20:02
飞书日历集成：从API调用到Webhook订阅的完整实战指南，帮你跳过OAuth坑、解决时区混乱、实现自动化事件同步
一、前言
干了这么多年运维，最烦的就是厂商文档写得云里雾里。飞书日历集成这东西，看着文档一堆，真到对接的时候token刷新失败、时区差8小时、webhook签名验证绕不过去这些问题能把人逼疯。今天把实战中踩过的坑总结出来，照着做能省你半天时间。
二、操作步骤
步骤1：创建飞书应用获取App ID和Secret
先去飞书开放平台创建应用，启用日历权限。这一步是所有后续操作的前提。
# 1. 登录飞书开放平台，创建企业自建应用
# https://open.feishu.cn/app
# 2. 创建完成后，在「凭证与基础信息」获取：
# App ID: cli_xxxxxxxxxxxxx
# App Secret: 你的Secret（不要硬编码到代码里）
# 3. 必须添加以下权限（按需勾选）：
# calendar:calendar:readonly - 读取日历
# calendar:calendar:write - 创建/修改日历
# calendar:event:readonly - 读取事件
# calendar:event:write - 创建/修改事件
# calendar.acl:read - 读取访问控制
预期输出：创建应用后界面显示App ID和Secret，权限配置页面显示已勾选的权限列表。
步骤2：获取Tenant Access Token（应用级Token）
这是最常用的认证方式，适合后端服务调用。Token有效期2小时，要注意自动刷新。
# 调用飞书Auth接口获取tenant_access_token
curl -X POST "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" \
-H "Content-Type: application/json" \
-d '{
"app_id": "cli_xxxxxxxxxxxxx",
"app_secret": "YOUR_APP_SECRET"
}'
预期输出：
{
"code": 0,
"msg": "success",
"tenant_access_token": "t-xxxxxx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"expire": 7200
}
注意：expire是7200秒（2小时），生产环境必须做token刷新机制，别等到token过期了API调用全挂。
步骤3：获取User Access Token（用户授权Token）
如果需要访问用户私人日历或者获取更高权限，必须走OAuth2.0用户授权流程。
# 1. 引导用户访问授权URL（替换your_app_id和redirect_uri）
https://open.feishu.cn/open-apis/authen/v1/authorize?app_id=cli_xxxxxxxxxxxxx&redirect_uri=https%3A%2F%2Fyour-domain.com%2Fcallback&state=random_string
# 2. 用户授权后，回调URL会带code参数
# https://your-domain.com/callback?code=xxxxx&state=random_string
# 3. 用code换取user_access_token
curl -X POST "https://open.feishu.cn/open-apis/authen/v1/oidc/access_token" \
-H "Content-Type: application/json" \
-d '{
"grant_type": "authorization_code",
"code": "用户授权后返回的code"
}'
预期输出：
{
"code": 0,
"msg": "success",
"data": {
"access_token": "u-xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"token_type": "Bearer",
"expires_in": 7200,
"refresh_token": "r-xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"refresh_expires_in": 259200
}
}
⚠️ 警告：user_access_token有效期也是2小时，但有refresh_token可以延期30天。别傻乎乎每次都让用户重新授权，refresh_token用起来。
步骤4：创建日历并获取calendar_id
创建日历是集成的基础，可以创建主日历或者secondary日历。
# 创建日历（使用tenant_access_token）
curl -X POST "https://open.feishu.cn/open-apis/calendar/v4/calendars" \
-H "Authorization: Bearer t-xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"summary": "项目排期日历",
"description": "用于团队项目排期同步",
"color": 1,
"type": "primary"
}'
预期输出：
{
"code": 0,
"msg": "success",
"calendar": {
"calendar_id": "feishu_calendar_id",
"summary": "项目排期日历",
"description": "用于团队项目排期同步",
"color": 1,
"type": "primary",
"creator": {
"cal_id": "feishu_calendar_id"
}
}
}
记录好返回的calendar_id，后续所有操作都依赖它。注意：主日历(primary)只能创建一个，secondary可以建多个。
步骤5：创建日历事件（含时区处理）
创建事件是最常见的操作，这里有个大坑——时区处理。很多新手创建的事件时间对不上，就是因为没处理好timezone参数。
# 创建日历事件（北京时间UTC+8）
curl -X POST "https://open.feishu.cn/open-apis/calendar/v4/calendars/feishu_calendar_id/events" \
-H "Authorization: Bearer t-xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"summary": "周会",
"description": "技术团队周会",
"start_time": {
"timestamp": "1735689600",
"timezone": "Asia/Shanghai"
},
"end_time": {
"timestamp": "1735693200",
"timezone": "Asia/Shanghai"
},
"reminders": [
{
"minutes": 15
}
],
"location": {
"name": "线上会议"
}
}'
预期输出：
{
"code": 0,
"msg": "success",
"event": {
"event_id": "od-xxxxxxxxxxxx",
"summary": "周会",
"description": "关于技术团队周会的安排",
"start_time": {
"timestamp": "1735689600",
"timezone": "Asia/Shanghai"
},
"end_time": {
"timestamp": "1735693200",
"timezone": "Asia/Shanghai"
}
}
}
时区避坑指南：
- timestamp是Unix时间戳（秒），不是毫秒！
- 飞书用IANA时区格式，Asia/Shanghai而不是+8:00
- 如果是跨时区会议，start_time和end_time都要指定timezone
- Python时间处理推荐pytz库，别用 naive datetime
步骤6：订阅Webhook实现事件变更推送
光主动调用API不够，实际场景需要飞书主动推送事件变更过来。这就需要配置Webhook订阅。
# 1. 在飞书开放平台配置事件订阅
# 应用管理 -> 事件与回调 -> 请求地址配置
# 填入你的回调服务器地址，如：https://your-domain.com/feishu/webhook
# 2. 订阅的事件类型：
# calendar.event.create - 创建事件
# calendar.event.update - 更新事件
# calendar.event.delete - 删除事件
# 3. 回调服务器验证URL有效性（飞书会发GET请求验证）
# 需要返回challenge参数
@app.route('/feishu/webhook', methods=['GET'])
def verify():
challenge = request.args.get('challenge')
return jsonify({"challenge": challenge})
预期输出：GET请求返回{"challenge": "xxxx"}后，飞书会显示「验证成功」。
# 4. 处理事件推送（POST请求）
@app.route('/feishu/webhook', methods=['POST'])
def handle_event():
# 验证签名
body = request.get_json()
headers = request.headers
# 签名验证（重要！防止伪造请求）
import hashlib
import hmac
import time
timestamp = headers.get('X-Lark-Time')
signature = headers.get('X-Lark-Signature')
# 签名算法：hmac-sha256(timestamp + "\n" + body_string, app_secret)
# 处理事件
event_type = body.get('event', {}).get('type')
calendar_id = body.get('event', {}).get('calendar_id')
event_id = body.get('event', {}).get('event_id')
# 记录日志
logger.info(f"收到飞书日历事件: type={event_type}, calendar={calendar_id}")
return jsonify({"code": 0})
⚠️ 警告：webhook必须验证签名！否则任何人都能伪造事件推送到你服务器。上线前必须测试签名验证逻辑。
步骤7：批量操作与错误处理
实际项目中经常需要批量同步日历数据，这里分享生产级的批量操作写法。
# 批量获取事件列表（分页处理）
import requests
import time
def get_calendar_events(calendar_id, access_token, page_size=50):
events = []
page_token = None
while True:
url = f"https://open.feishu.cn/open-apis/calendar/v4/calendars/{calendar_id}/events"
params = {
"page_size": page_size,
"sync_token": page_token
} if page_token else {"page_size": page_size}
headers = {"Authorization": f"Bearer {access_token}"}
resp = requests.get(url, headers=headers, params=params)
if resp.status_code != 200:
# token过期处理
if resp.json().get('code') == 99991663:
access_token = refresh_access_token()
headers = {"Authorization": f"Bearer {access_token}"}
continue
raise Exception(f"API调用失败: {resp.text}")
data = resp.json()
events.extend(data.get('items', []))
if not data.get('has_more'):
break
page_token = data.get('page_token')
time.sleep(0.2) # 防止触发限流
return events
# 重试装饰器
from functools import wraps
def retry_on_expired_token(max_retries=3):
def decorator(func):
@wraps(func)
def wrapper(*args, **kwargs):
for i in range(max_retries):
try:
return func(*args, **kwargs)
except Exception as e:
if 'token' in str(e).lower() and i < max_retries - 1:
refresh_token()
continue
raise
return wrapper
return decorator
预期输出：成功获取到所有分页数据，无遗漏。限流时自动重试，token过期时自动刷新。
生产环境注意：
- API调用有频率限制，免费版每分钟60次，企业版更高
- 批量操作加sleep，防止触发限流
- 所有网络请求加超时设置，别让线程卡死
- 日志要记录完整请求参数，出问题好排查
三、常见问题FAQ
Q1：调用API返回99991663错误码，token明明没过期啊？
这破问题坑了我好几次。飞书的token过期判断逻辑有点迷，有时候服务器时间不同步也会报这个错。解决方案：收到99991663就直接refresh token，别纠结当前token还剩多久。企业微信也有类似问题，时间服务器同步好能解决一半。
Q2：webhook收不到推送，但手动调用API能正常获取数据？
八成是签名验证失败了。检查两点：一是回调地址必须公网可访问，飞书那边会验证；二是签名算法别搞错，正确的签名是把timestamp和body拼接后用HMAC-SHA256算。调试阶段先注释掉签名验证，确认能收到数据再加回去。
Q3：创建的事件日历里看不到，是权限问题吗？
权限是一方面，更重要的是calendar_id对不对。主日历和secondary日历的ID格式不一样，用错了查半天。另外就是检查一下是否把calendar设成「仅自己可见」了，在日历设置里能改可见范围。企业内部应用一般用主日历就行，别折腾secondary。
Q4：时区设置后时间还是差8小时，怎么回事？
飞书的timestamp是Unix时间戳（秒级），很多新手当成毫秒级处理，差了1000倍。另外就是timezone参数必须同时在start_time和end_time里传，只传一个的话会用默认时区。推荐用pytz库处理时间，naive datetime在生产环境迟早出事。
Q5：想同步飞书日历到本地，能用ICS格式吗？
飞书API支持导出ICS，但用起来挺麻烦的。更推荐的方式是定期调用events接口同步增量，变化少的时候同步效率高。ICS适合一次性导入导出，实时同步还得靠webhook。
四、总结
飞书日历集成就那几个核心点：先搞定认证（tenant token够用就别折腾user token），创建日历拿到calendar_id，然后增删改查事件按文档来，webhook订阅做好签名验证防伪造。踩过几个坑之后就觉得文档其实写得还行，就是示例代码残缺得厉害。
核心要点：
- Token刷新机制必须做，别等挂了自己还蒙在鼓里
- 时区用Asia/Shanghai，timestamp是秒不是毫秒
- Webhook必须验证签名，生产环境暴露公网这一步不能省
- API调用有频率限制，批量操作加sleep加重试
延伸阅读：
- 飞书开放平台日历API文档：日历API参考
- WebSocket长连接方案：适合需要实时性更高的场景，比Webhook更可靠
- 飞书事件订阅列表：按需订阅，别全加上增加回调复杂度
`
content = content.indexOf('') > 0 ? content.replace('', viewstyle + '') : viewstyle + content
const iframe = document.querySelector('#viewcontent')
const viewdoc = iframe.contentDocument
viewdoc.open()
viewdoc.write(content)
viewdoc.close()
iframe.height = viewdoc.body.scrollHeight + 20
})
