飞书API无官方C# SDK，需手动处理鉴权、签名、HTTP请求及重试；tenant_access_token须用app_id/app_secret获取并线程安全缓存刷新；消息发送需注意字段大小写、user_id仅支持open_id/union_id、msg_type小写、post内容需序列化；Webhook仅适用于机器人通知，服务端API才支持定向发送与已读回执；高频错误码99999、110021、10005须针对性处理。
飞书 API 没有官方 C# SDK，直接对接必须手动处理鉴权、签名、HTTP 请求和错误重试——这不是“调个库就能跑”的事，而是得自己搭轮子。
如何获取飞书 tenant_access_token（最常卡住的一步）
飞书所有服务端接口都依赖 tenant_access_token，它不是 App Token，也不是 User Token，且有效期仅 2 小时，必须缓存并自动刷新。
- 先用
app_id和app_secret向https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal/POST 获取 - 请求体必须是
application/json，不能是application/x-www-form-urlencoded - 响应中若出现
"code": 10005，基本是app_id或app_secret填错了，或应用未在对应飞书租户中安装 - 务必用线程安全的缓存（如
MemoryCache）存 token，并在过期前 30 秒触发刷新，避免并发请求反复刷 token
调用消息发送接口：message/v4/send 的关键细节
发消息看着简单，但字段名大小写、chat_id 与 open_id 混用、msg_type 值拼错，都会返回 99999 或 110021 这类模糊错误。
邮箱订单自动录入飞书
下载
开箱即用的采购订单自动审核 Skill：读取本地订单或飞书邮箱附件，调用 Laiye ADP 识别跨国采购订单，初始化/写入飞书多维表格订单工作台，上传订单源文件，并给审核负责人发送结构化私信，让业务人员只盯未匹配到内部商品、价格异常、新客户、币种异常等异常。
-
user_id字段只接受open_id或union_id，不接受手机号或邮箱；若要用手机号查用户，得先调contact/v3/users/batch_get_by_mobile -
msg_type必须小写，如"text"、"post"，写成"Text"会报错 - 发富文本（
post）时，content是 JSON 字符串，不是对象——必须JsonSerializer.Serialize()后再塞进外层 JSON，否则 400 - 测试阶段建议始终带上
enable_id_trans: true，避免 open_id 转换失败静默丢消息
Webhook 发送 vs 服务端 API 发送：别混用场景
Webhook 看似简单，但它不校验身份、不支持私聊、不返回已读状态，且飞书官方明确说“仅用于机器人通知”，和真正的服务端 API 完全不同路。
- Webhook 地址形如
https://www.feishu.cn/.../hook/xxx，只能 POST，无需 token，但无法指定接收人 - 服务端 API（如
message/v4/send）需tenant_access_token，可定向发给任意成员，支持撤回、已读回执等 - 若业务要求“发给某位员工”或“发完要确认是否送达”，必须走服务端 API，Webhook 在这里就是伪解法
- Webhook 的
Content-Type必须是application/json，且 body 中msg_type只支持"text"和"interactive"，不支持"post"
异常处理与日志必须覆盖这三类错误码
飞书 API 错误码文档分散，实际高频出问题的是这几个，不提前拦截会导致消息丢失无感知：
-
99999：通用系统错误，大概率是请求格式错（如少字段、类型错），应记录完整请求体和响应体用于排查 -
110021：用户不可达，常见于open_id过期（用户退出企业）或跨租户调用，需捕获后降级为 Webhook 或人工提醒 -
10005：鉴权失败，优先检查tenant_access_token是否过期或被其他实例误刷新，不要盲目重试 - 所有 HTTP 超时（
HttpRequestException）、非 2xx 响应，都应计入监控指标，而不是只打一行Console.WriteLine
飞书 API 的真实复杂度不在代码量，而在状态管理——token 刷新时机、用户 ID 类型转换、错误码语义理解，这些地方没日志、没监控、没幂等设计，上线后就会变成定时报警器。
