钉钉流程页面对接

一、功能简介

本手册旨在指导企业管理员或开发人员如何将 钉钉OA系统中的审批流程和页面 与 第三方业务系统（如ERP、CRM、财务系统等）进行集成对接，实现统一入口操作、数据互通、流程联动等功能。通过对接，可以提升企业办公自动化水平，避免重复录入，增强跨系统协作效率。

二、适用场景

可在业务系统发起流程，调用钉钉官方OA审批相关接口创建钉钉OA审批流程，在钉钉端打开钉钉审批详情页处理流程。

三、业务流程

业务系统与钉钉端内的整体交互流程如下：

钉钉OA审批流程和页面对接的业务流程图，业务系统发起审批后在钉钉端内打开官方详情页处理并获取状态

四、实现效果

1、从业务系统发起流程，创建OA审批流程

业务系统调用钉钉OA审批接口，发起审批并自动创建钉钉OA审批流程：

2、从钉钉OA审批列表打开官方OA审批详情页审批

在钉钉OA审批列表点击审批单，打开官方详情页处理：

3、从钉钉待办打开官方OA审批详情页审批

在钉钉待办中心点击待办任务，同样打开官方详情页处理：

五、开发流程

企业内部应用与钉钉OA审批的接口交互流程如下：

企业内部应用与钉钉OA审批的接口交互时序图，涵盖模板创建、实例发起、审批操作与回调通知

接入流程简介

文档展示了创建一个企业内部应用，使用官方OA审批相关API，通过创建/更新官方审批模板、发起/撤销/评论审批实例、同意/拒绝/转交审批任务、上传/下载审批附件等API，以及官方OA审批实例/审批任务回调事件，实现业务系统发起，钉钉端内打开官方OA审批详情页进行集成的场景案例。

前提条件：完成 创建应用 的流程。步骤一：进入应用详情页，获取应用 Client ID 和 Client Secret；步骤二：申请接口权限，申请”OA审批”相应权限；步骤三：获取应用访问凭证 获取企业内部应用的accessToken。调用接口时，通过accessToken鉴权调用者身份；步骤四：调用OA审批相关API：

创建官方OA审批模板： 管理员可在OA管理后台手动操作创建；或业务系统调用新版服务端API- 创建或更新审批表单模板 接口，获取模板的唯一编码processCode。若没有保存接口返回的模板编码processCode，可登录钉钉管理后台查看获取；

审批模板的编码可在管理后台的模板设置中查看：

