飞书开放平台 Server API 文档

主题

创建审批定义 ​

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

使用限制 ​

通过该 API 创建的审批定义，无法从审批管理后台或以 API 方式停用、删除，请谨慎调用。不推荐企业自建应用使用该 API 创建审批定义，如有需要，尽量联系企业管理员在审批管理后台创建定义。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/approval/v4/approvals
HTTP MethodPOST
接口频率限制1000 次/分钟、50 次/秒
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可approval:approval 查看、创建、更新、删除审批应用相关信息 approval:definition 查看、创建、更新、删除原生审批定义相关信息
字段权限要求> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 contact:user.employee_id:readonly 获取用户 user ID

请求头 ​

名称类型必填描述
Authorizationstring是tenant_access_token 值格式："Bearer access_token" 示例值："Bearer t-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token
Content-Typestring是固定值："application/json; charset=utf-8"

查询参数 ​

名称类型必填描述
department_id_typestring否此次调用中使用的部门 ID 的类型。关于部门 ID 详细介绍参见部门 ID 介绍。
示例值：open_department_id
可选值有：
- department_id: 支持用户自定义配置的部门 ID。自定义配置时可复用已删除的 department_id，因此在未删除的部门范围内 department_id 具有唯一性。 - open_department_id: 由系统自动生成的部门 ID，ID 前缀固定为 od-，在租户内全局唯一。
user_id_typestring否用户 ID 类型
示例值：open_id
可选值有：
- open_id: 标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。了解更多：如何获取 Open ID - union_id: 标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。了解更多：如何获取 Union ID？ - user_id: 标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。了解更多：如何获取 User ID？
默认值：open_id
当值为 user_id，字段权限要求： contact:user.employee_id:readonly 获取用户 user ID

请求体 ​

名称类型必填描述
approval_namestring是审批名称的国际化文案 Key，以 @i18n@ 开头，长度不得少于 9 个字符。
示例值："@i18n@approval_name"
approval_codestring否审批定义 Code。使用说明：
- 该参数不传值时，表示新建审批定义，最终响应结果会返回由系统自动生成的审批定义 Code。 - 该参数传入指定审批定义 Code 时，表示调用该接口更新该审批定义内容，更新方式为覆盖原定义内容的全量更新。
审批定义 Code。获取方式：
- 调用创建审批定义接口后，从响应参数 approval_code 获取。 - 登录审批管理后台，在指定审批定义的 URL 中获取，具体操作参见什么是 Approval Code。
示例值："7C468A54-8745-2245-9675-08B7C63E7A85"
descriptionstring否审批描述的国际化文案 Key，以 @i18n@ 开头，长度不得少于 9 个字符。
示例值："@i18n@description"
viewersapproval_create_viewers\[\]是viewers 字段指定了哪些人能从审批应用的前台发起该审批。使用说明：
- 当 viewer_type 为 USER，需要填写 viewer_user_id
- 当 viewer_type 为 DEPARTMENT，需要填写 viewer_department_id
- 当 viewer_type 为 TENANT 或 NONE 时，无需填写 viewer_user_id 和 viewer_department_id
注意：列表最大长度为 200。
  └ viewer_typestring否审批定义的可见范围
示例值："USER"
可选值有：
- TENANT: 当前企业内可见 - DEPARTMENT: 指定部门可见 - USER: 指定用户可见 - NONE: 任何人都不可见
  └ viewer_user_idstring否当 viewer_type 是 USER 时，需要通过该参数传入用户 ID，ID 类型与查询参数 user_id_type 取值一致。
示例值："19a294c2"
  └ viewer_department_idstring否当 viewer_type 为DEPARTMENT，需要通过该参数传入部门 ID，ID 类型与查询参数 department_id_type 取值一致。
示例值："od-ac9d697abfa990b715dcc33d58a62a9d"
formapproval_form是审批定义表单
  └ form_contentstring是审批定义表单。表单格式为 JSON 数组，实际传值时需要将 JSON 压缩转义为 String 类型。表单内各个控件的 JSON 字段说明参见审批定义表单控件参数。
注意：以下示例值未转义，你可以参考下文请求示例章节的示例代码。
示例值："[{\"id\":\"user_name\", \"type\": \"input\", \"required\":true, \"name\":\"@i18n@widget1\"}]"
node_listapproval_node\[\]是审批定义节点列表，用于设置审批流程所需要的各个节点，审批流程的始末固定为开始节点和结束节点，因此传值时需要将开始节点作为 list 第一个元素，结束节点作为 list 最后一个元素。
说明：API 方式不支持设置条件分支，如需设置条件分支请前往飞书审批后台创建审批定义。
  └ idstring是节点 ID。
- 开始节点的 ID 为 START - 结束节点的 ID 为 END
开始和结束节点不需要指定 name、node_type 以及 approver。
示例值："START"
  └ namestring否节点名称的国际化文案 Key，以 @i18n@ 开头，长度不得少于 9 个字符。
