> ## Documentation Index
> Fetch the complete documentation index at: https://help.dingtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.
# 钉钉流程页面对接
> 指导企业管理员与开发者将钉钉OA审批流程和页面与ERP、CRM、财务系统等第三方业务系统集成对接，实现统一入口、数据互通与流程联动。
## 一、功能简介
本手册旨在指导企业管理员或开发人员如何将 **钉钉OA系统中的审批流程和页面** 与 **第三方业务系统（如ERP、CRM、财务系统等）进行集成对接**，实现统一入口操作、数据互通、流程联动等功能。通过对接，可以提升企业办公自动化水平，避免重复录入，增强跨系统协作效率。
## 二、适用场景
可在业务系统发起流程，调用钉钉官方OA审批相关接口创建钉钉OA审批流程，在钉钉端打开钉钉审批详情页处理流程。
## 三、业务流程
业务系统与钉钉端内的整体交互流程如下：
## 四、实现效果
### 1、从业务系统发起流程，创建OA审批流程
业务系统调用钉钉OA审批接口，发起审批并自动创建钉钉OA审批流程：
### 2、从钉钉OA审批列表打开官方OA审批详情页审批
在钉钉OA审批列表点击审批单，打开官方详情页处理：
### 3、从钉钉待办打开官方OA审批详情页审批
在钉钉待办中心点击待办任务，同样打开官方详情页处理：
## 五、开发流程
企业内部应用与钉钉OA审批的接口交互流程如下：
### 接入流程简介
文档展示了创建一个企业内部应用，使用官方OA审批相关API，通过创建/更新官方审批模板、发起/撤销/评论审批实例、同意/拒绝/转交审批任务、上传/下载审批附件等API，以及官方OA审批实例/审批任务回调事件，实现业务系统发起，钉钉端内打开官方OA审批详情页进行集成的场景案例。
前提条件：完成 **创建应用** 的流程。
步骤一：进入应用详情页，获取应用 Client ID 和 Client Secret；
步骤二：申请接口权限，申请"OA审批"相应权限；
步骤三：获取应用访问凭证 **获取企业内部应用的accessToken**。调用接口时，通过accessToken鉴权调用者身份；
步骤四：调用OA审批相关API：
1. **创建官方OA审批模板：** 管理员可在OA管理后台手动操作创建；或业务系统调用新版服务端API- **创建或更新审批表单模板** 接口，获取模板的唯一编码`processCode`。若没有保存接口返回的模板编码`processCode`，可登录钉钉管理后台查看获取；
审批模板的编码可在管理后台的模板设置中查看：
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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"
}
}
]
}
```
2. 创建审批模板成功后，用户可以在钉钉OA审批管理后台，查看/编辑官方OA审批单模板、查看/搜索模板数据、导出/删除模板数据等；
3. **发起官方OA审批实例：** 用户可通过OA审批官方应用手动发起审批；或业务系统可根据模板编码`processCode`，调用新版服务端API- **发起审批实例** 接口发起审批实例，获取审批实例`instanceId`；
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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"
]
}
]
}
```
4. 发起审批实例成功后，用户可进入钉钉OA审批中心，查看审批四大列表（待处理、已处理、已发起、我收到的）、搜索审批实例数据、执行审批等操作；
5. **添加审批评论附件：** 若需要添加审批评论附件，需先将文件上传至审批钉盘空间，再调用新版服务端API- **添加审批评论** 接口。具体使用教程参考： **评论及撤销审批流**：
1. 需先调用新版服务端API- **获取审批钉盘空间信息** 接口，获取钉盘空间的上传权限，并获取审批钉盘空间spaceId；
2. 调用客户端JSAPI- **上传附件到钉盘/从钉盘选择文件** 接口，获取文件基本信息，本流程示例使用 **JSAPI Explorer** 实现；
3. 获取审批钉盘空间spaceId后，可根据审批实例`instanceId`，调用新版服务端API- **添加审批评论** 接口，实现审批单的添加评论操作。
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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"
]
}
}
```
6. **预览下载审批附件：** 若需要预览/下载附件，可调用服务端API- **授权下载审批钉盘文件** 接口、 **授权预览审批附件** 接口，进行审批钉盘文件的授权操作，再调用服务端API- **下载审批附件** 接口，获取文件的链接`downloadUri`实现下载。具体使用教程参考： **审批附件的操作流程**；
7. **同意/拒绝审批任务：** 审批人可通过钉钉OA审批中心、钉钉待办中心手动操作同意/拒绝审批任务；或业务系统根据审批实例`instanceId`，调用新版服务端API- **获取单个审批实例详情** 接口，获取审批实例详情，获取审批任务各个任务节点信息`taskId`；
8. 根据审批实例`instanceId`和相应的任务节点`taskId`信息，调用新版服务端API- **同意或拒绝审批任务** 接口，实现审批任务的操作，所有审批节点同意后，则该审批单通过；
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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"
]
}
}
```
9. 撤销官方OA审批实例：查看审批后，若发现提交的审批单有误需撤销该审批实例，可根据审批实例`instanceId`，调用新版服务端API- **撤销审批实例**，实现审批单的撤销操作；
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"isSystem": true,
"processInstanceId": "oKPAxjtgSP-AqeVTk-xxxx",
"operatingUserId": "manager98xx",
"remark": "撤销审批实例"
}
```
10. 审批单状态发生变化后，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应用定向推送回调。 | **审批任务状态变更(定向)** |
## 七、相关文档
四种企业业务系统接入钉钉OA审批的方案总览
业务系统发起，钉钉端内打开业务系统详情页审批