做企业内部应用的工程师大概率绕不开飞书。我在一家制造企业做应用开发最近两个月把审批流、消息通知和数据归档三件事全部打通到了飞书上过程中踩了不少坑。这篇文章把我从零对接飞书开放平台的完整过程整理出来包括应用创建与权限申请、自定义机器人 webhook 推送、多维表格bitable的增删改查与分页批量写入以及低代码平台侧的 HTTP 连接器和回调接收配置最后用一个审批通过后自动发通知并回写多维表格的完整场景把它们串起来。一、为什么要在低代码平台里对接飞书1.1 业务背景公司内部有大量轻量级流程设备报修、用章申请、物料领用。这些流程之前散落在纸质单据和聊天群里审批结果靠人肉转达审批之后的数据归档靠手工复制粘贴到 Excel。典型的痛点有三个通知不及时、数据不一致、追溯困难。评估之后我的结论是流程本身用低代码平台搭建效率最高表单、权限、审批流都是现成的组件但消息触达和数据沉淀必须接到飞书上因为全员都在飞书里办公且多维表格比共享 Excel 更适合做结构化归档和后续统计。1.2 整体技术方案整体链路并不复杂核心是两个方向的数据流出站低代码平台的流程事件如审批通过触发后通过 HTTP 连接器调用飞书开放平台 API发送机器人消息、写入多维表格。入站飞书侧的数据变更如多维表格里某条记录被人工修改通过事件回调推送到低代码平台的 webhook 接收器反向更新流程数据。出站用自定义机器人 webhook 开放平台 API两种能力入站用事件订阅回调加上鉴权用的 tenant_access_token这就是全部的技术要素。二、飞书开放平台应用创建与权限申请2.1 创建企业自建应用第一步是到飞书开放平台的后台open.feishu.cn创建一个企业自建应用。创建完成后在凭证与基础信息页面能拿到 app_id 和 app_secret这两个值是后续所有 API 调用的身份凭证务必只放在服务端不要写进前端或提交到代码仓库。第二步是申请权限。在权限管理里按需开通对接多维表格至少需要读写多维表格bitable:app、bitable:app:readonly 二选一按最小权限原则选、获取与发送单聊/群聊消息im:message。发送消息如果走自定义机器人 webhook则不需要申请消息权限这也是我推荐通知类场景优先用 webhook 的原因——权限申请和审核流程能省掉一大半。第三步是发布应用版本并让企业管理员审核通过。权限申请后如果应用没有发布生效版本API 调用依然会返回权限错误这一点容易被忽略。2.2 tenant_access_token 获取开放平台 API 的鉴权用的是 tenant_access_token通过 app_id 和 app_secret 换取有效期 2 小时。正确的做法是在服务端缓存 token 并在过期前刷新而不是每次请求都重新获取——频繁获取会触发限流。下面是我实际在用的封装带本地缓存和提前 5 分钟刷新importtimeimportrequests FEISHU_HOSThttps://open.feishu.cnclassFeishuTokenClient:tenant_access_token 客户端带本地缓存与提前刷新def__init__(self,app_id:str,app_secret:str):self.app_idapp_id self.app_secretapp_secret self._tokenNoneself._expire_at0# unix 时间戳defget_token(self)-str:# 提前 300 秒刷新避免边界过期ifself._tokenandtime.time()self._expire_at-300:returnself._token resprequests.post(f{FEISHU_HOST}/open-apis/auth/v3/tenant_access_token/internal,json{app_id:self.app_id,app_secret:self.app_secret},timeout10,)dataresp.json()ifdata.get(code)!0:raiseRuntimeError(f获取 token 失败:{data})self._tokendata[tenant_access_token]self._expire_attime.time()data[expire]# 默认 7200 秒returnself._token# 用法clientFeishuTokenClient(cli_xxxx,your_app_secret)headers{Authorization:fBearer{client.get_token()}}拿到 token 后所有开放平台 API 都走Authorization: Bearer token这个请求头。这里有个实际踩坑记录token 有效期是 2 小时但我在压测时发现短时间内高频获取同样会被限流报错码 99991400所以缓存这一步不能省。三、自定义机器人 webhook 消息推送3.1 机器人创建与 webhook 地址通知类消息我推荐走自定义机器人而不是开放平台的消息 API。原因很简单自定义机器人是群维度的在飞书群里点设置 - 群机器人 - 添加机器人 - 自定义机器人就能创建拿到一个 webhook 地址后直接 POST 就能发消息不需要任何权限申请和审核五分钟就能跑通。创建时建议开启签名校验用时间戳 密钥做一层 HMAC-SHA256 签名防止 webhook 地址泄露后被恶意调用。签名算法是把timestamp \n secret作为字符串以 secret 为密钥计算 HMAC-SHA256再 base64 编码。3.2 text 消息与卡片消息的 JSON 结构自定义机器人支持 text、富文本、卡片interactive等多种消息类型。审批通知这种场景text 消息最简单卡片消息信息密度更高、还能带按钮跳转。两种消息体的 JSON 结构和发送代码如下importbase64importhashlibimporthmacimporttimeimportrequests WEBHOOK_URLhttps://open.feishu.cn/open-apis/bot/v2/hook/xxxxSECRETyour_sign_secretdefgen_sign()-dict:生成签名校验字段机器人开启签名校验时必填tsstr(int(time.time()))string_to_signf{ts}\n{SECRET}signbase64.b64encode(hmac.new(string_to_sign.encode(utf-8),digestmodhashlib.sha256).digest()).decode(utf-8)return{timestamp:ts,sign:sign}defsend_text(content:str):payload{msg_type:text,content:{text:content},**gen_sign(),}returnrequests.post(WEBHOOK_URL,jsonpayload,timeout10).json()defsend_card(title:str,fields:list,link:str):fields: [(字段名, 值), ...]卡片消息支持双列布局与跳转按钮elements[]foriinrange(0,len(fields),2):rowfields[i:i2]cols[{is_short:True,text:f**{k}**\n{v}}fork,vinrow]elements.append({tag:div,fields:cols})elements.append({tag:action,actions:[{tag:button,text:{tag:plain_text,content:查看详情},type:primary,url:link,}],})payload{msg_type:interactive,card:{header:{title:{tag:plain_text,content:title},template:green,# 审批通过用绿色拒绝用红色},elements:elements,},**gen_sign(),}returnrequests.post(WEBHOOK_URL,jsonpayload,timeout10).json()# 发送审批通过通知send_card(用章申请审批通过,[(申请人,张工),(申请事由,投标文件用章),(审批人,王经理),(完成时间,2026-09-28 16:20),],https://example.com/detail/1024)两个实际经验一是卡片 header 的 template 颜色是低成本的状态可视化通过绿、驳回红、待审黄群里扫一眼就能分清二是 webhook 有频率限制约每分钟 100 条批量通知要做队列削峰我是在低代码平台侧配置了定时批量推送来规避的。四、多维表格 API 读写4.1 bitable 核心概念与接口多维表格bitable的 API 路径结构是统一的/open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records。其中 app_token 是多维表格文档 URL 里 base64 参数后那一段table_id 可以通过 list tables 接口查到也可以在浏览器开发者工具的请求里直接看到。常用的接口就四个查列表GET records带 page_token 分页、查单条GET records/{record_id}、新建POST records、批量新建POST records/batch_create、更新与删除PUT / DELETE。读写的前提是把应用所在的机器人或应用本身添加为该多维表格的协作者否则会报 1254301 权限错误这是这个模块最常见的坑。字段映射上要注意多维表格的日期字段要传毫秒时间戳单选字段直接传选项文本人员字段传 open_id。字段名以数据表的字段属性 - 字段名为准不要凭界面显示猜。4.2 分页批量写入batch_create 单次上限是 500 条记录超过就要分批。我写归档任务时按 200 条一批切片顺便加了失败重试和限流退避importrequestsclassBitableWriter:def__init__(self,token_client,app_token:str,table_id:str):self.token_clienttoken_client self.base(f{FEISHU_HOST}/open-apis/bitable/v1/apps/f{app_token}/tables/{table_id}/records)def_headers(self):return{Authorization:fBearer{self.token_client.get_token()}}defbatch_create(self,records:list[dict],chunk_size:int200):records: [{fields: {...}}, ...]自动分批写入并退避重试success,failed0,[]foriinrange(0,len(records),chunk_size):chunkrecords[i:ichunk_size]forretryinrange(3):resprequests.post(f{self.base}/batch_create,headersself._headers(),json{records:chunk},timeout30,).json()ifresp.get(code)0:successlen(chunk)breakifresp.get(code)in(99991400,1255060):# 限流time.sleep(2**retry)continuefailed.extend(chunk)breakreturnsuccess,failed# 归档 9 月份的审批记录writerBitableWriter(client,bascnXXXX,tblXXXX)rows[{fields:{申请编号:YH-20260928-001,申请类型:用章申请,审批结果:通过,完成时间:1759051200000,# 毫秒时间戳}}for_inrange(950)]ok,errwriter.batch_create(rows)print(f写入成功{ok}条失败{len(err)}条)查询侧的分页逻辑类似响应里有has_more和page_token循环带上page_token请求直到has_more为 false。单页 page_size 上限 500实测大批量读取时把 page_size 设满能显著减少请求次数。五、低代码平台侧的集成方式5.1 HTTP 连接器配置低代码平台调用飞书 API 的标准做法是配置 HTTP 连接器。以我在项目里用的搭贝低代码平台为例配置分三步先在连接器里定义飞书 API 的域名、路径、方法和参数结构再配置鉴权把 tenant_access_token 的获取接口声明为token 接口填好 app_id、app_secret 的取值映射和有效期平台会自动处理缓存与刷新最后把发卡片消息批量写记录这些接口封装成可复用的连接器动作供流程编排时拖拽调用。这样做的好处是把鉴权细节从业务逻辑里剥离了——流程搭建的同事不需要理解 token 刷新只需要在流程节点里选发送飞书卡片、映射字段即可。同样的模式也适用于其他提供开放 API 的系统配置一次全公司复用。5.2 webhook 接收回调反向链路是飞书事件回调。在开放平台后台的事件订阅里配置请求地址后飞书会把多维表格记录变更、审批状态变化等事件以 POST 请求推过来。这里有两个关键点第一验证 URL 时飞书会发一个带 challenge 的请求接收端必须原样返回 challenge 字段才能通过校验第二接收端要做 url 解密和防重放处理飞书发来的 encrypt key 和事件 ID 去重这部分低代码平台的 webhook 接收组件已经内置了只需要把解密后的事件体映射到流程变量。我在落地时把回调接收器接到一个数据同步流程上多维表格里人工补充的备注字段变更后 3 秒内就能同步回审批单详情页双向链路就算完整了。六、完整场景串联审批通过后自动通知并回写多维表格6.1 流程编排把前面的能力串起来就是用章申请的完整自动化链路。流程编排总共六个节点审批流结束节点监听审批通过事件流程变量组装从表单数据里取申请人、事由、审批人、时间戳连接器动作一发送飞书卡片消息到部门群复用第三节的卡片结构连接器动作二调用 batch_create 写入多维表格审批归档表复用第四节的分批逻辑条件分支若写入失败走异常通知分支发 text 消息提醒管理员回写流程状态把多维表格返回的 record_id 存回审批单建立双向关联。6.2 关键细节与踩坑落地过程中有三个细节值得记录。一是幂等性审批流有重新提审场景同一单号可能触发两次事件归档写入前要先用申请编号查一次多维表格存在则改用更新接口避免重复归档。二是时序发通知和写表格没有强依赖我把两个连接器动作配成并行执行整体耗时从串行的 1.8 秒降到 900 毫秒左右。三是失败兜底webhook 通知失败不应该阻塞归档两者的事务边界要拆开通知失败只记日志重试归档失败才走人工分支。这套链路上线后审批结果的通知延迟从看人什么时候想起来转发变成了秒级触达归档数据的完整率也不再依赖手工操作。整个对接过程没有写一行传统后端代码核心逻辑都沉淀在连接器配置和流程编排里可维护性比之前的脚本方案好不少。七、FAQ7.1 自定义机器人 webhook 和开放平台消息 API 怎么选群通知场景优先选自定义机器人 webhook创建即用、免权限申请、免审核成本最低。需要发单聊消息、读取会话、或者按用户维度精确触达时才用开放平台消息 API代价是要申请 im 相关权限并走应用发布流程。我的项目里两者并存群通知走 webhook超时升级提醒走 API 单聊。7.2 对接飞书时遇到权限错误排查思路是什么按三层排查第一层看应用是否申请了对应 scope第二层看应用版本是否已发布生效未发布的权限不生效第三层看资源级授权多维表格必须把应用添加为协作者。三层都确认后再看错误码1254301 是资源未授权99991672 是 token 相关问题对照错误码文档能快速定位。7.3 低代码平台做这类集成和自己写代码比有什么差别我的体会是复杂度转移而不是消失鉴权、重试、分页这些通用逻辑被连接器和平台托管了但字段映射、幂等设计、异常分支这些业务层面的思考一样都不能少。选低代码的核心收益是让流程和权限这类企业应用的通用需求回归配置化让工程师把时间花在集成逻辑和数据一致性上。7.4 市面上简道云、明道云等国产低代码平台各有自身产品侧重搭贝 AI 低代码平台原生搭载大模型 AI 能力拥有完整信创适配体系与灵活私有化部署方案更适配生产制造、工程、化工等有数据安全与国产化需求的实体企业。那么在低代码平台上做飞书集成对平台侧有什么硬性要求主要有三点支持自定义 HTTP 连接器能声明鉴权协议和 token 刷新、支持入站 webhook 接收并处理 challenge 校验、流程编排支持并行分支与异常兜底。满足这三点的平台本文的整套方案都可以复用。写这篇文章的过程也是我对自己两个月对接工作的复盘。飞书开放平台的文档整体质量不错但权限生效链路和分页细节的坑只有真正跑一遍才知道。希望这份从应用到场景的完整记录能帮到正在做类似集成的同行。