示例值："@i18n@node_name"
  └ node_typestring否当前节点的审批方式。
注意：当该参数取值为依次审批（SEQUENTIAL）时，审批人类型（approver.type）必须为发起人自选（Free）。
示例值："AND"
可选值有：
- AND: 会签，需要所有审批人同意才会通过审批 - OR: 或签，一名审批人同意即可通过审批 - SEQUENTIAL: 依次审批，按照审批人顺序依次进行审批
  └ approverapproval_approver_ccer\[\]否审批人列表
    └ typestring是审批人类型。使用说明：
- 该参数取值为 Supervisor、SupervisorTopDown、DepartmentManager 、DepartmentManagerTopDown 这 4 种时，需要在 level 参数中填写对应的级数。例如：由下往上三级主管审批，该参数取值 Supervisor 、level 参数取值 3。
- 该参数取值为 Personal 时，需要填写对应的 user_id ，用于指定用户。
- 该参数取值为 Free 时，无需指定 user_id 和 level。
示例值："Supervisor"
可选值有：
- Supervisor: 主管审批（由下往上） - SupervisorTopDown: 主管审批（从上往下） - DepartmentManager: 部门负责人审批（由下往上） - DepartmentManagerTopDown: 部门负责人审批（从上往下） - Personal: 指定成员 - Free: 发起人自选
    └ user_idstring否用户 ID。
- type 取值 Personal 时需要通过该参数设置指定的用户。
- ID 类型与查询参数 user_id_type 取值一致。
示例值："f7cb567e"
    └ levelstring否审批级数。当 type 取值为 Supervisor、SupervisorTopDown、DepartmentManager、DepartmentManagerTopDown 这 4 种时，需要在 level 中填写对应的级数。例如：由下往上三级主管审批，level 取值 3。
示例值："3"
  └ ccerapproval_approver_ccer\[\]否抄送人列表
    └ typestring是抄送人类型。使用说明：
- 该参数取值为 Supervisor、SupervisorTopDown、DepartmentManager 、DepartmentManagerTopDown 这 4 种时，需要在 level 参数中填写对应的级数。例如：抄送由下往上三级主管，该参数取值 Supervisor 、level 参数取值 3。
- 该参数取值为 Personal 时，需要填写对应的 user_id ，用于指定用户。
- 该参数取值为 Free 时，无需指定 user_id 和 level。
- 抄送人类型不支持设置为发起人自选（Free）。
示例值："Supervisor"
可选值有：
- Supervisor: 主管审批（由下往上） - SupervisorTopDown: 主管审批（从上往下） - DepartmentManager: 部门负责人审批（由下往上） - DepartmentManagerTopDown: 部门负责人审批（从上往下） - Personal: 指定成员 - Free: 发起人自选（抄送人类型不支持该选项）
    └ user_idstring否用户 ID。
- type 取值 Personal 时需要通过该参数设置指定的用户。
- ID 类型与查询参数 user_id_type 取值一致。
示例值："f7cb567e"
    └ levelstring否审批级数。当 type 取值为 Supervisor、SupervisorTopDown、DepartmentManager 、DepartmentManagerTopDown 这 4 种时，需要在 level 中填写对应的级数。例如：抄送由下往上三级主管，level 取值 3。
示例值："3"
  └ privilege_fieldfield_group否表单内的控件权限
    └ writablestring\[\]是可写权限的表单控件项的 ID 列表，ID 需要与表单参数（form）内传入的控件 ID 值保持一致。
示例值：["user_name"]
    └ readablestring\[\]是可读权限的表单控件项的 ID 列表，ID 需要与表单参数（form）内传入的控件 ID 值保持一致。
示例值：["user_name"]
  └ approver_chosen_multiboolean否发起人自选审批人时，是否允许多选。
- true：允许 - false：不允许
示例值：false
  └ approver_chosen_rangeapprover_range\[\]否发起人自选审批人时，可选择的范围。
示例值：[test]
    └ typestring否审批人类型
示例值："ALL"
可选值有：
- ALL: 全企业 - PERSONAL: 指定审批人 - ROLE: 指定角色
    └ id_liststring\[\]否ID 列表。
- 当 type 取值 ALL 时，无需传值。 - 当 type 取值 PERSONAL 时，传入用户 ID，ID 类型与 user_id_type 取值一致。 - 当 type 取值 ROLE 时，传入角色 ID。获取方式：成功创建角色后，在返回结果中可获取角色 ID。
示例值：["f7cb567e"]
  └ starter_assigneestring否审批人为提交人本人时的操作
示例值："STARTER"
可选值有：
- STARTER: 提交人本人进行审批 - AUTO_PASS: 自动通过 - SUPERVISOR: 提交人的直属上级进行审批 - DEPARTMENT_MANAGER: 提交人的直属部门负责人进行审批
settingsapproval_setting否审批定义其他设置
  └ revert_intervalint否审批实例通过后允许撤回的时间，以秒为单位，默认 31 天，取值 0 为不可撤回。