{
    "name": "使用钉钉OA审批流程和页面对接",
    "description": "可在业务系统发起流程，调用钉钉官方OA审批相关接口创建钉钉OA审批流程，在钉钉端打开钉钉审批详情页处理流程。",
    "templateConfig": {
        "disableStopProcessButton": false,
        "disableFormEdit": false,
        "disableHomepage": false,
        "hidden": false
    },
    "formComponents": [
        {
            "componentType": "TextField",
            "props": {
                "label": "单行输入框", // 控件标题
                "placeholder": "请输入", // 输入提示
                "componentId": "TextField_17EZKEGSOCTC0", // 控件id，表单内唯一，无业务语义
                "required": false, // 是否必填，默认非必填
                "bizAlias": "staffId" // 控件的业务标识，表单内唯一，与componentId二选一
            }
        },
        {
            "componentType": "TextareaField",
            "props": {
                "label": "多行输入框",
                "placeholder": "请输入多行文本内容，需要换行时请输入\r\n", // 输入提示
                "componentId": "TextareaField_17EZKEGSOCTC0",
                "required": false
            }
        },
        {
            "componentType": "NumberField",
            "props": {
                "label": "数字输入框",
                "placeholder": "请输入数字",
                "componentId": "NumberField_108PIFZM21F40",
                "required": false,
                "unit": "元", // 数字单位
                "defaultValue": "10" // 默认值
            }
        },
        {
            "componentType": "DDSelectField",
            "props": {
                "options": [ // 可选选项列表
                    {
                        "value": "选项1", // 选项显示名称
                        "key": "option_0" // 控件内唯一key，非必填，系统会默认生成
                    },
                    {
                        "value": "选项2",
                        "key": "option_1"
                    },
                    {
                        "value": "选项3",
                        "key": "option_2"
                    },
                    {
                        "key": "other", // 其他项特殊key
                        "value": "其它"
                    }
                ],
                "label": "单选框",
                "placeholder": "请选择",
                "componentId": "DDSelectField_14T8M4EKXAV40",
                "required": false
            }
        },
        {
            "componentType": "DDMultiSelectField",
            "props": {
                "options": [
                    {
                        "value": "选项1",
                        "key": "option_0"
                    },
                    {
                        "value": "选项2",
                        "key": "option_1"
                    },
                    {
                        "value": "选项3",
                        "key": "option_2"
                    },
                    {
                        "key": "other", // 其他项特殊key
                        "value": "其它"
                    }
                ],
                "label": "多选框",
                "placeholder": "请选择",
                "componentId": "DDMultiSelectField_1XJ7NG1GSD6O0",
                "required": false
            }
        },
        {
            "componentType": "DDDateField",
            "props": {
                "unit": "小时", // 日期格式，枚举值（小时、天）
                "format": "yyyy-MM-dd HH:mm", // 日期格式，非必填，小时对应yyyy-MM-dd HH:mm，天对应yyyy-MM-dd HH:mm
                "bizAlias": "",
                "label": "日期",
                "placeholder": "请选择",
                "componentId": "DDDateField_SQL0DF3MS9C0",
                "required": false,
                "defaultValue": "2021-12-21 17:46" // 默认值
            }
        },
        {
            "componentType": "DDDateRangeField",
            "props": {
                "unit": "小时",
                "format": "yyyy-MM-dd HH:mm",
                "bizAlias": "",
                "label": "[\"开始时间\",\"结束时间\"]",
                "placeholder": "请选择",
                "componentId": "DDDateRangeField_7MPG14N3OOO0",
                "duration": true, // 是否自动计算时长
                "required": false
            }
        },
        {
            "componentType": "TextNote",
            "props": {
                "link": "https://www.dingtalk.io/", // 超链接
                "notPrint": "0",
                "bizAlias": "",
                "componentId": "TextNote_13RP7230RAF40",
                "content": "说明文字" // 说明文字
            }
        },
        {
            "componentType": "PhoneField",
            "props": {
                "mode": "phone", // 枚举值：phone_tel：手机和固话、phone：手机、tel：固话
                "label": "电话",
                "placeholder": "请输入",
                "componentId": "PhoneField_Y0XWOX6ZP6O0",
                "required": false
            }
        },
        {
            "componentType": "DDPhotoField",
            "props": {
                "label": "图片",
                "componentId": "DDPhotoField_P50A0HMHB280",
                "required": false
            }
        },
        {
            "componentType": "MoneyField",
            "props": {
                "upper": "0", // 金额需要大写(0不大写，1需要大写)，默认需要大写
                "label": "金额（元）",
                "placeholder": "请输入金额",
                "componentId": "MoneyField_L1PP26ZDV400",
                "required": false
            }
        },
        {
            "componentType": "DDAttachment",
            "props": {
                "label": "附件",
                "componentId": "DDAttachment_18U4QTOWLMPS0",
                "required": false
            }
        },
        {
            "componentType": "InnerContactField",
            "props": {
                "label": "联系人",
                "placeholder": "请选择",
                "componentId": "InnerContactField_162USP4V1BC00",
                "choice": "1", //枚举值：1标识支持多选，0标识单选，默认为0
                "required": false,
                "bizAlias": ""
            }
        },
        {
            "componentType": "DepartmentField",
            "props": {
                "multiple": false, // 是否支持多选，true多选，false单选
                "label": "部门",
                "placeholder": "请选择",
                "componentId": "DepartmentField_1GY5JSPOCY000",
                "required": false
            }
        },
        {
            "componentType": "RelateField",
            "props": {
                "label": "关联审批单",
                "placeholder": "请选择",
                "componentId": "RelateField_5X1DL4KMKUW0",
                "required": false,
                "bizAlias": "",
                "availableTemplates": [ // 可被关联的审批模板列表，为空时表示可关联所有审批模板的实例数据
                    {
                        "name": "官方OA审批-POP-0328-日期区间7", // 可关联的审批表单名称
                        "processCode": "PROC-AF45DE4C-7520-4842-9128-EB7BD0A4EA85" // 可关联的审批表单formCode
                    }
                ]
            }
        },
        {
            "componentType": "AddressField",
            "props": {
                "addressModel": "district", // 枚举值,city省市,district省市区,street省市区-街道
                "bizAlias": "",
                "label": "省市区",
                "componentId": "AddressField_1P9H21H8R2LC0",
                "required": false
            }
        },
        {
            "componentType": "StarRatingField",
            "props": {
                "limit": 5, // 枚举值：5分制、10分制
                "label": "评分",
                "placeholder": "请输入",
                "componentId": "StarRatingField_10E5NHTA2W0G0",
                "required": false,
                "bizAlias": ""
            }
        },
        {
            "children": [ // 明细中的子控件列表，子控件列表遵循各控件属性标准
                {
                    "componentType": "TextField",
                    "props": {
                        "label": "单行输入框",
                        "placeholder": "请输入",
                        "componentId": "TextField_1UE1ZY1A28AO0",
                        "required": false
                    }
                },
                {
                    "componentType": "MoneyField",
                    "props": {
                        "payEnable": false,
                        "upper": "0",
                        "bizAlias": "",
                        "label": "金额（元）",
                        "placeholder": "请输入金额",
                        "componentId": "MoneyField_1S85G4YLMM5C0",
                        "required": false
                    }
                },
                {
                    "componentType": "NumberField",
                    "props": {
                        "unit": "元",
                        "payEnable": false,
                        "bizAlias": "",
                        "label": "数字输入框",
                        "placeholder": "请输入数字",
                        "componentId": "NumberField_1XP6AWG50SE80",
                        "required": false
                    }
                }
            ],
            "componentType": "TableField",
            "props": {
                "tableViewMode": "table", // 明细填写方式，枚举值：list：列表,table：表格
                "verticalPrint": true, // 明细打印方式，true：纵向 false：横向
                "statField": [ // 设置对数字、金额类控件进行总数统计
                    {
                        "componentId": "MoneyField_1S85G4YLMM5C0",
                        "label": "金额（元）"
                    },
                    {
                        "componentId": "NumberField_1XP6AWG50SE80",
                        "label": "数字输入框"
                    }
                ],
                "bizAlias": "",
                "label": "表格",
                "componentId": "TableField_1MLEPEAQSXHC0"
            }
        }
    ]
}

