钉钉审批流集成指南：事件驱动与API调用实现自动化审批

1. 从“手动审批”到“自动流转”：为什么我们需要调用钉钉审批流？

如果你在负责一个需要与钉钉审批打交道的业务系统，比如OA、ERP或者CRM，那么“调用审批流”这个需求迟早会找上门。想象一下这个场景：员工在你的业务系统里提交了一张采购申请单，点击“提交”按钮后，系统弹出一个提示：“请前往钉钉完成审批”。然后员工需要退出你的系统，打开钉钉，找到对应的审批模板，再把刚才填过的信息手动抄一遍提交。这体验有多割裂，流程效率就有多低下。更别提那些需要根据审批结果来触发后续动作的场景了，比如审批通过后自动创建采购订单、自动扣减预算，或者审批驳回后自动通知申请人修改。如果依赖人工在钉钉和业务系统之间来回同步状态，不仅容易出错，工作量也是巨大的。

所以，将业务系统与钉钉审批流打通，实现数据的自动提交和状态的自动同步，就成了提升企业数字化协作效率的关键一步。这不仅仅是技术上的“调用一个接口”，更是对业务流程的重塑。今天，我们就来深入聊聊钉钉官方推荐的审批流调用方式。官方推荐的方法，核心在于利用钉钉开放平台提供的“ 审批事件回调 ”与“ 审批实例接口 ”组合拳，实现业务系统与钉钉审批的深度、稳定集成。这种方式避免了早期一些开发者采用的“模拟登录”、“爬虫抓取”等不稳定方案，是钉钉生态内认可的标准做法。

2. 理解钉钉审批流集成的核心模型：事件驱动与主动查询

在动手写代码之前，我们必须先理解钉钉审批流集成的核心逻辑模型。官方推荐的模式，本质上是一个 “事件驱动 + 主动查询” 的混合架构。理解这一点，是成功集成的基石。

2.1 审批流的核心数据对象

首先，我们需要明确几个关键对象，它们构成了整个交互的数据基础：

1. 审批模板 ：在钉钉管理后台创建的审批表单，定义了审批的字段、流程和权限。每个模板有一个唯一的 process_code 。
2. 审批实例 ：用户发起一次审批后产生的一个具体实例，包含本次审批的所有表单数据、审批进度和最终结果。每个实例有一个唯一的 process_instance_id 。
3. 审批任务 ：审批流程中的一个节点，指向某个审批人。一个实例可能包含多个任务。

我们的集成，主要围绕“审批实例”的生命周期展开。

2.2 “事件驱动”：让钉钉主动通知我们

这是官方推荐模式的精髓。你的业务系统不需要像“巡逻兵”一样每隔几分钟就去钉钉问一遍：“有没有新的审批？有没有审批状态更新？”这样效率低，且对钉钉服务器不友好。

相反，你应该在钉钉开放平台为你创建的应用中，配置“ 审批事件订阅 ”。当钉钉内发生与你应用相关的审批事件时，钉钉服务器会主动向你的服务器发送一个HTTP POST请求（即回调）。主要的事件类型包括：

• bpms_instance_change ：审批实例状态变更。这是最核心的事件，涵盖了审批实例的 开始、结束、终止 等关键节点。
  • start ：有人发起了审批。
  • finish ：审批流程结束（包括 同意 和 拒绝 ）。
  • terminate ：审批被撤销。

当你的服务器收到这个回调时，你就知道有一件重要的审批事务发生了。回调信息里会包含关键的 process_instance_id 和事件类型。

为什么这是推荐的？ 因为它实时、高效、资源消耗低。你的系统处于“待命”状态，只在有事发生时被唤醒处理，这是典型的异步事件驱动架构，非常适合此类场景。

2.3 “主动查询”：获取完整的数据详情

事件回调就像一个“敲门声”，它告诉你“有事发生”，并给了你一个“线索”（ process_instance_id ）。但敲门声不会告诉你事情的详细经过。为了获取审批实例的完整信息，比如表单里具体填了哪些值、审批意见是什么、经过了哪些审批节点，你需要拿着这个 process_instance_id ，主动调用钉钉的开放API去查询。

核心的API是： /v1.0/workflow/processInstances/{process_instance_id} 。通过这个接口，你可以拉取到该审批实例的完整快照。

所以，完整的流程链条是： 钉钉发生审批事件 → 钉钉回调你的服务器 → 你的服务器解析事件，拿到实例ID → 你的服务器调用钉钉API，查询实例详情 → 你的业务系统根据详情数据执行后续逻辑（如更新数据库状态、触发业务流程）。

这个模型清晰地将“通知”和“取数”解耦，既保证了实时性，又保证了数据的完整性。

3. 环境准备与核心配置：避开第一个大坑

理论清晰后，我们开始实操。第一步的环境配置，就有不少细节需要注意，很多坑都埋在这里。

3.1 创建钉钉企业内部应用

你需要在钉钉开放平台创建一个“企业内部应用”，这是所有调用的身份凭证。

1. 登录开放平台 ：访问钉钉开放平台，使用企业管理员账号登录。
2. 创建应用 ：在“应用开发” -> “企业内部开发”中，选择“创建应用”，应用类型选择“小程序或H5微应用”即可（即使你不是做前端应用，这个类型也支持后端API调用）。
3. 获取凭证 ：创建成功后，记录下 AppKey 和 AppSecret 。这是你的应用访问钉钉API的“账号