# 创建审批定义

该接口用于创建审批定义，可以灵活指定审批定义的基础信息、表单和流程等。

## 使用限制

通过该 API 创建的审批定义，无法从审批管理后台或以 API 方式停用、删除，请谨慎调用。不推荐企业自建应用使用该 API 创建审批定义，如有需要，尽量联系企业管理员[在审批管理后台创建定义](https://www.feishu.cn/hc/zh-CN/articles/360040241113-%E7%AE%A1%E7%90%86%E5%91%98%E5%88%9B%E5%BB%BA%E5%AE%A1%E6%89%B9)。

## 请求

基本 |  
---|---
HTTP URL | https://open.feishu.cn/open-apis/approval/v4/approvals
HTTP Method | POST
接口频率限制 | [1000 次/分钟、50 次/秒](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
支持的应用类型 | Custom App、Store App
权限要求<br>**调用该 API 所需的权限。开启其中任意一项权限即可调用**<br>开启任一权限即可 | 查看、创建、更新、删除审批应用相关信息(approval:approval)<br>查看、创建、更新、删除原生审批定义相关信息(approval:definition)
字段权限要求 | **注意事项**：该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请<br>获取用户 user ID(contact:user.employee_id:readonly)

### 请求头

名称 | 类型 | 必填 | 描述
---|---|---|---
Authorization | string | 是 | `tenant_access_token`<br>**值格式**："Bearer `access_token`"<br>**示例值**："Bearer t-7f1bcd13fc57d46bac21793a18e560"<br>[了解更多：如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use)
Content-Type | string | 是 | **固定值**："application/json; charset=utf-8"

### 查询参数

名称 | 类型 | 必填 | 描述
---|---|---|---
department_id_type | string | 否 | 此次调用中使用的部门 ID 的类型。关于部门 ID 详细介绍参见[部门 ID 介绍](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview#9c02ed7a)。<br>**示例值**：open_department_id<br>**可选值有**：<br>- department_id：支持用户自定义配置的部门 ID。自定义配置时可复用已删除的 department_id，因此在未删除的部门范围内 department_id 具有唯一性。<br>- open_department_id：由系统自动生成的部门 ID，ID 前缀固定为 `od-`，在租户内全局唯一。
user_id_type | string | 否 | 用户 ID 类型<br>**示例值**：open_id<br>**可选值有**：<br>- open_id：标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。[了解更多：如何获取 Open ID](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-openid)<br>- union_id：标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。[了解更多：如何获取 Union ID？](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-union-id)<br>- user_id：标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。[了解更多：如何获取 User ID？](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-user-id)<br>**默认值**：`open_id`<br>**当值为 `user_id`，字段权限要求**：<br>获取用户 user ID(contact:user.employee_id:readonly)

### 请求体

名称 | 类型 | 必填 | 描述
---|---|---|---
approval_name | string | 是 | 审批名称的国际化文案 Key，以 `@i18n@` 开头，长度不得少于 9 个字符。<br>**示例值**："@i18n@approval_name"
approval_code | string | 否 | 审批定义 Code。使用说明：<br>- 该参数不传值时，表示新建审批定义，最终响应结果会返回由系统自动生成的审批定义 Code。<br>- 该参数传入指定审批定义 Code 时，表示调用该接口更新该审批定义内容，更新方式为覆盖原定义内容的全量更新。<br>审批定义 Code。获取方式：<br>- 调用[创建审批定义](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/approval/create)接口后，从响应参数 approval_code 获取。<br>- 登录审批管理后台，在指定审批定义的 URL 中获取，具体操作参见[什么是 Approval Code](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/approval/overview-of-approval-resources#8151e0ae)。<br>**示例值**："7C468A54-8745-2245-9675-08B7C63E7A85"
description | string | 否 | 审批描述的国际化文案 Key，以 `@i18n@` 开头，长度不得少于 9 个字符。<br>**示例值**："@i18n@description"
viewers | approval_create_viewers\[\] | 是 | viewers 字段指定了哪些人能从审批应用的前台发起该审批。使用说明：<br>- 当 viewer_type 为 USER，需要填写 viewer_user_id<br>- 当 viewer_type 为 DEPARTMENT，需要填写 viewer_department_id<br>- 当 viewer_type 为 TENANT 或 NONE 时，无需填写 viewer_user_id 和 viewer_department_id<br>**注意**：列表最大长度为 200。
viewer_type | string | 否 | 审批定义的可见范围<br>**示例值**："USER"<br>**可选值有**：<br>- TENANT：当前企业内可见<br>- DEPARTMENT：指定部门可见<br>- USER：指定用户可见<br>- NONE：任何人都不可见
viewer_user_id | string | 否 | 当 viewer_type 是 USER 时，需要通过该参数传入用户 ID，ID 类型与查询参数 user_id_type 取值一致。<br>**示例值**："19a294c2"
viewer_department_id | string | 否 | 当 viewer_type 为DEPARTMENT，需要通过该参数传入部门 ID，ID 类型与查询参数 department_id_type 取值一致。<br>**示例值**："od-ac9d697abfa990b715dcc33d58a62a9d"
form | approval_form | 是 | 审批定义表单
form_content | string | 是 | 审批定义表单。表单格式为 JSON 数组，实际传值时需要将 JSON 压缩转义为 String 类型。表单内各个控件的 JSON 字段说明参见[审批定义表单控件参数](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/approval/approval-definition-form-control-parameters)。<br>**注意**：以下示例值未转义，你可以参考下文**请求示例**章节的示例代码。<br>**示例值**："[{\"id\":\"user_name\", \"type\": \"input\", \"required\":true, \"name\":\"@i18n@widget1\"}]"
node_list | approval_node\[\] | 是 | 审批定义节点列表，用于设置审批流程所需要的各个节点，审批流程的始末固定为开始节点和结束节点，因此传值时需要将开始节点作为 list 第一个元素，结束节点作为 list 最后一个元素。<br>**说明**：API 方式不支持设置条件分支，如需设置条件分支请前往[飞书审批后台](https://www.feishu.cn/approval/admin/approvalList?devMode=on)创建审批定义。
id | string | 是 | 节点 ID。<br>- 开始节点的 ID 为 START<br>- 结束节点的 ID 为 END<br>开始和结束节点不需要指定 name、node_type 以及 approver。<br>**示例值**："START"
name | string | 否 | 节点名称的国际化文案 Key，以 `@i18n@` 开头，长度不得少于 9 个字符。<br>**示例值**："@i18n@node_name"
node_type | string | 否 | 当前节点的审批方式。<br>**注意**：当该参数取值为依次审批（SEQUENTIAL）时，审批人类型（approver.type）必须为发起人自选（Free）。<br>**示例值**："AND"<br>**可选值有**：<br>- AND：会签，需要所有审批人同意才会通过审批<br>- OR：或签，一名审批人同意即可通过审批<br>- SEQUENTIAL：依次审批，按照审批人顺序依次进行审批
approver | approval_approver_ccer\[\] | 否 | 审批人列表
type | string | 是 | 审批人类型。使用说明：<br>- 该参数取值为 Supervisor、SupervisorTopDown、DepartmentManager 、DepartmentManagerTopDown 这 4 种时，需要在 level 参数中填写对应的级数。例如：由下往上三级主管审批，该参数取值 Supervisor 、level 参数取值 3。<br>- 该参数取值为 Personal 时，需要填写对应的 user_id ，用于指定用户。<br>- 该参数取值为 Free 时，无需指定 user_id 和 level。<br>**示例值**："Supervisor"<br>**可选值有**：<br>- Supervisor：主管审批（由下往上）<br>- SupervisorTopDown：主管审批（从上往下）<br>- DepartmentManager：部门负责人审批（由下往上）<br>- DepartmentManagerTopDown：部门负责人审批（从上往下）<br>- Personal：指定成员<br>- Free：发起人自选
user_id | string | 否 | 用户 ID。<br>- type 取值 Personal 时需要通过该参数设置指定的用户。<br>- ID 类型与查询参数 user_id_type 取值一致。<br>**示例值**："f7cb567e"
level | string | 否 | 审批级数。当 type 取值为 Supervisor、SupervisorTopDown、DepartmentManager、DepartmentManagerTopDown 这 4 种时，需要在 level 中填写对应的级数。例如：由下往上三级主管审批，level 取值 3。<br>**示例值**："3"
ccer | approval_approver_ccer\[\] | 否 | 抄送人列表
type | string | 是 | 抄送人类型。使用说明：<br>- 该参数取值为 Supervisor、SupervisorTopDown、DepartmentManager 、DepartmentManagerTopDown 这 4 种时，需要在 level 参数中填写对应的级数。例如：抄送由下往上三级主管，该参数取值 Supervisor 、level 参数取值 3。<br>- 该参数取值为 Personal 时，需要填写对应的 user_id ，用于指定用户。<br>- 该参数取值为 Free 时，无需指定 user_id 和 level。<br>- 抄送人类型不支持设置为发起人自选（Free）。<br>**示例值**："Supervisor"<br>**可选值有**：<br>- Supervisor：主管审批（由下往上）<br>- SupervisorTopDown：主管审批（从上往下）<br>- DepartmentManager：部门负责人审批（由下往上）<br>- DepartmentManagerTopDown：部门负责人审批（从上往下）<br>- Personal：指定成员<br>- Free：发起人自选（抄送人类型不支持该选项）
user_id | string | 否 | 用户 ID。<br>- type 取值 Personal 时需要通过该参数设置指定的用户。<br>- ID 类型与查询参数 user_id_type 取值一致。<br>**示例值**："f7cb567e"
level | string | 否 | 审批级数。当 type 取值为 Supervisor、SupervisorTopDown、DepartmentManager 、DepartmentManagerTopDown 这 4 种时，需要在 level 中填写对应的级数。例如：抄送由下往上三级主管，level 取值 3。<br>**示例值**："3"
privilege_field | field_group | 否 | 表单内的控件权限
writable | string\[\] | 是 | 可写权限的表单控件项的 ID 列表，ID 需要与表单参数（form）内传入的控件 ID 值保持一致。<br>**示例值**：["user_name"]
readable | string\[\] | 是 | 可读权限的表单控件项的 ID 列表，ID 需要与表单参数（form）内传入的控件 ID 值保持一致。<br>**示例值**：["user_name"]
approver_chosen_multi | boolean | 否 | 发起人自选审批人时，是否允许多选。<br>- true：允许<br>- false：不允许<br>**示例值**：false
approver_chosen_range | approver_range\[\] | 否 | 发起人自选审批人时，可选择的范围。<br>**示例值**：[test]
type | string | 否 | 审批人类型<br>**示例值**："ALL"<br>**可选值有**：<br>- ALL：全企业<br>- PERSONAL：指定审批人<br>- ROLE：指定角色
id_list | string\[\] | 否 | ID 列表。<br>- 当 type 取值 ALL 时，无需传值。<br>- 当 type 取值 PERSONAL 时，传入用户 ID，ID 类型与 user_id_type 取值一致。<br>- 当 type 取值 ROLE 时，传入角色 ID。获取方式：成功[创建角色](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/functional_role/create)后，在返回结果中可获取角色 ID。<br>**示例值**：["f7cb567e"]
starter_assignee | string | 否 | 审批人为提交人本人时的操作<br>**示例值**："STARTER"<br>**可选值有**：<br>- STARTER：提交人本人进行审批<br>- AUTO_PASS：自动通过<br>- SUPERVISOR：提交人的直属上级进行审批<br>- DEPARTMENT_MANAGER：提交人的直属部门负责人进行审批
settings | approval_setting | 否 | 审批定义其他设置
revert_interval | int | 否 | 审批实例通过后允许撤回的时间，以秒为单位，默认 31 天，取值 0 为不可撤回。<br>**示例值**：0
revert_option | int | 否 | 是否支持审批通过第一个节点后撤回，默认为 1 表示支持，取值为 0 表示不支持。<br>**示例值**：0
reject_option | int | 否 | 审批被拒绝后的设置<br>**示例值**：0<br>**可选值有**：<br>- 0：默认设置，流程被终止<br>- 1：退回至发起人，发起人可编辑流程后重新提交
quick_approval_option | int | 否 | 快捷审批配置项，开启后可在卡片上直接审批。<br>**默认值**：1<br>**示例值**：1<br>**可选值有**：<br>- 0：禁用<br>- 1：启用<br>**默认值**：`1`
config | approval_config | 否 | 审批定义配置项，用于配置对应审批定义是否可以由用户在[审批后台](https://www.feishu.cn/approval/admin)进行修改。
can_update_viewer | boolean | 是 | 是否允许用户修改可见范围<br>**默认值**：false<br>**示例值**：false
can_update_form | boolean | 是 | 是否允许用户更新表单<br>**默认值**：false<br>**示例值**：false
can_update_process | boolean | 是 | 是否允许用户更新流程定义<br>**默认值**：false<br>**示例值**：false
can_update_revert | boolean | 是 | 是否允许用户更新撤回设置<br>**默认值**：false<br>**示例值**：false
help_url | string | 否 | 审批定义的帮助文档链接<br>**示例值**："https://xxx.xxx.xxx"
icon | int | 否 | 审批图标枚举，默认为 0。下图从左至右，从上到下依次为 0~24 号图标。<br>![icon.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/2c60da4397e18c0ae1fdf6bf50b36ad4_tQc0Lfgx4D.png?height=1080&lazyload=true&width=1066)<br>**示例值**：0<br>**默认值**：`0`
i18n_resources | i18n_resource\[\] | 是 | 国际化文案
locale | string | 是 | 语言。<br>**示例值**："zh-CN"<br>**可选值有**：<br>- zh-CN：中文<br>- en-US：英文<br>- ja-JP：日文
texts | i18n_resource_text\[\] | 是 | 文案的 key、value。<br>**示例值**：{ "@i18n@1": "权限申请", "@i18n@2": "OA审批", "@i18n@3": "Permission" }
key | string | 是 | 文案 key。key 以 `@i18n@` 开头，该字段主要用于做国际化，允许用户同时传多个语言的文案，审批中心会根据用户当前的语音环境使用对应的文案，如果没有传用户当前的语音环境文案，则会使用默认的语言文案。<br>**示例值**："@i18n@1"
value | string | 是 | 文案内容<br>**示例值**："people"
is_default | boolean | 是 | 是否为默认语言。默认语言需要包含所有 key，非默认语言如果 key 不存在会使用默认语言代替。<br>**示例值**：true
process_manager_ids | string\[\] | 否 | 审批流程管理员的用户 ID 列表。<br>- ID 类型与查询参数 user_id_type 取值一致<br>- 列表最大长度为 200<br>**示例值**：["1c5ea995"]

### 请求体示例
```json
{
    "approval_name": "@i18n@approval_name",
    "approval_code": "7C468A54-8745-2245-9675-08B7C63E7A85",
    "description": "@i18n@description",
    "viewers": [
        {
            "viewer_type": "USER",
            "viewer_user_id": "19a294c2",
            "viewer_department_id": "od-ac9d697abfa990b715dcc33d58a62a9d"
        }
    ],
    "form": {
        "form_content": "[{\"id\":\"user_name\", \"type\": \"input\", \"required\":true, \"name\":\"@i18n@widget1\"}]"
    },
    "node_list": [
        {
            "id": "START",
            "name": "@i18n@node_name",
            "node_type": "AND",
            "approver": [
                {
                    "type": "Supervisor",
                    "user_id": "f7cb567e",
                    "level": "3"
                }
            ],
            "ccer": [
                {
                    "type": "Supervisor",
                    "user_id": "f7cb567e",
                    "level": "3"
                }
            ],
            "privilege_field": {
                "writable": [
                    "user_name"
                ],
                "readable": [
                    "user_name"
                ]
            },
            "approver_chosen_multi": false,
            "approver_chosen_range": [
                {
                    "type": "ALL",
                    "id_list": [
                        "f7cb567e"
                    ]
                }
            ],
            "starter_assignee": "STARTER"
        }
    ],
    "settings": {
        "revert_interval": 0,
        "revert_option": 0,
        "reject_option": 0,
        "quick_approval_option": 1
    },
    "config": {
        "can_update_viewer": false,
        "can_update_form": false,
        "can_update_process": false,
        "can_update_revert": false,
        "help_url": "https://xxx.xxx.xxx"
    },
    "icon": 0,
    "i18n_resources": [
        {
            "locale": "zh-CN",
            "texts": [
                {
                    "key": "@i18n@1",
                    "value": "people"
                }
            ],
            "is_default": true
        }
    ],
    "process_manager_ids": [
        "1c5ea995"
    ]
}
```

## 响应

### 响应体

名称 | 类型 | 描述
---|---|---
code | int | 错误码，非 0 表示失败
msg | string | 错误描述
data | \- | \-
approval_code | string | 审批定义 Code。建议妥善保管该 Code，后续[查看指定审批定义](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/approval/get)、[创建审批实例](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/instance/create)等场景需要使用审批定义 Code。
approval_id | string | 审批定义 ID。

### 响应体示例
```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "approval_code": "81D31358-93AF-92D6-7425-01A5D67C4E71",
        "approval_id": "7090754740375519252"
    }
}
```

### 错误码

HTTP状态码 | 错误码 | 描述 | 排查建议
---|---|---|---
400 | 1390001 | param is invalid | 参数错误。排查方案：<br>- 根据接口文档的参数说明，检查请求时传入的参数是否正确。<br>- 如果传入的有表单参数（form），则需要检查该参数内传入的表单控件数据是否正确。如果报错信息内包含控件 ID（如 `控件= widget17261088448220001`），可以调用[查看指定审批定义](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/approval/get)或者[获取单个审批实例详情](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/instance/get)接口，获取响应参数 form 值，检索有问题的控件 ID，然后检查该控件的配置是否正确。
400 | 1390002 | approval code not found | 找不到审批定义 Code，检查传入的审批定义 Code 是否正确。<br>审批定义 Code 获取方式：<br>- 调用[创建审批定义](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/approval/create)接口后，从响应参数 approval_code 获取。<br>- 登录审批管理后台，在指定审批定义的 URL 中获取，具体操作参见[什么是 Approval Code](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/approval/overview-of-approval-resources#8151e0ae)。
400 | 1390003 | instance code not found | 找不到审批实例 Code，检查传入的审批实例 Code 是否正确。<br>审批实例 Code 获取方式：<br>- 调用[创建审批实例](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/instance/create)接口后，从响应参数 instance_code 获取。<br>- 调用[批量获取审批实例 ID](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/instance/list)接口，获取所需的审批实例 Code。<br>- 调用[查询实例列表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/instance/query)，设置过滤条件查询指定的审批实例 Code。
400 | 1390004 | user_id or open_id not found | 检查传入的 user_id 参数是否正确，user_id 的类型需要和 user_id_type 一致，且需要确保 ID 值正确。
403 | 1390009 | no operation permission | 没有操作权限。请前往[飞书审批管理后台](https://www.feishu.cn/approval/admin/approvalList)，进入指定审批定义编辑页面，在流程设计里的审批操作权限内，检查操作权限是否正确配置。
400 | 1390013 | unsupported approval for free process | 不支持自定义审批流程。
400 | 1390015 | approval is not active | 审批定义已停用，请确保当前所用的审批定义已启用后重试。你可以登录[飞书审批管理后台](https://www.feishu.cn/approval/admin/approvalList)，查看相应审批定义是否被停用。<br>![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/3991337412ec292a8f61d5c57a5d590b_MbHV5E0Qmr.png)
400 | 1395001 | There have been some errors. Please try again later | 服务出现错误。排查方案：<br>1. 参考接口文档的参数说明，检查请求时传入的参数是否正确。如果传入的有表单参数（form），则需要检查传入的表单控件数据是否正确。<br>2. 降低请求频率，并重试。如果重试仍然报错，请联系[技术支持](https://applink.feishu.cn/TLJpeNdW)。

更多错误码信息，参见[通用错误码](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN)。