创建审批模板成功后，用户可以在钉钉OA审批管理后台，查看/编辑官方OA审批单模板、查看/搜索模板数据、导出/删除模板数据等；

发起官方OA审批实例： 用户可通过OA审批官方应用手动发起审批；或业务系统可根据模板编码processCode，调用新版服务端API- 发起审批实例 接口发起审批实例，获取审批实例instanceId；

{
    "processCode": "PROC-C512D64A-60F6-4F83-B708-xxx",
    "originatorUserId": "manager98xx",
    "deptId": -1,
    "microappAgentId": 348925476,
    "formComponentValues": [
        {
            "name": "日期",
            "value": "2021-08-17"
        },
        {
            "name": "[\"开始时间\",\"结束时间\"]",
            "value": "[\"2019-02-19\",\"2019-02-25\"]"
        },
        {
            "name": "身份证",
            "value": "xxxx"
        },
        {
            "name": "图片",
            "value": "[\"http://url1\",\"http://url2\",\"http://url3\"]"
        },
        {
            "name": "表格",
            "value": "[[{\"name\":\"单行输入框\",\"value\":\"[百度](https://www.baidu.com/)\"},{\"name\":\"数字输入框\",\"value\":\"100\"}]]"
        },
        {
            "name": "金额（元）",
            "value": "100"
        },
        {
            "name": "附件",
            "value": "[{\"spaceId\": \"163xxxx658\", \"fileName\": \"2644.JPG\", \"fileSize\": \"333\", \"fileType\": \"jpg\", \"fileId\": \"643xxxx140\"}]"
        },
        {
            "name": "省市区",
            "value": "北京,北京市,河东区"
        },
        {
            "name": "评分",
            "value": "5"
        },
        {
            "name": "文本框",
            "value": "文本框示例"
        }
    ],
    "approvers": [
        {
            "actionType": "NONE",
            "userIds": [
                "manager98xx"
            ]
        },
        {
            "actionType": "OR",
            "userIds": [
                "manager98xx"
            ]
        }
    ]
}

发起审批实例成功后，用户可进入钉钉OA审批中心，查看审批四大列表（待处理、已处理、已发起、我收到的）、搜索审批实例数据、执行审批等操作；
添加审批评论附件： 若需要添加审批评论附件，需先将文件上传至审批钉盘空间，再调用新版服务端API- 添加审批评论 接口。具体使用教程参考： 评论及撤销审批流：
1. 需先调用新版服务端API- 获取审批钉盘空间信息 接口，获取钉盘空间的上传权限，并获取审批钉盘空间spaceId；
2. 调用客户端JSAPI- 上传附件到钉盘/从钉盘选择文件 接口，获取文件基本信息，本流程示例使用 JSAPI Explorer 实现；
3. 获取审批钉盘空间spaceId后，可根据审批实例instanceId，调用新版服务端API- 添加审批评论 接口，实现审批单的添加评论操作。

