事情要从去年年底的财务对账说起。当时财务经理拿着一份Excel找我上面列了四十多笔差异钉钉里明明审批通过的报销单金蝶云星空系统里要么没有对应凭证要么金额对不上。原因大家心里都清楚同一个报销单钉钉审批走一遍流程财务还要在ERP里手工重新录一遍两边全靠人肉搬运中间环节一多不出错才是意外。那次对账之后我花了大半个月时间把钉钉审批通过→金蝶云星空自动生成报销凭证这条链路完整做通了。这篇文章就把整个方案摊开来讲包括选型时的纠结、两边的接口准备、核心代码怎么写、字段映射怎么定以及上线后踩过的几个印象深刻的坑。如果你公司正好也有钉钉和金蝶云星空也想把审批报销的自动化流转做起来这篇应该能帮你少走不少弯路。1. 先说清楚这套对接要解决的是财务转录这个老麻烦1.1 每月几百张报销单财务转录为什么总出问题在大中型企业里钉钉审批流和金蝶云星空往往是两套独立运行的系统。钉钉负责发起报销、走审批金蝶负责记账、结算、出报表。两边互不相通报销数据要从钉钉到金蝶只能靠财务人员照着审批单重新录入。这个过程至少有三个问题。第一是重复劳动按每月400张报销单算每张录入加核对至少5分钟一天就有两三个小时耗在纯录入上。第二是转录错误报销金额、费用项目、承担部门这些字段肉眼看着抄一遍一个月下来总会出几笔差异最头疼的是金额录错一位小数账怎么都对不上。第三是时间滞后审批通过后往往要等财务有空才录月初月末集中处理时积压一堆报销周期被无限拉长员工天天催。这三件事单独拿出来都像小问题但合在一起就是财务月底加班的常态也是业务部门对财务报销慢抱怨的来源。1.2 自动化真正改变的三个环节把这个对接做成后改变的核心在三个环节。审批结束后数据自动流转不需要财务手工重新录。钉钉审批一通过回调服务立刻感知到事件拉取审批详情再调用金蝶云星空WebAPI把报销单写入ERP整个过程从原来的几分钟到几小时压缩到几十秒。数据全程可追溯。金蝶生成的单据上会带上钉钉审批实例ID和审批单号以后不管是财务查账还是审计追溯都能从ERP凭证一路找回到钉钉原始审批单再也不用靠人工在那张Excel里翻来翻去。错误率大幅下降。系统转录不会把金额看错也不会把费用项目选成相近的另一项字段经过映射规则处理后进入ERP的数据是一致的。1.3 方案边界什么场景适合自动化什么场景要保留人工这里必须泼一盆冷水。自动化不是要把所有财务单据都接到这条链路上。我梳理后把场景分了三类。适合完全自动化的是标准化的费用报销、差旅报销、日常请款这类单据字段清晰、审批规则明确映射规则可以稳定覆盖。需要半自动化的是涉及预算强控、多部门分摊、项目核算的单据这类业务建议先由系统自动带出大部分字段再由财务人工确认关键项后再入账。不适合自动化的是固定资产业务、成本归集、复杂往来核销这类单据业务变体太多硬做自动化很容易出现错误入账账务上处理起来更麻烦。要记住一个原则自动化解决的是转录和流转的效率问题而不是审核问题。钉钉审批环节的人工审核一步都不能省。2. 选型复盘为什么最终放弃RPA和中间件选择API直连2.1 三条路线摆在一起对比当时摆在面前的有三条技术路线我挨个做了一轮评估最终才定了API直连。方案开发量稳定性维护成本灵活性API直连自建服务中等对开发有要求高全链路可监控低接口稳定高业务规则可编码RPA模拟操作低靠录制脚本低UI一变就挂高脚本经常要修低只能按固定流程走集成中间件/低代码低到中依赖平台稳定性中按单据量计费中受平台字段模型限制RPA当时看上去最省事不用碰接口文档录个脚本就能模拟人工操作金蝶客户端。但我很快就排除了。金蝶云星空客户端的界面元素换个版本就可能变按钮位置一变脚本就得重录。而且RPA没法在每一步写入的时候做业务校验出了问题定位也麻烦。低代码中间件方案也考虑过但问题是费用报销涉及字段映射、查询基础资料、幂等校验这些逻辑在低代码平台上表达起来很吃力还容易遇到平台自身字段模型的限制。2.2 API直连的两个关键前提API直连能成立是因为两边都提供了靠谱的开放能力。金蝶云星空自带标准的WebAPI接口支持登录鉴权、单据保存、基础资料查询。钉钉开放平台提供审批实例的创建、详情查询以及审批事件回调能力。有了这两个前提API直连就是最可控的方案。所有环节都能写日志出了问题能定位到具体是哪一边的问题。业务规则也能用代码表达得清清楚楚不需要依赖任何中间层的黑盒逻辑。2.3 全链路数据流从审批通过到ERP入账先把这个流程串一遍后面所有代码和配置都是为它服务的。钉钉端发起报销审批审批人全部通过后钉钉开放平台推送审批实例结束事件到我们的回调服务。回调服务先验证事件签名再解密消息判断审批结果为agree。接着调用钉钉的审批实例详情接口把表单里填写的部门、费用项目、金额、收款账号等字段取出来。然后通过一套映射关系把钉钉的业务字符串转换成金蝶能识别的编码调用金蝶云星空WebAPI的保存接口在ERP里生成一张报销单。最后把处理结果记录下来并回写一条消息到钉钉审批单的评论里让发起人知道已自动推送ERP。整个链路看下来中间最核心的就是回调服务它是钉钉和金蝶之间的翻译器和搬运工。3. 金蝶云星空侧WebAPI授权、账套与单据准备3.1 先搞清楚金蝶云星空WebAPI的访问方式金蝶云星空的WebAPI从形态上看是一组HTTP POST接口基地址一般是金蝶服务器的公网或内网地址加端口核心路径固定。登录用的是AuthService路径下的ValidateUser接口业务操作走DynamicFormService路径下的Save、ExecuteBillQuery等接口。它跟很多RESTful风格接口不一样请求体是一个大JSON里面有固定的几个顶层字段比如creator、needUpDateFields、needReturnFields、modelmodel里放的是目标单据各个字段的值。刚开始做对接时我最容易犯的错是去记标准HTTP接口应该怎么设计实际上金蝶这套接口有自己的调用约定照着它的约定来就行不要试图改成REST风格。3.2 创建专属API用户并分配单据权限金蝶侧最重要的事不是写代码而是先把权限设计好。绝对不能拿administrator这种超级管理员账号去跑自动化。应该创建独立的API调用用户按最小权限原则分配。实际操作中我给这个API用户分配了三类权限费用报销单的新增和保存权限、付款单的查询权限、基础资料部门、费用项目、供应商、银行账号的查询权限。这样即使调用逻辑出了问题也只会影响报销单的新增范围不会把其他业务搞乱。数据中心ID这个东西很容易被忽略它在登录接口里是必填的代表金蝶里某一个实际账套。如果公司有多套账一定要在代码配置里区分清楚别把报销单写到了错误的账套里。3.3 用Postman完成一次登录和保存接口联调正式写代码之前先用Postman把两个接口调通可以省掉后面很多联调时间。第一步是登录。向ValidateUser接口发送POST请求请求体包含数据中心ID、用户名、密码。密码在金蝶WebAPI里通常要求做RSA加密具体要看你们的接口版本我这边是通过金蝶提供的说明拿到了加密方式。登录成功后返回一个sessionId这个sessionId就是后续调用业务接口的凭证。第二步是拿sessionId调用一次ExecuteBillQuery把费用项目列表查出来确认基础资料接口通。第三步是构造一个最简的Save请求体手动把一张测试报销单写进金蝶验证字段模型和必填项。这一步一定要亲自做一遍因为你只有在真实环境里试过才能知道金蝶这个版本的单据到底哪些字段必填哪些字段有默认值哪些字段值必须关联基础资料内的实体。4. 钉钉侧审批模板、事件回调与安全解密4.1 审批模板设计直接影响下游字段映射钉钉这边的起点是审批模板设计。很多人以为审批模板是行政的事做对接才发现模板字段设计得不好下游代码就得多写一堆恶心的兼容逻辑。设计报销审批模板的时候第一时间把业务上需要的字段都显式加进去包括报销事由、报销部门、费用项目、报销金额、收款人姓名、收款银行、收款账号、备注。一个字段对应一个控件别图省事让员工把所有信息填在一大段正文里那样下游解析起来非常痛苦。钉钉审批表单里的每个控件都有唯一的控件ID一般在设计表单时自动生成。对接代码里解析详情时拿到的就是控件ID到值的映射拿到之后再去跟中文标题关联。所以模板里每个字段的标题要稳定不要频繁改标题文字否则映射关系会断裂。4.2 订阅审批事件HTTP回调与Stream模式怎么选钉钉开放平台支持两种事件接收方式这里重点说一下怎么选。传统方式是HTTP回调需要在公网有一个可访问的URL钉钉把加密消息POST到这个URL上。适合本身就有公网入口或者网关的企业实现直观排查问题方便。另一种是Stream模式这是钉钉后来推出的方式服务端主动建立长连接不需要公网回调地址。对于部署在公司内网的场景特别友好不用为安全审批伤脑筋。缺陷是通信模式和HTTP时代不一样有些旧有的中间件平台支持不好。我当时因为公司服务部署在云上、有现成的网关入口选的是HTTP回调。如果你公司网络条件复杂优先考虑Stream模式省去一大堆内网穿透和防火墙配置的麻烦。4.3 回调验签与AES解密以及必须响应的固定格式钉钉HTTP回调的消息安全性做得比较严格。推送过来的请求里有四个关键参数msg_signature、timeStamp、nonce、encrypt。加密方式是对称AES加密密钥是应用创建时生成的AES Key同时每个应用还有自己的AppKey和AppSecret。收到回调后必须做的事有两件先验签确保消息确实来自钉钉再解密拿到真正的JSON消息体。钉钉官方SDK里已经封装好了加解密工具类直接用就行不建议自己实现加密算法很容易在编码和Padding上踩坑。这里有一个特别容易被忽略的坑处理完消息后必须在3秒内以纯文本形式返回字符串success注意是success这个单词不是JSON不是其他任何内容。如果超时返回或返回格式不对钉钉会判定投递失败并重试。5. 把关键代码写给你看从回调到入账的完整过程5.1 处理钉钉回调过滤事件类型、校验审批结果钉钉回调服务收到的消息并不止一种事件类型除了审批实例结束还有审批实例开始、审批转交、审批评论等。所以第一步是过滤事件类型。核心的EventType是bpms_instance_change而真正触发入账的是审批结果为agree同意。下面是示意代码。PostMapping(/dingtalk/callback) public String dingtalkCallback(RequestBody String body, RequestParam(signature) String signature, RequestParam(timestamp) String timestamp, RequestParam(nonce) String nonce) { // 1. 验证签名 CheckResult checkResult decryptMsg(signature, timestamp, nonce, body); if (!checkResult.isSuccess()) { return success; // 验签失败也返回success避免钉钉重试风暴 } JSONObject event JSON.parseObject(checkResult.getData()); String eventType event.getString(EventType); if (!bpms_instance_change.equals(eventType)) { return success; } String processInstanceId event.getString(processInstanceId); String result event.getString(result); // 2. 只有审批结果为 agree 才走后续入账逻辑 if (agree.equals(result)) { reimburseService.processApproved(processInstanceId); } return success; }注意验签失败时也要返回success这个细节是我踩出来的经验否则恶意请求或者消息错乱会触发钉钉无穷尽的重试。5.2 拉取审批实例详情解析表单数据收到审批实例结束事件后接下来要调钉钉的processinstance/get接口拿完整实例详情。这里要注意接口查询有权限限制调用的应用必须拥有审批的读取权限并且要配置为被审批流程使用。拿到返回结果后最关心的字段是form_component_values它是一个数组每一项包含控件ID、控件名称和值。解析时把它们塞进Map再根据业务需要取出来。public ReimburseModel getProcessDetail(String processInstanceId) { MapString, Object params new HashMap(); params.put(process_instance_id, processInstanceId); DingTalkClient client new DingTalkClient(); JSONObject resp client.execute(/topapi/processinstance/get, params); JSONObject processInstance resp.getJSONObject(process_instance); String title processInstance.getString(title); String status processInstance.getString(status); ReimburseModel model new ReimburseModel(); model.setTitle(title); model.setInstanceId(processInstanceId); model.setApplicant(processInstance.getJSONObject(originator_userid).getString(userid)); JSONArray formValues processInstance.getJSONArray(form_component_values); for (int i 0; i formValues.size(); i) { JSONObject item formValues.getJSONObject(i); String name item.getString(name); String value item.getString(value); switch (name) { case 报销部门: model.setDeptName(value); break; case 费用项目: model.setFeeItemName(value); break; case 报销金额: model.setAmount(new BigDecimal(value)); break; case 收款人: model.setPayee(value); break; case 收款账号: model.setAccountNo(value); break; } } return model; }这一步看着简单但有一个很关键的坑钉钉审批单里的金额字段在草稿和某些条件下可能是字符串一定要拿到值后先做清洗去掉空格和可能的逗号分隔符再转成BigDecimal。5.3 构造金蝶云星空保存参数调用WebAPI拿到业务数据后最关键的一步是构造金蝶云星空的Save请求体。下面是核心代码片段。public String saveReimburseToK3Cloud(ReimburseModel model) { HttpHeaders headers new HttpHeaders(); headers.setContentType(MediaType.APPLICATION_JSON); headers.set(X-Auth-Token, k3SessionHolder.getSessionId()); JSONObject body new JSONObject(); body.put(creator, api_user); body.put(needUpDateFields, new JSONArray()); body.put(needReturnFields, new JSONArray().put(FBillNo)); JSONObject modelObj new JSONObject(); modelObj.put(FBillTypeID, new JSONObject().put(FNumber, EXP01)); modelObj.put(FDate, DateUtil.formatDate(model.getBizDate())); modelObj.put(FOrgID, new JSONObject().put(FNumber, deptMapping.getOrgNumber(model.getDeptName()))); modelObj.put(FCreateOrgID, new JSONObject().put(FNumber, deptMapping.getOrgNumber(model.getDeptName()))); modelObj.put(F_ContractType, 钉钉报销); modelObj.put(F_Remark, 钉钉审批单号: model.getInstanceId()); // 费用明细 JSONArray entryRows new JSONArray(); JSONObject entry new JSONObject(); entry.put(FEntryAmount, model.getAmount()); entry.put(FExpenseItemID, new JSONObject().put(FNumber, feeMapping.getNumber(model.getFeeItemName()))); entry.put(F_Payee, model.getPayee()); entry.put(F_PayAccount, model.getAccountNo()); entryRows.add(entry); modelObj.put(FEntity, entryRows); body.put(model, modelObj); String url k3Config.getBaseUrl() /K3Cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.Save.common.kdsvc; ResponseEntityString resp restTemplate.postForEntity(url, new HttpEntity(body, headers), String.class); return parseBillNo(resp.getBody()); }金蝶云星空的字段有两种形式。一种直接传基本类型值一种必须传带FNumber的对象指向基础资料。这类关联型字段在保存时如果直接传字符串大概率会报字段校验错误。5.4 幂等控制防止同一单被重复写入ERP这里单独拿出来讲因为它太重要了。对接上线后一定会遇到重试场景比如金蝶接口超时后我们重试或者钉钉回调推送重复。一旦没有幂等控制同一张审批单就会被写入两次账上直接出现双倍报销。我的做法是设计一张关联表字段至少包括审批实例ID、审批单号、金蝶单据编号、处理状态、处理时间、失败原因。在处理回调时先查表如果同一审批实例ID已经存在且状态为success直接跳过。如果状态为fail允许重试。同时在金蝶侧也留了一手把审批实例ID拼进单据里一个非必填的自定义文本字段中这样即使关联表数据丢失也能在金蝶里通过查询这个字段来判断是否已入账。双保险踏实很多。6. 字段映射与业务规则业务语言到财务语言的转换6.1 一张可以直接改来用的映射表对接的本质是让两套系统的字段语义对齐。钉钉表单里员工写的IT部和金蝶ERP里维护的组织名称信息技术部不是一回事必须先建立映射关系。下面是我们当时的参考映射你可以根据自己的单子改。钉钉审批字段金蝶云星空单据字段映射说明报销申请人经办人F_Applicant从钉钉用户ID关联到金蝶员工编号报销部门报销部门F_PayOrgID按部门名称映射到金蝶组织编码费用项目费用项目FExpenseItemID按名称映射到金蝶费用项目编码报销金额费用金额FEntryAmount直接数值传递注意精度收款人收款人F_Payee文本字段直接传递收款账号收款账户F_PayAccount文本字段可做银行卡号校验报销事由摘要F_Remark拼接申请人、审批单号等信息钉钉审批实例ID自定义字段F_ReimburseSrcId用于幂等和对账追溯这个表是整条链路的灵魂后面无论排查问题还是调整业务都围绕它展开。6.2 部门与费用项目的基础资料映射部门和费用项目的映射是最需要维护成本的因为两个系统的基础资料编码规则完全不一样。钉钉的组织架构里是研发中心-后端组金蝶里的组织可能是研发部不建立映射就写不进ERP。我的做法是建一张数据库映射表名称就叫biz_mapping里面存的是来源系统、来源编码、目标系统、目标编码、状态。每次跑批前加载到内存缓存里避免每笔单子都查一次数据库。费用项目的映射有点不同因为钉钉表单里的费用项目往往是财务提前定义好的选项比如差旅费、业务招待费、办公用品费。这些选项在金蝶里可能对应到更细的科目比如差旅费在金蝶里区分了差旅费-市内交通、差旅费-长途差旅那需要在钉钉表单位维护的时候就做层级映射。这属于业务定义问题开发同学要拉着财务一起把对照关系确认好不要自己拍脑袋。6.3 金额精度、日期格式、摘要拼接的隐藏问题金额精度是我们踩过的坑。钉钉表单里员工填的金额可能是1000、1000.5、1,000.00进系统前必须统一转成decimal并保留两位小数。如果直接按字符串传给金蝶后面做费用分摊时可能出现精度不一致。金蝶侧的标准做法是由WebAPI在保存时自动做金额计算但我们传进去的必须已经是BigDecimal类型而不是字符串。日期格式也要小心钉钉接口返回的时间是毫秒时间戳金蝶的日期字段接受yyyy-MM-dd格式。中间如果不做转换金蝶会把一堆数字当成日期轻则保存失败重则生成一张日期错乱的单据。摘要我建议用固定模板拼接比如差旅费-张三-2025年3月深圳出差-钉钉单号xxx。固定模板的好处是对账和查旧账时看到的格式永远一致搜索起来也舒服。7. 上线之后的实战排坑我踩过的四个真坑7.1 审批结束事件到了但审批实例还没归档这是上线当天就遇到的坑。钉钉推送了bpms_instance_change事件result为agree我立刻去调processinstance/get接口拉详情发现返回的status居然还是running表单数据也不全。后来翻了文档才明白审批结束事件发出的时候钉钉内部还在做归档操作实例状态不是马上变成complete的。解决方式是加一个小延迟。收到事件后不立即拉详情而是先确认事件里带过来的审批结果字段再往异步队列里丢一个延迟任务比如3到5秒后再去拉详情。如果还是没归档完成就重试一次。上线至今没有因为这个再丢过单。7.2 金蝶会话过期与接口超时的处理金蝶WebAPI的登录sessionId是有有效期的默认不长。我们把sessionId放在了一个单机内存缓存里有效期设为与实际会话周期一致并在每次调用前检查剩余时间剩余不足1分钟就主动重新登录。这样能避免在跑大批量数据时突然遇到会话失效。另外金蝶接口偶发超时是常态尤其是月底所有人都在跑报表的时候。对保存接口一定要做重试但重试必须配合前面说的幂等控制否则超时后实际已写入重试就会产生重复单。重试策略我建议用指数退避加抖动第一次失败等2秒第二次4秒第三次8秒最多重试3次超过后进入人工待处理池。7.3 申请人换部门后单据归属错误有个月对账的时候发现好几笔报销单跑到了错误的部门费用里。排查后定位到根因钉钉表单里压根没有报销部门这个字段下游用的是申请人当前所处部门来做的映射。结果员工在审批期间从A部门调到了B部门系统拉详情时取到的是B部门报销费用就被计到了新部门头上。后来我们的修正动作有两条。第一在钉钉审批模板里显式增加报销部门下拉框员工发起时自己选择并且默认带出当前部门。第二下游映射只信任表单里的报销部门不再动态读取申请人组织架构。这个小改动让部门归属错误率直接归零。7.4 负数报销与金额精度问题第一次遇到负数报销的时候我们还以为数据出了问题。后来了解到是有员工提前借款垫付后续报销时冲销借款系统生成的是负数金额的单据。我们的第一版校验规则里有金额必须大于0把这类单子全部拦截了。修正方案是放行负数金额但在金额方向上做校验报销单金额绝对值不能超过预设上限超过的转人工。同时金蝶侧要确认费用项目是否允许负数入账有些科目在ERP里做了借贷方向限制负数单会直接保存失败这类情况只能走人工或者调整科目方向。8. 自动化上线后的日常运维日志、重试、对账与兜底8.1 链路日志设计让每一笔单子可追溯自动化跑起来之后最怕的就是出了错不知道去哪找。我强烈建议在回调服务里给每一笔处理请求生成一个全局唯一的traceId从钉钉回调开始就把它打进日志里后面每一步处理、每一次调用都带上它。同时在数据库里维护一张处理流水表字段包括traceId、审批实例ID、审批单号、事件类型、处理阶段、金蝶单据编号、是否成功、错误码、错误信息、耗时。这样遇到问题只需要在日志平台搜traceId就能把整条链路的执行轨迹拉出来。我们上线后前两个月排查问题的效率基本都是靠这张流水表撑起来的。没有它面对成百上千条日志真的会崩溃。8.2 失败重试机制与人工兜底界面再好的代码也会遇到脏数据、接口故障、字段配置错误。所以一定要设计兜底机制不能只会反复重试。我在后台维护了一张待处理任务表凡是在自动链路里失败次数超过3次的单子都会被标记为failed并推送到这个表里。管理页面上列出所有失败单展示钉钉审批单号、金蝶报错信息、失败原因运营或财务人员可以在这个页面上点击重试也可以手动修改参数后重试。这个机制在系统出问题的时候特别重要。有一次金蝶那边升级了下费用项目的配置导致我们所有的费用项目编码全部失效如果没有这个兜底界面几百张报销单就要积压到人工对着API文档哭了。8.3 月度自动对账怎么做自动化上线后不代表可以长期不核对。我建议每个月月初做一次自动对账逻辑其实不复杂钉钉侧查询上个月审批通过且结束的报销审批单统计数量、按费用项目分类汇总金额。金蝶侧查询上个月通过对接生成的所有报销单同样统计数量和金额。两边按审批实例ID关联比对有差异的单子输出到一张差异表推送给财务负责人。这个对账脚本我放在定时任务里每个月1号早上9点执行结果推送到钉钉部门群里。财务同事看到只有差异0笔的时候就是这套自动化真正发挥价值的时候。从决定做这个对接到现在我最大的体会是技术本身不复杂难的是把两套系统的业务语义对齐再把异常兜底做好。如果你也准备做类似的对接建议不要一上来就想全部单据都自动化选一类报销单先做试点跑一两个月稳定了再逐步扩展到其他场景。项目最怕的不是慢而是链路没走通之前就铺太大出了问题连定位都无从下手。
钉钉审批到金蝶云星空：报销单自动化流转的API对接实践
事情要从去年年底的财务对账说起。当时财务经理拿着一份Excel找我上面列了四十多笔差异钉钉里明明审批通过的报销单金蝶云星空系统里要么没有对应凭证要么金额对不上。原因大家心里都清楚同一个报销单钉钉审批走一遍流程财务还要在ERP里手工重新录一遍两边全靠人肉搬运中间环节一多不出错才是意外。那次对账之后我花了大半个月时间把钉钉审批通过→金蝶云星空自动生成报销凭证这条链路完整做通了。这篇文章就把整个方案摊开来讲包括选型时的纠结、两边的接口准备、核心代码怎么写、字段映射怎么定以及上线后踩过的几个印象深刻的坑。如果你公司正好也有钉钉和金蝶云星空也想把审批报销的自动化流转做起来这篇应该能帮你少走不少弯路。1. 先说清楚这套对接要解决的是财务转录这个老麻烦1.1 每月几百张报销单财务转录为什么总出问题在大中型企业里钉钉审批流和金蝶云星空往往是两套独立运行的系统。钉钉负责发起报销、走审批金蝶负责记账、结算、出报表。两边互不相通报销数据要从钉钉到金蝶只能靠财务人员照着审批单重新录入。这个过程至少有三个问题。第一是重复劳动按每月400张报销单算每张录入加核对至少5分钟一天就有两三个小时耗在纯录入上。第二是转录错误报销金额、费用项目、承担部门这些字段肉眼看着抄一遍一个月下来总会出几笔差异最头疼的是金额录错一位小数账怎么都对不上。第三是时间滞后审批通过后往往要等财务有空才录月初月末集中处理时积压一堆报销周期被无限拉长员工天天催。这三件事单独拿出来都像小问题但合在一起就是财务月底加班的常态也是业务部门对财务报销慢抱怨的来源。1.2 自动化真正改变的三个环节把这个对接做成后改变的核心在三个环节。审批结束后数据自动流转不需要财务手工重新录。钉钉审批一通过回调服务立刻感知到事件拉取审批详情再调用金蝶云星空WebAPI把报销单写入ERP整个过程从原来的几分钟到几小时压缩到几十秒。数据全程可追溯。金蝶生成的单据上会带上钉钉审批实例ID和审批单号以后不管是财务查账还是审计追溯都能从ERP凭证一路找回到钉钉原始审批单再也不用靠人工在那张Excel里翻来翻去。错误率大幅下降。系统转录不会把金额看错也不会把费用项目选成相近的另一项字段经过映射规则处理后进入ERP的数据是一致的。1.3 方案边界什么场景适合自动化什么场景要保留人工这里必须泼一盆冷水。自动化不是要把所有财务单据都接到这条链路上。我梳理后把场景分了三类。适合完全自动化的是标准化的费用报销、差旅报销、日常请款这类单据字段清晰、审批规则明确映射规则可以稳定覆盖。需要半自动化的是涉及预算强控、多部门分摊、项目核算的单据这类业务建议先由系统自动带出大部分字段再由财务人工确认关键项后再入账。不适合自动化的是固定资产业务、成本归集、复杂往来核销这类单据业务变体太多硬做自动化很容易出现错误入账账务上处理起来更麻烦。要记住一个原则自动化解决的是转录和流转的效率问题而不是审核问题。钉钉审批环节的人工审核一步都不能省。2. 选型复盘为什么最终放弃RPA和中间件选择API直连2.1 三条路线摆在一起对比当时摆在面前的有三条技术路线我挨个做了一轮评估最终才定了API直连。方案开发量稳定性维护成本灵活性API直连自建服务中等对开发有要求高全链路可监控低接口稳定高业务规则可编码RPA模拟操作低靠录制脚本低UI一变就挂高脚本经常要修低只能按固定流程走集成中间件/低代码低到中依赖平台稳定性中按单据量计费中受平台字段模型限制RPA当时看上去最省事不用碰接口文档录个脚本就能模拟人工操作金蝶客户端。但我很快就排除了。金蝶云星空客户端的界面元素换个版本就可能变按钮位置一变脚本就得重录。而且RPA没法在每一步写入的时候做业务校验出了问题定位也麻烦。低代码中间件方案也考虑过但问题是费用报销涉及字段映射、查询基础资料、幂等校验这些逻辑在低代码平台上表达起来很吃力还容易遇到平台自身字段模型的限制。2.2 API直连的两个关键前提API直连能成立是因为两边都提供了靠谱的开放能力。金蝶云星空自带标准的WebAPI接口支持登录鉴权、单据保存、基础资料查询。钉钉开放平台提供审批实例的创建、详情查询以及审批事件回调能力。有了这两个前提API直连就是最可控的方案。所有环节都能写日志出了问题能定位到具体是哪一边的问题。业务规则也能用代码表达得清清楚楚不需要依赖任何中间层的黑盒逻辑。2.3 全链路数据流从审批通过到ERP入账先把这个流程串一遍后面所有代码和配置都是为它服务的。钉钉端发起报销审批审批人全部通过后钉钉开放平台推送审批实例结束事件到我们的回调服务。回调服务先验证事件签名再解密消息判断审批结果为agree。接着调用钉钉的审批实例详情接口把表单里填写的部门、费用项目、金额、收款账号等字段取出来。然后通过一套映射关系把钉钉的业务字符串转换成金蝶能识别的编码调用金蝶云星空WebAPI的保存接口在ERP里生成一张报销单。最后把处理结果记录下来并回写一条消息到钉钉审批单的评论里让发起人知道已自动推送ERP。整个链路看下来中间最核心的就是回调服务它是钉钉和金蝶之间的翻译器和搬运工。3. 金蝶云星空侧WebAPI授权、账套与单据准备3.1 先搞清楚金蝶云星空WebAPI的访问方式金蝶云星空的WebAPI从形态上看是一组HTTP POST接口基地址一般是金蝶服务器的公网或内网地址加端口核心路径固定。登录用的是AuthService路径下的ValidateUser接口业务操作走DynamicFormService路径下的Save、ExecuteBillQuery等接口。它跟很多RESTful风格接口不一样请求体是一个大JSON里面有固定的几个顶层字段比如creator、needUpDateFields、needReturnFields、modelmodel里放的是目标单据各个字段的值。刚开始做对接时我最容易犯的错是去记标准HTTP接口应该怎么设计实际上金蝶这套接口有自己的调用约定照着它的约定来就行不要试图改成REST风格。3.2 创建专属API用户并分配单据权限金蝶侧最重要的事不是写代码而是先把权限设计好。绝对不能拿administrator这种超级管理员账号去跑自动化。应该创建独立的API调用用户按最小权限原则分配。实际操作中我给这个API用户分配了三类权限费用报销单的新增和保存权限、付款单的查询权限、基础资料部门、费用项目、供应商、银行账号的查询权限。这样即使调用逻辑出了问题也只会影响报销单的新增范围不会把其他业务搞乱。数据中心ID这个东西很容易被忽略它在登录接口里是必填的代表金蝶里某一个实际账套。如果公司有多套账一定要在代码配置里区分清楚别把报销单写到了错误的账套里。3.3 用Postman完成一次登录和保存接口联调正式写代码之前先用Postman把两个接口调通可以省掉后面很多联调时间。第一步是登录。向ValidateUser接口发送POST请求请求体包含数据中心ID、用户名、密码。密码在金蝶WebAPI里通常要求做RSA加密具体要看你们的接口版本我这边是通过金蝶提供的说明拿到了加密方式。登录成功后返回一个sessionId这个sessionId就是后续调用业务接口的凭证。第二步是拿sessionId调用一次ExecuteBillQuery把费用项目列表查出来确认基础资料接口通。第三步是构造一个最简的Save请求体手动把一张测试报销单写进金蝶验证字段模型和必填项。这一步一定要亲自做一遍因为你只有在真实环境里试过才能知道金蝶这个版本的单据到底哪些字段必填哪些字段有默认值哪些字段值必须关联基础资料内的实体。4. 钉钉侧审批模板、事件回调与安全解密4.1 审批模板设计直接影响下游字段映射钉钉这边的起点是审批模板设计。很多人以为审批模板是行政的事做对接才发现模板字段设计得不好下游代码就得多写一堆恶心的兼容逻辑。设计报销审批模板的时候第一时间把业务上需要的字段都显式加进去包括报销事由、报销部门、费用项目、报销金额、收款人姓名、收款银行、收款账号、备注。一个字段对应一个控件别图省事让员工把所有信息填在一大段正文里那样下游解析起来非常痛苦。钉钉审批表单里的每个控件都有唯一的控件ID一般在设计表单时自动生成。对接代码里解析详情时拿到的就是控件ID到值的映射拿到之后再去跟中文标题关联。所以模板里每个字段的标题要稳定不要频繁改标题文字否则映射关系会断裂。4.2 订阅审批事件HTTP回调与Stream模式怎么选钉钉开放平台支持两种事件接收方式这里重点说一下怎么选。传统方式是HTTP回调需要在公网有一个可访问的URL钉钉把加密消息POST到这个URL上。适合本身就有公网入口或者网关的企业实现直观排查问题方便。另一种是Stream模式这是钉钉后来推出的方式服务端主动建立长连接不需要公网回调地址。对于部署在公司内网的场景特别友好不用为安全审批伤脑筋。缺陷是通信模式和HTTP时代不一样有些旧有的中间件平台支持不好。我当时因为公司服务部署在云上、有现成的网关入口选的是HTTP回调。如果你公司网络条件复杂优先考虑Stream模式省去一大堆内网穿透和防火墙配置的麻烦。4.3 回调验签与AES解密以及必须响应的固定格式钉钉HTTP回调的消息安全性做得比较严格。推送过来的请求里有四个关键参数msg_signature、timeStamp、nonce、encrypt。加密方式是对称AES加密密钥是应用创建时生成的AES Key同时每个应用还有自己的AppKey和AppSecret。收到回调后必须做的事有两件先验签确保消息确实来自钉钉再解密拿到真正的JSON消息体。钉钉官方SDK里已经封装好了加解密工具类直接用就行不建议自己实现加密算法很容易在编码和Padding上踩坑。这里有一个特别容易被忽略的坑处理完消息后必须在3秒内以纯文本形式返回字符串success注意是success这个单词不是JSON不是其他任何内容。如果超时返回或返回格式不对钉钉会判定投递失败并重试。5. 把关键代码写给你看从回调到入账的完整过程5.1 处理钉钉回调过滤事件类型、校验审批结果钉钉回调服务收到的消息并不止一种事件类型除了审批实例结束还有审批实例开始、审批转交、审批评论等。所以第一步是过滤事件类型。核心的EventType是bpms_instance_change而真正触发入账的是审批结果为agree同意。下面是示意代码。PostMapping(/dingtalk/callback) public String dingtalkCallback(RequestBody String body, RequestParam(signature) String signature, RequestParam(timestamp) String timestamp, RequestParam(nonce) String nonce) { // 1. 验证签名 CheckResult checkResult decryptMsg(signature, timestamp, nonce, body); if (!checkResult.isSuccess()) { return success; // 验签失败也返回success避免钉钉重试风暴 } JSONObject event JSON.parseObject(checkResult.getData()); String eventType event.getString(EventType); if (!bpms_instance_change.equals(eventType)) { return success; } String processInstanceId event.getString(processInstanceId); String result event.getString(result); // 2. 只有审批结果为 agree 才走后续入账逻辑 if (agree.equals(result)) { reimburseService.processApproved(processInstanceId); } return success; }注意验签失败时也要返回success这个细节是我踩出来的经验否则恶意请求或者消息错乱会触发钉钉无穷尽的重试。5.2 拉取审批实例详情解析表单数据收到审批实例结束事件后接下来要调钉钉的processinstance/get接口拿完整实例详情。这里要注意接口查询有权限限制调用的应用必须拥有审批的读取权限并且要配置为被审批流程使用。拿到返回结果后最关心的字段是form_component_values它是一个数组每一项包含控件ID、控件名称和值。解析时把它们塞进Map再根据业务需要取出来。public ReimburseModel getProcessDetail(String processInstanceId) { MapString, Object params new HashMap(); params.put(process_instance_id, processInstanceId); DingTalkClient client new DingTalkClient(); JSONObject resp client.execute(/topapi/processinstance/get, params); JSONObject processInstance resp.getJSONObject(process_instance); String title processInstance.getString(title); String status processInstance.getString(status); ReimburseModel model new ReimburseModel(); model.setTitle(title); model.setInstanceId(processInstanceId); model.setApplicant(processInstance.getJSONObject(originator_userid).getString(userid)); JSONArray formValues processInstance.getJSONArray(form_component_values); for (int i 0; i formValues.size(); i) { JSONObject item formValues.getJSONObject(i); String name item.getString(name); String value item.getString(value); switch (name) { case 报销部门: model.setDeptName(value); break; case 费用项目: model.setFeeItemName(value); break; case 报销金额: model.setAmount(new BigDecimal(value)); break; case 收款人: model.setPayee(value); break; case 收款账号: model.setAccountNo(value); break; } } return model; }这一步看着简单但有一个很关键的坑钉钉审批单里的金额字段在草稿和某些条件下可能是字符串一定要拿到值后先做清洗去掉空格和可能的逗号分隔符再转成BigDecimal。5.3 构造金蝶云星空保存参数调用WebAPI拿到业务数据后最关键的一步是构造金蝶云星空的Save请求体。下面是核心代码片段。public String saveReimburseToK3Cloud(ReimburseModel model) { HttpHeaders headers new HttpHeaders(); headers.setContentType(MediaType.APPLICATION_JSON); headers.set(X-Auth-Token, k3SessionHolder.getSessionId()); JSONObject body new JSONObject(); body.put(creator, api_user); body.put(needUpDateFields, new JSONArray()); body.put(needReturnFields, new JSONArray().put(FBillNo)); JSONObject modelObj new JSONObject(); modelObj.put(FBillTypeID, new JSONObject().put(FNumber, EXP01)); modelObj.put(FDate, DateUtil.formatDate(model.getBizDate())); modelObj.put(FOrgID, new JSONObject().put(FNumber, deptMapping.getOrgNumber(model.getDeptName()))); modelObj.put(FCreateOrgID, new JSONObject().put(FNumber, deptMapping.getOrgNumber(model.getDeptName()))); modelObj.put(F_ContractType, 钉钉报销); modelObj.put(F_Remark, 钉钉审批单号: model.getInstanceId()); // 费用明细 JSONArray entryRows new JSONArray(); JSONObject entry new JSONObject(); entry.put(FEntryAmount, model.getAmount()); entry.put(FExpenseItemID, new JSONObject().put(FNumber, feeMapping.getNumber(model.getFeeItemName()))); entry.put(F_Payee, model.getPayee()); entry.put(F_PayAccount, model.getAccountNo()); entryRows.add(entry); modelObj.put(FEntity, entryRows); body.put(model, modelObj); String url k3Config.getBaseUrl() /K3Cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.Save.common.kdsvc; ResponseEntityString resp restTemplate.postForEntity(url, new HttpEntity(body, headers), String.class); return parseBillNo(resp.getBody()); }金蝶云星空的字段有两种形式。一种直接传基本类型值一种必须传带FNumber的对象指向基础资料。这类关联型字段在保存时如果直接传字符串大概率会报字段校验错误。5.4 幂等控制防止同一单被重复写入ERP这里单独拿出来讲因为它太重要了。对接上线后一定会遇到重试场景比如金蝶接口超时后我们重试或者钉钉回调推送重复。一旦没有幂等控制同一张审批单就会被写入两次账上直接出现双倍报销。我的做法是设计一张关联表字段至少包括审批实例ID、审批单号、金蝶单据编号、处理状态、处理时间、失败原因。在处理回调时先查表如果同一审批实例ID已经存在且状态为success直接跳过。如果状态为fail允许重试。同时在金蝶侧也留了一手把审批实例ID拼进单据里一个非必填的自定义文本字段中这样即使关联表数据丢失也能在金蝶里通过查询这个字段来判断是否已入账。双保险踏实很多。6. 字段映射与业务规则业务语言到财务语言的转换6.1 一张可以直接改来用的映射表对接的本质是让两套系统的字段语义对齐。钉钉表单里员工写的IT部和金蝶ERP里维护的组织名称信息技术部不是一回事必须先建立映射关系。下面是我们当时的参考映射你可以根据自己的单子改。钉钉审批字段金蝶云星空单据字段映射说明报销申请人经办人F_Applicant从钉钉用户ID关联到金蝶员工编号报销部门报销部门F_PayOrgID按部门名称映射到金蝶组织编码费用项目费用项目FExpenseItemID按名称映射到金蝶费用项目编码报销金额费用金额FEntryAmount直接数值传递注意精度收款人收款人F_Payee文本字段直接传递收款账号收款账户F_PayAccount文本字段可做银行卡号校验报销事由摘要F_Remark拼接申请人、审批单号等信息钉钉审批实例ID自定义字段F_ReimburseSrcId用于幂等和对账追溯这个表是整条链路的灵魂后面无论排查问题还是调整业务都围绕它展开。6.2 部门与费用项目的基础资料映射部门和费用项目的映射是最需要维护成本的因为两个系统的基础资料编码规则完全不一样。钉钉的组织架构里是研发中心-后端组金蝶里的组织可能是研发部不建立映射就写不进ERP。我的做法是建一张数据库映射表名称就叫biz_mapping里面存的是来源系统、来源编码、目标系统、目标编码、状态。每次跑批前加载到内存缓存里避免每笔单子都查一次数据库。费用项目的映射有点不同因为钉钉表单里的费用项目往往是财务提前定义好的选项比如差旅费、业务招待费、办公用品费。这些选项在金蝶里可能对应到更细的科目比如差旅费在金蝶里区分了差旅费-市内交通、差旅费-长途差旅那需要在钉钉表单位维护的时候就做层级映射。这属于业务定义问题开发同学要拉着财务一起把对照关系确认好不要自己拍脑袋。6.3 金额精度、日期格式、摘要拼接的隐藏问题金额精度是我们踩过的坑。钉钉表单里员工填的金额可能是1000、1000.5、1,000.00进系统前必须统一转成decimal并保留两位小数。如果直接按字符串传给金蝶后面做费用分摊时可能出现精度不一致。金蝶侧的标准做法是由WebAPI在保存时自动做金额计算但我们传进去的必须已经是BigDecimal类型而不是字符串。日期格式也要小心钉钉接口返回的时间是毫秒时间戳金蝶的日期字段接受yyyy-MM-dd格式。中间如果不做转换金蝶会把一堆数字当成日期轻则保存失败重则生成一张日期错乱的单据。摘要我建议用固定模板拼接比如差旅费-张三-2025年3月深圳出差-钉钉单号xxx。固定模板的好处是对账和查旧账时看到的格式永远一致搜索起来也舒服。7. 上线之后的实战排坑我踩过的四个真坑7.1 审批结束事件到了但审批实例还没归档这是上线当天就遇到的坑。钉钉推送了bpms_instance_change事件result为agree我立刻去调processinstance/get接口拉详情发现返回的status居然还是running表单数据也不全。后来翻了文档才明白审批结束事件发出的时候钉钉内部还在做归档操作实例状态不是马上变成complete的。解决方式是加一个小延迟。收到事件后不立即拉详情而是先确认事件里带过来的审批结果字段再往异步队列里丢一个延迟任务比如3到5秒后再去拉详情。如果还是没归档完成就重试一次。上线至今没有因为这个再丢过单。7.2 金蝶会话过期与接口超时的处理金蝶WebAPI的登录sessionId是有有效期的默认不长。我们把sessionId放在了一个单机内存缓存里有效期设为与实际会话周期一致并在每次调用前检查剩余时间剩余不足1分钟就主动重新登录。这样能避免在跑大批量数据时突然遇到会话失效。另外金蝶接口偶发超时是常态尤其是月底所有人都在跑报表的时候。对保存接口一定要做重试但重试必须配合前面说的幂等控制否则超时后实际已写入重试就会产生重复单。重试策略我建议用指数退避加抖动第一次失败等2秒第二次4秒第三次8秒最多重试3次超过后进入人工待处理池。7.3 申请人换部门后单据归属错误有个月对账的时候发现好几笔报销单跑到了错误的部门费用里。排查后定位到根因钉钉表单里压根没有报销部门这个字段下游用的是申请人当前所处部门来做的映射。结果员工在审批期间从A部门调到了B部门系统拉详情时取到的是B部门报销费用就被计到了新部门头上。后来我们的修正动作有两条。第一在钉钉审批模板里显式增加报销部门下拉框员工发起时自己选择并且默认带出当前部门。第二下游映射只信任表单里的报销部门不再动态读取申请人组织架构。这个小改动让部门归属错误率直接归零。7.4 负数报销与金额精度问题第一次遇到负数报销的时候我们还以为数据出了问题。后来了解到是有员工提前借款垫付后续报销时冲销借款系统生成的是负数金额的单据。我们的第一版校验规则里有金额必须大于0把这类单子全部拦截了。修正方案是放行负数金额但在金额方向上做校验报销单金额绝对值不能超过预设上限超过的转人工。同时金蝶侧要确认费用项目是否允许负数入账有些科目在ERP里做了借贷方向限制负数单会直接保存失败这类情况只能走人工或者调整科目方向。8. 自动化上线后的日常运维日志、重试、对账与兜底8.1 链路日志设计让每一笔单子可追溯自动化跑起来之后最怕的就是出了错不知道去哪找。我强烈建议在回调服务里给每一笔处理请求生成一个全局唯一的traceId从钉钉回调开始就把它打进日志里后面每一步处理、每一次调用都带上它。同时在数据库里维护一张处理流水表字段包括traceId、审批实例ID、审批单号、事件类型、处理阶段、金蝶单据编号、是否成功、错误码、错误信息、耗时。这样遇到问题只需要在日志平台搜traceId就能把整条链路的执行轨迹拉出来。我们上线后前两个月排查问题的效率基本都是靠这张流水表撑起来的。没有它面对成百上千条日志真的会崩溃。8.2 失败重试机制与人工兜底界面再好的代码也会遇到脏数据、接口故障、字段配置错误。所以一定要设计兜底机制不能只会反复重试。我在后台维护了一张待处理任务表凡是在自动链路里失败次数超过3次的单子都会被标记为failed并推送到这个表里。管理页面上列出所有失败单展示钉钉审批单号、金蝶报错信息、失败原因运营或财务人员可以在这个页面上点击重试也可以手动修改参数后重试。这个机制在系统出问题的时候特别重要。有一次金蝶那边升级了下费用项目的配置导致我们所有的费用项目编码全部失效如果没有这个兜底界面几百张报销单就要积压到人工对着API文档哭了。8.3 月度自动对账怎么做自动化上线后不代表可以长期不核对。我建议每个月月初做一次自动对账逻辑其实不复杂钉钉侧查询上个月审批通过且结束的报销审批单统计数量、按费用项目分类汇总金额。金蝶侧查询上个月通过对接生成的所有报销单同样统计数量和金额。两边按审批实例ID关联比对有差异的单子输出到一张差异表推送给财务负责人。这个对账脚本我放在定时任务里每个月1号早上9点执行结果推送到钉钉部门群里。财务同事看到只有差异0笔的时候就是这套自动化真正发挥价值的时候。从决定做这个对接到现在我最大的体会是技术本身不复杂难的是把两套系统的业务语义对齐再把异常兜底做好。如果你也准备做类似的对接建议不要一上来就想全部单据都自动化选一类报销单先做试点跑一两个月稳定了再逐步扩展到其他场景。项目最怕的不是慢而是链路没走通之前就铺太大出了问题连定位都无从下手。
