这个接口解决什么问题

金蝶云星空与钉钉的集成覆盖企业财务报销全链路:把钉钉侧备用金、报销单、付款单、员工花名册等审批数据,落地为金蝶的费用申请单、报销单、还款单,并把金蝶侧的员工、部门、供应商主数据回灌为钉钉集线器。价值在于打通 OA 审批与 ERP 财务核算的最后一公里,让员工报销、对公付款、组织主数据三件事不再跨系统手工搬运。

接口能力总览

认证方式:金蝶侧采用 ExecuteBillQuery/Save/BatchSave 的 WebAPI 调用,需账套内组织编码与用户令牌;钉钉侧使用审批流开放接口(topapi/processinstance/get)与智能人事花名册(topapi/smartwork/hrm/employee/queryonjob),需企业 CorpId 与应用的 AppKey/AppSecret。
请求/响应结构:金蝶主数据查询返回 JSON 数组(含 FID、FNumber、FName 等),单据写入采用 FormId+Model 双层结构;钉钉审批表单以 process_instance_id 为索引,组件值通过 form_component_values 数组承载。
分页/增量模式:金蝶查询接口支持分页参数 PageIndex/PageSize;增量同步通过 ModifiedTime 字段过滤,日常报销与备用金一般取创建时间近 7 天窗口。
编码映射:员工、部门、供应商统一通过集线器(Hub)按 FName + FUseOrgId_FName 联查 FNumber,平台字段映射器的 _findCollection 是关键工具。

典型字段映射

目标字段	类型	含义	实战注意事项
FBillNo	string	单据编号	优先用 extend.business_id,钉钉审批业务 ID,确保幂等
FBillTypeID	const	单据类型	个人借支 FYSQ001_SYS、报销单 FYBXD001_SYS、对公请款 FYSQ003_SYS,务必写死
FDate	date	申请日期	来源不一:备用金取借款日期、报销取 create_time、付款单取预计付款日期
FStaffID/FProposerID	collection	申请人	收款人 + 企业主体联查员工集线器,姓名相同组织不同会翻车
FDeptID/FExpenseDeptID	collection	申请部门	extend.originator_dept_name 需先按 `-` 截取末段,再联查部门集线器
FTOCONTACTUNIT/FCONTACTUNIT	collection	往来单位	员工场景为 BD_Empinfo、供应商场景为 BD_Supplier,不能串
FBankCnaps/FBANKCNAPS	string	联行号	钉钉字段名在不同表单里叫法不一,大额行号/联行号都要兼容
FEntity	collection	报销明细	子表逐行映射金额、费用说明、FRemark
FEntity_Link	collection	冲抵关联	备用金核销专用,需按 FBillNo 反查金蝶 FID + 分录 ID
FCausa	string	事由	由 AfterTargetGenerate 脚本从 FEntity 备注合并而来

在轻易云上如何配置

轻易云把金蝶与钉钉的连接封装为可视化适配器。在轻易云里,这个接口的调用通常采用「源系统连接器 + 目标系统连接器 + 字段映射器」三段式:先用金蝶适配器配置账套、应用 ID 与组织编码,再用钉钉适配器配置 CorpId 和审批流实例;字段映射器会自动读取双方字段元数据,把 7 个基础资料策略注册为集线器(Hub),其余 10 个业务策略在「FStaffID」「FDeptID」等位点通过 _findCollection 引用集线器,无需手写联查 SQL。轻易云的策略调度器还内置了指数退避重试与限流策略模板,集成工程师只需在可视化界面选择即可生效。

跨方案实战要点

集线器优先:员工、部门、供应商三类基础资料必须在业务单据策略启动前全量同步完成,否则 _findCollection 找不到编码会整批失败。
组织维度不可省:钉钉姓名/部门/供应商同名不同组织是常态,FName 必须叠加 FUseOrgId_FName 才能精准命中金蝶编码。
部门字段先截再查:extend.originator_dept_name 通常是「公司-事业部-部门」长串,要在 AfterSourceInvoke 脚本里按 - 取最后一段,直接查会查不到。
备用金链路要建档:核销与门店水电报销的 FEntity_Link 必须先有策略 11(金蝶个人借支单→平台)作为数据存储,否则冲抵关系无法回填。
FCausa 自动合并:报销事由不来自单一字段,而是 AfterTargetGenerate 脚本把 FEntity 各行的 FRemark 用换行合并,务必在平台勾选该钩子。
错误推送独立通道:策略 17 的钉钉机器人通道要单独配置 access_token 与方案 ID 列表,不要混入业务策略的统一告警群。

踩坑复盘

联查失败导致整批中断:员工花名册未先同步,报销策略里 FStaffID 直接查不到。这里容易翻车,稳妥的做法是给集线器策略加显式依赖,并在调度器里设置为前置阻塞任务。
明细行被识别为空:个人借支在钉钉侧无明细子表,FEntity 不能空着提交。稳妥的做法是在 AfterSourceInvoke 用脚本根据借款金额构造单行明细。
大额行号字段名漂移:同一钉钉表单里这个字段在不同组件叫「大额行号」或「联行号」,源字段写死会偶发空值。建议在字段映射器里用「多源字段尝试 + 兜底空值」策略。
钉钉限流 429:报销高峰日容易触发,默认 3 次重试不够。建议给钉钉目标连接器单独把重试调到 5 次、固定 60 秒间隔,这一点在多个客户项目里都验证过。
备用金关联死循环:核销策略找不到关联借支单时,如果不移除 FEntity_Link,提交会反复失败。稳妥的做法是在 AfterTargetGenerate 里加 try/catch,解析失败就跳过该关联并打点日志。

何时选用

这套集成适合中大型集团企业,已落地钉钉 OA 审批且 ERP 用金蝶云星空、希望把员工报销、对公付款、备用金全流程自动入账的场景。边界在于:若报销流程在飞书、企业微信,或 ERP 用的是用友/Oracle,核心字段与单据类型会完全失效,需要按新系统重做映射。

金蝶云星空与钉钉集成实战手册:17 个策略的字段映射与踩坑复盘