{
    "commentUserId": "manager98xx",
    "processInstanceId": "DQ7-X2EESQunrozGEe_xxx",
    "text": "测试添加审批评论",
    "file": {
        "attachments": [
            {
                "spaceId": "817447xxx",
                "fileSize": "173404",
                "fileId": "6660150xxx",
                "fileName": "评论附件.jpg",
                "fileType": "jpg"
            }
        ],
        "photos": [
            "https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/9227796361/p352432.png"
        ]
    }
}

预览下载审批附件： 若需要预览/下载附件，可调用服务端API- 授权下载审批钉盘文件 接口、 授权预览审批附件 接口，进行审批钉盘文件的授权操作，再调用服务端API- 下载审批附件 接口，获取文件的链接downloadUri实现下载。具体使用教程参考： 审批附件的操作流程；
同意/拒绝审批任务： 审批人可通过钉钉OA审批中心、钉钉待办中心手动操作同意/拒绝审批任务；或业务系统根据审批实例instanceId，调用新版服务端API- 获取单个审批实例详情 接口，获取审批实例详情，获取审批任务各个任务节点信息taskId；

根据审批实例instanceId和相应的任务节点taskId信息，调用新版服务端API- 同意或拒绝审批任务 接口，实现审批任务的操作，所有审批节点同意后，则该审批单通过；

{
    "actionerUserId": "manager98xx",
    "processInstanceId": "fsTunaLIRyeRMrddA1YwZQ0964170020xxxx",
    "remark": "同意",
    "taskId": 8333450,
    "result": "agree",
    "file": {
        "attachments": [
            {
                "space_id": "817447xxxx",
                "file_size": "173404",
                "file_id": "6660150xxxx",
                "file_name": "评论附件.jpg",
                "file_type": "jpg"
            }
        ],
        "photos": [
            "https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/9227796361/p352432.png"
        ]
    }
}

撤销官方OA审批实例：查看审批后，若发现提交的审批单有误需撤销该审批实例，可根据审批实例instanceId，调用新版服务端API- 撤销审批实例，实现审批单的撤销操作；
{ "isSystem": true, "processInstanceId": "oKPAxjtgSP-AqeVTk-xxxx", "operatingUserId": "manager98xx", "remark": "撤销审批实例" }
审批单状态发生变化后，OA审批支持将 审批任务状态变化 和 审批实例状态变化 等回调事件推送至业务系统侧，可以让企业应用能够更深度地与钉钉平台集成，实现信息共享和业务协同。具体使用教程参考： 事件订阅操作指南。

六、使用接口

1、审批表单

API	说明	新版规范（新版服务端API）
创建或更新审批模板	创建或更新一个OA审批的流程表单模板，可指定表单控件列表并生成默认审批流程。	创建或更新审批表单模板
获取表单 schema	通过 processCode 获取对应表单的 schema 信息。	获取表单 schema
获取审批单流程中的节点信息	获取审批单流程中的节点信息。	获取审批单流程中的节点信息
获取指定用户可见的审批表单列表	根据员工的userid分页获取该用户可见的审批表单列表。	获取指定用户可见的审批表单列表
获取当前企业所有可管理的表单	获取当前企业所有可管理的审批表单。	获取当前企业所有可管理的表单

2、审批实例

API	说明	新版规范（新版服务端API）
发起审批实例	发起OA审批实例。	发起审批实例
获取单个审批实例详情	根据审批实例ID，获取审批实例详情。	获取单个审批实例详情
撤销审批实例	撤销发起的审批实例。	撤销审批实例
添加审批评论	对审批实例添加评论。	添加审批评论
获取审批实例ID列表	获取权限范围内的相关部门审批实例ID列表。	获取审批实例ID列表

3、审批钉盘空间&附件

API	说明	新版规范（新版服务端API）
获取审批钉盘空间信息	获取审批钉盘空间的ID并授予当前用户上传附件的权限。	获取审批钉盘空间信息
授权预览审批附件	授权预览审批附件。	授权预览审批附件
授权下载审批钉盘文件	根据钉盘空间spaceId和文件fileId对钉盘文件进行授权审批钉盘空间下载权限。	授权下载审批钉盘文件
下载审批附件	获取审批文件下载授权，并且生成下载链接。	下载审批附件

