金蝶云星空单据回传钉钉：单策略闭环通知实战教程

这个策略解决什么问题

业务单据推到金蝶云星空之后，业务审批人需要立刻在钉钉里收到反馈——但金蝶本身不会主动通知钉钉。一次实际项目中，客户现场的要求很朴素：销售员在钉钉发起一张单据，审批通过后由后端写入金蝶云星空，写完之后要在钉钉那条审批流上「回一句」，让发起人知道已经落到 ERP。这个策略就是承接「金蝶 → 钉钉」的回执闭环，看似只是调一次评论接口，但要做对顺序、做对幂等、做对字段，并不容易。

数据流向与字段映射

整体链路是「金蝶云星空 → 轻易云 → 钉钉」。金蝶侧负责提供「这条单据写完了」的信号（通常是一条已生效单据的查询结果），轻易云做中转和触发，钉钉侧用「topapi/process/instance/com/add」类接口在原审批流上追加评论。

关键字段对照：

素材中的具体租户信息、租户号、API 平台号已在教程中隐去，仅保留业务字段。

在轻易云上如何配置

我们用轻易云数据集成平台（Qeasy）承接这一策略时，配置重点在三处。

第一，源端配置。源端是金蝶云星空一个「请求空操作」式查询（QUERY），用来把刚写入的单据主键拉回来。它的 metadata 入参里把 business_id 标记为 number 字段，idCheck=true，开启幂等。

第二，目标端配置。目标端是钉钉的「topapi/process/instance/comment/add」，类型 EXECUTE，方法 POST。请求对象是嵌套结构，外层包一个 request 对象，里面包含 processInstanceId 和 comment 两个核心字段。

第三，中间层组装。这是容易出问题的地方：comment 的内容是动态拼出来的，一般会带上「单据编号 + 业务日期 + 金蝶回执状态」。我们建议把这段拼装逻辑写在轻易云的「字段映射 / 脚本转换」里，集中管理，不要散落在金蝶或钉钉侧——这正是轻易云客户常见的「编码映射集中管理」模式。

实施步骤

我们通常分三阶段调度。

第一阶段，定增量起点。先用金蝶侧单据创建时间作为增量游标，确认起点后写入轻易云调度器，避免历史数据被一次性回灌。

第二阶段，触发全量验证。在切换正式调度前，开一次「全量触发」，把近 N 天的单据全部跑一遍，主要目的是核对两边流程实例是否能 1:1 对得上，对不上的单独标记。

第三阶段，日常调度。素材中目标端 crontab 是 */7 8-22 * * *，即工作时段每 7 分钟扫一次。这个频率对办公时段足够密集，对夜间又不会骚扰到人。源端的金蝶查询则按上游单据落库后的事件触发，做到「增量与全量双轨」的常见做法。

踩坑复盘

**坑一：comment 接口被风控拦截。**钉钉审批流的 comment 接口有调用频次上限，全量触发时容易瞬时打满。稳妥的做法是轻易云侧加一个节流阀，单租户每秒不超过 N 次。

**坑二：金蝶内码 ≠ 钉钉流程实例号。**两边完全不是同一套编号体系，必须在轻易云侧建立一张映射表，靠金蝶单据号（比如带业务前缀的编码）去关联钉钉流程实例。我们见过项目把这层映射放在钉钉自定义字段里，结果字段被审批人手动改过，导致回传找不到对应流。

**坑三：comment 内容出现乱码。**金蝶回带出来的单据标题如果带特殊符号，钉钉侧会原样透传到企业微信式的轻应用里。稳妥做法是在轻易云里做一次 HTML / 特殊字符清洗。

**坑四：失败重试导致重复评论。**钉钉 comment 接口本身没有强幂等，重试一次就发一条。我们的做法是依赖轻易云 idCheck + 单据内码去重，重试时如果发现已存在，直接跳过。

**坑五：审批流已结束，回传失败。**钉钉的已结束流程不允许再追加评论，接口会报错。处理方式是在轻易云侧先 query 一次流程状态，已结束就只落日志不调接口。

适用场景与不适用场景

适用：审批发起在钉钉、归档在金蝶，需要把 ERP 回执反馈到原流程上的轻协作场景。不适用：需要传附件回执、对接第三方财务系统的复杂场景；以及金蝶侧单据数量极大（单日万级以上）、不适合走逐单评论通道的高吞吐场景，后者建议走消息中台统一通知。