示例值：0
  └ revert_optionint否是否支持审批通过第一个节点后撤回，默认为 1 表示支持，取值为 0 表示不支持。
示例值：0
  └ reject_optionint否审批被拒绝后的设置
示例值：0
可选值有：
- 0: 默认设置，流程被终止 - 1: 退回至发起人，发起人可编辑流程后重新提交
  └ quick_approval_optionint否快捷审批配置项，开启后可在卡片上直接审批。
默认值：1
示例值：1
可选值有：
- 0: 禁用 - 1: 启用
默认值：1
configapproval_config否审批定义配置项，用于配置对应审批定义是否可以由用户在审批后台进行修改。
  └ can_update_viewerboolean是是否允许用户修改可见范围
默认值：false
示例值：false
  └ can_update_formboolean是是否允许用户更新表单
默认值：false
示例值：false
  └ can_update_processboolean是是否允许用户更新流程定义
默认值：false
示例值：false
  └ can_update_revertboolean是是否允许用户更新撤回设置
默认值：false
示例值：false
  └ help_urlstring否审批定义的帮助文档链接
示例值："https://xxx.xxx.xxx"
iconint否审批图标枚举，默认为 0。下图从左至右，从上到下依次为 0~24 号图标。 icon.png
示例值：0
默认值：0
i18n_resourcesi18n_resource\[\]是国际化文案
  └ localestring是语言。
示例值："zh-CN"
可选值有：
- zh-CN: 中文 - en-US: 英文 - ja-JP: 日文
  └ textsi18n_resource_text\[\]是文案的 key、value。
示例值：{ "@i18n@1": "权限申请", "@i18n@2": "OA审批", "@i18n@3": "Permission" }
    └ keystring是文案 key。key 以 @i18n@ 开头，该字段主要用于做国际化，允许用户同时传多个语言的文案，审批中心会根据用户当前的语音环境使用对应的文案，如果没有传用户当前的语音环境文案，则会使用默认的语言文案。
示例值："@i18n@1"
    └ valuestring是文案内容
示例值："people"
  └ is_defaultboolean是是否为默认语言。默认语言需要包含所有 key，非默认语言如果 key 不存在会使用默认语言代替。
示例值：true
process_manager_idsstring\[\]否审批流程管理员的用户 ID 列表。
- ID 类型与查询参数 user_id_type 取值一致 - 列表最大长度为 200
示例值：["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"
    ]
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ approval_codestring审批定义 Code。建议妥善保管该 Code，后续查看指定审批定义、创建审批实例等场景需要使用审批定义 Code。
  └ approval_idstring审批定义 ID。

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "approval_code": "81D31358-93AF-92D6-7425-01A5D67C4E71",
        "approval_id": "7090754740375519252"
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
4001390001param is invalid参数错误。排查方案： - 根据接口文档的参数说明，检查请求时传入的参数是否正确。 - 如果传入的有表单参数（form），则需要检查该参数内传入的表单控件数据是否正确。如果报错信息内包含控件 ID（如 控件= widget17261088448220001），可以调用查看指定审批定义或者获取单个审批实例详情接口，获取响应参数 form 值，检索有问题的控件 ID，然后检查该控件的配置是否正确。
4001390002approval code not found找不到审批定义 Code，检查传入的审批定义 Code 是否正确。 审批定义 Code 获取方式： - 调用创建审批定义接口后，从响应参数 approval_code 获取。 - 登录审批管理后台，在指定审批定义的 URL 中获取，具体操作参见什么是 Approval Code。
4001390003instance code not found找不到审批实例 Code，检查传入的审批实例 Code 是否正确。 审批实例 Code 获取方式： - 调用创建审批实例接口后，从响应参数 instance_code 获取。 - 调用批量获取审批实例 ID接口，获取所需的审批实例 Code。 - 调用查询实例列表，设置过滤条件查询指定的审批实例 Code。
4001390004user_id or open_id not found检查传入的 user_id 参数是否正确，user_id 的类型需要和 user_id_type 一致，且需要确保 ID 值正确。
4031390009no operation permission没有操作权限。请前往飞书审批管理后台，进入指定审批定义编辑页面，在流程设计里的审批操作权限内，检查操作权限是否正确配置。
4001390013unsupported approval for free process不支持自定义审批流程。
4001390015approval is not active审批定义已停用，请确保当前所用的审批定义已启用后重试。你可以登录飞书审批管理后台，查看相应审批定义是否被停用。 image.png
4001395001There have been some errors. Please try again later服务出现错误。排查方案： 1. 参考接口文档的参数说明，检查请求时传入的参数是否正确。如果传入的有表单参数（form），则需要检查传入的表单控件数据是否正确。 2. 降低请求频率，并重试。如果重试仍然报错，请联系技术支持。

更多错误码信息，参见通用错误码。

内容来源：飞书开放平台 · 自动爬取整理

本镜像仅供学习与查阅，文档版权归飞书所有