4、审批任务

API	说明	新版规范（新版服务端API）
同意或拒绝审批任务	根据指定模板ID、实例ID、审批节点ID和审批人，对单个审批任务进行处理。	同意或拒绝审批任务
获取用户待审批数量	根据用户的userid获取该用户待处理的审批数量。	获取用户待审批数量
转交OA审批任务	转交OA审批任务。	转交OA审批任务

5、审批回调事件

5.1 企业内部应用类型的回调事件

回调事件	说明	新版规范（新版服务端API）
审批实例开始、结束、终止、删除	当审批实例开始、结束、终止或删除时，钉钉服务器给开发者回调地址推送审批实例事件。	审批实例开始、结束、终止、删除
审批任务开始、结束、取消	当审批事件发生审批任务开始、结束或取消时，推送给订阅者的内容。	审批任务开始、结束、取消

5.2 第三方企业应用的回调事件

回调事件	说明	新版规范（新版服务端API）
审批实例状态变更(广播)	审批广播事件场景，归属于某个ISV或官方OA审批应用的审批单模板，有可能也需要授权给另外的ISV做系统集成，在通过授权获取审批实例数据jsapi获取企业授权后，针对已授权的审批模板，触发该审批单相应实例、任务状态变更后，会给已授权的ISV推送回调。	审批实例状态变更(广播)
审批任务状态变更(广播)	审批广播事件场景，归属于某个ISV或官方OA审批应用的审批单模板，有可能也需要授权给另外的ISV做系统集成，在通过授权获取审批实例数据jsapi获取企业授权后，针对已授权的审批模板，触发该审批单相应实例、任务状态变更后，会给已授权的ISV推送回调。	审批任务状态变更(广播)
审批实例状态变更(定向)	审批定向事件场景，ISV通过开放接口创建的官方OA审批，或用户在OA管理后台创建的”ISV套件”模板，此类场景下该审批模板是归属于ISV的，因此用户在钉钉侧或三方通过API触发相应实例、任务状态变更后，会给对应归属的ISV应用定向推送回调。	审批实例状态变更(定向)
审批任务状态变更(定向)	审批定向事件场景，ISV通过开放接口创建的官方OA审批，或用户在OA管理后台创建的”ISV套件”模板，此类场景下该审批模板是归属于ISV的，因此用户在钉钉侧或三方通过API触发相应实例、任务状态变更后，会给对应归属的ISV应用定向推送回调。	审批任务状态变更(定向)

快速上手

角色手册

管理员手册

进阶能力

一、功能简介

二、适用场景

三、业务流程

四、实现效果

1、从业务系统发起流程，创建OA审批流程

2、从钉钉OA审批列表打开官方OA审批详情页审批

3、从钉钉待办打开官方OA审批详情页审批

五、开发流程

接入流程简介

六、使用接口

1、审批表单

2、审批实例

3、审批钉盘空间&附件

4、审批任务

5、审批回调事件

5.1 企业内部应用类型的回调事件

5.2 第三方企业应用的回调事件

七、相关文档

流程中心开放方案

三方流程页面对接

​一、功能简介

​二、适用场景

​三、业务流程

​四、实现效果

​1、从业务系统发起流程，创建OA审批流程

​2、从钉钉OA审批列表打开官方OA审批详情页审批

​3、从钉钉待办打开官方OA审批详情页审批

​五、开发流程

​接入流程简介

​六、使用接口

​1、审批表单

​2、审批实例

​3、审批钉盘空间&附件

​4、审批任务

​5、审批回调事件

​5.1 企业内部应用类型的回调事件

​5.2 第三方企业应用的回调事件

​七、相关文档

流程中心开放方案

三方流程页面对接

一、功能简介

二、适用场景

三、业务流程

四、实现效果

1、从业务系统发起流程，创建OA审批流程

2、从钉钉OA审批列表打开官方OA审批详情页审批

3、从钉钉待办打开官方OA审批详情页审批

五、开发流程

接入流程简介

六、使用接口

1、审批表单

2、审批实例

3、审批钉盘空间&附件

4、审批任务

5、审批回调事件

5.1 企业内部应用类型的回调事件

5.2 第三方企业应用的回调事件

七、相关文档