金蝶云星空单据审核后回传钉钉通知：基于轻易云的闭环同步策略实战

这个策略解决什么问题

业务现场常见的痛点是：报销单、付款单等单据先在钉钉审批流里发起，审批通过后再传给金蝶云星空做账务落库。但单据进了金蝶以后，财务还需要在金蝶里再走一道审核流程才算真正落地。申请人、审批人此时完全感知不到金蝶那边的进度，常常反复来问「我的单子到底过了没有」。

这个策略就是为这种场景设计的：定时去金蝶云星空拉取指定单据的审核状态，一旦发现状态从「未审核」变成「已审核」，就调用钉钉的审批流评论接口，在对应的审批实例下发一条「已审核」的提示。整个闭环不依赖人工在两个系统之间切换，轻易云数据集成平台（Qeasy）负责把状态变更翻译成钉钉侧可见的消息。

数据流向与字段映射

整条链路可以拆成「源系统 → 中间层 → 目标系统」三段来看。源是金蝶云星空，中间是轻易云集成平台（Qeasy）自身的状态记录，目标则是钉钉的审批流实例。

源端通过金蝶的 executeBillQuery 接口，把单据编号、实体主键、单据状态、创建人、审核人等关键字段拉出来。我们真正关心的只有三列：FBillNo（单据编号）、FDOCUMENTSTATUS（单据状态）、FID（实体主键）。其余字段在第一版里可以不取，等真要回溯责任人再补，避免一开始就把映射表堆得太厚。

中间层在 Qeasy 上做两件事：一是把金蝶回包里的状态码翻译成业务可读的字符串，二是按单据编号建立索引，记录「上次已通知的状态」，用来比对本次是否发生状态跃迁。

目标端调的是钉钉的 topapi/process/instance/comment/add 接口，把评论内容挂回原始审批实例。请求体里只需要把审批实例 ID、要发送的用户 ID、评论正文三个字段组装好，其它钉钉原生的扩展字段保持默认。

关键字段对照可以这样整理：

在轻易云上如何配置

配置这个策略时，建议把源端 metadata 的 idCheck 保留为 true，让平台用实体主键做幂等校验，避免同一张单据被重复扫描。

源端 metadata.api 设为 executeBillQuery，method 为 POST，过滤条件里把 FDOCUMENTSTATUS 作为查询字段带出来即可。请求字段列表里只保留真正参与判断的 FBillNo、FDOCUMENTSTATUS、FID 三项，其余字段不勾选，能显著减少回包体积。

目标端 metadata.api 选 topapi/process/instance/comment/add，请求结构是嵌套对象，request 是必填的 object 类型，里面再放 process_instance_id、userid、comment 三个子字段。在 Qeasy 的字段映射区，把中间层算出来的 process_instance_id 绑到 request.process_instance_id，把模板拼接好的「您的单据 {bill_no} 已审核」绑到 request.comment。

轻易云客户常见的做法是把所有「金蝶状态码 → 中文描述」的映射集中放在一个码表里维护，而不是散落在每个策略里。这样审核人换了、加了新状态码，只改一处就能生效。

实施步骤

第一阶段先把增量起点跑稳。挑选一张真实已审核的单据，手动把它的单据编号录入到 Qeasy 的「初始已通知状态」表里，避免它一上来就被误判为「状态从空变为已审核」而触发通知。

第二阶段触发一次全量巡检。手动执行一次源端查询，把过去一段时间内所有 FDOCUMENTSTATUS = 已审核 的单据拉出来，逐条和中间层的索引比对。如果发现比对结果有遗漏，再回去检查是过滤条件写错，还是源端接口本身就没返回这条数据。

第三阶段进入正式调度。源端用 */10 8-22 * * *，意思是工作时间内每 10 分钟扫一次金蝶，目标端用 */6 8-22 * * *，每 6 分钟执行一次推送。源端频率比目标端稍低，是因为金蝶的 executeBillQuery 有调用成本，没必要扫得比推送还勤。

第四阶段做表头与表体的分阶段验证。表头（单据本身的状态）先行上线，跑一周没有误报再考虑要不要把分录级别的状态也接进来。

踩坑复盘

第一，状态码比对一定要做「上次状态」缓存，不能只看「当前是不是已审核」。如果不做缓存，金蝶里任何一次重新保存都会让 FDOCUMENTSTATUS 字段重新返回，Qeasy 会误以为状态变了又发一遍通知，钉钉侧就会被刷屏。

第二，process_instance_id 这个映射关系必须一开始就和发起阶段的策略对齐。我们见过一个项目，发起时用的是钉钉表单 ID，回查时却传成了审批实例 ID，导致评论发到了错误的实例上。在轻易云上建议单独维护一张「钉钉实例 ↔ 金蝶单据编号」对照表，两个策略共用同一份数据源。

第三，调度时间窗口要和工作时间对齐。源端和目标端的 crontab 都限定在 8-22 点之间，晚上和周末不扫、不推。如果不做这个限制，凌晨金蝶做日结时返回的状态可能是中间态，Qeasy 会把它当成真实状态缓存下来，第二天业务一上线就乱套。

第四，钉钉的评论接口有调用频次上限，单租户每分钟不要超过几十次。源端 10 分钟扫一次、目标端 6 分钟推一次的节奏，在单据量不大的企业里完全够用；但如果业务量上来，建议把目标端的批量推送接口用起来，而不是逐条调用。

第五，典型的错误是只盯单据状态本身，忽略了审核人字段。一旦审核被驳回再重新提交，FDOCUMENTSTATUS 会经历「已审核 → 已驳回 → 已审核」的反复，Qeasy 只看状态码就会反复推送。稳妥的做法是把 FAPPROVERID 也带进比对，审核人没变就只发一次。

适用场景与不适用场景

这个策略适合报销、付款、费用申请等「钉钉发起 → 金蝶落账 → 金蝶审核」的三段式流程，单据量在每天几十到几百之间，业务对状态可见性要求高。不适合的场景是：金蝶侧没有明确的「已审核」状态字段，或者钉钉审批流本身没有可挂载评论的实例 ID，再或者单据量极大需要实时推送、对分钟级延迟都不能容忍的场景——后者建议直接走事件流而不是定时轮询。