创建审批定义

Error: 为了更好地提升接口文档的的易理解性，我们对文档进行了升级，请尽快迁移至新版本>>

用于通过接口创建简单的审批定义，可以灵活指定定义的基础信息、表单和流程等。创建成功后，不支持从审批管理后台删除该定义。不推荐企业自建应用使用，如有需要尽量联系管理员在审批管理后台创建定义。

接口谨慎调用，创建后的审批定义无法停用/删除

请求

项目	值
HTTP URL	https://www.feishu.cn/approval/openapi/v2/approval/create
HTTP Method	POST
支持的应用类型	custom,isv
权限要求调用该 API 所需的权限。开启其中任意一项权限即可调用	`approval:approval:readonly` 访问审批应用

请求头

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

请求体

参数	类型	必须	说明
approval_name	String	是	审批名称的国际化文案 Key，以 @i18n@ 开头，长度不得少于 9 个字符
approval_code	String	否	传空表示新建
description	String	否	审批描述的国际化文案 Key，以 @i18n@ 开头，长度不得少于 9 个字符
viewers	list	是	审批前台可见人范围，详见下方说明
form	map	是	审批定义表单
∟form_content	String	是	审批定义表单内容，json 数组，详见下方说明
node_list	list	是	审批定义节点，map 数组，需要将开始节点作为 list 第一个元素，结束节点作为最后一个元素
∟id	String	是	节点 ID，开始节点的 ID 为 START，结束节点的 ID 为 END，开始和结束节点不需要指定 name、node_type 以及 approver
∟name	String	是	节点名称的国际化文案 Key，以 @i18n@ 开头，长度不得少于 9 个字符
∟node_type	String	是	审批类型枚举 - AND 会签 - OR 或签 - SEQUENTIAL 依次审批当 node_type 为依次审批时，审批人必须为『发起人自选』
∟approver	list	是	审批人列表，详见下方说明
∟ccer	list	否	抄送人列表，详见下方说明
settings	map	否	审批定义其他设置
∟revert_interval	int	否	审批实例通过后允许撤回的时间，以秒为单位，默认 31 天，0 为不可撤回
∟revert_option	int	否	是否支持审批通过第一个节点后撤回，默认为1，0为不支持
config	map	否	审批定义配置项，用于配置对应审批定义是否可以由用户在审批后台进行修改
∟can_update_viewer	bool	否	是否可以修改可见范围，默认 false
∟can_update_form	bool	否	是否可以修改表单内容，默认 false
∟can_update_process	bool	否	是否可以修改流程节点，默认 false
∟can_update_revert	bool	否	是否可以修改撤回时间，默认 false
∟help_url	String	否	用于配置帮助页链接，可以从审批后台跳转到该链接页面
icon	int	否	审批图标枚举，详见下方说明，默认为 0
i18n_resources	list	是	国际化文案
∟locale	String	是	语言： zh-CN - 中文 en-US - 英文 ja-JP - 日文
∟is_default	bool	是	是否默认语言，默认语言需要包含所有 key，非默认语言如果 key 不存在会使用默认语言代替
∟texts	map	是	文案 key, value, i18n key 以 @i18n@ 开头

请求体示例

json

{
    "approval_name": "@i18n@approval_name",
    "approval_code": "7C468A54-8745-2245-9675-08B7C63E7A85",
    "description": "@i18n@description",
    "viewers":[
        {
            "type":"TENANT",
            "open_id":"ou_e03053f0541cecc3269d7a9dc34a0b21",
            "user_id":"f7cb567e"
        }
    ],
    "form": {
          "form_content": "[{\"id\":\"user_name\", \"type\": \"input\", \"required\":true, \"name\":\"@i18n@widget1\"}]"
        },
    "node_list": [{
          "id": "START"
        },{
          "id": "node_id",
          "name": "@i18n@node_name",
          "node_type": "AND",
          "approver": [
            {
              "type": "Personal",
              "open_id": "ou_e03053f0541cecc3269d7a9dc34a0b21",
              "user_id": "f7cb567e"
            }
          ],
          "ccer": [
            {
              "type": "Supervisor",
              "open_id": "ou_e03053f0541cecc3269d7a9dc34a0b21",
              "user_id": "f7cb567e"
            }
          ]
        },{
          "id": "END"
        }],
    "settings" : {
          "revert_interval":0
        },
    "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" : {
              "@i18n@approval_name": "审批名称",
              "@i18n@description": "审批描述",
              "@i18n@widget1": "控件1",
              "@i18n@node_name": "节点名称"
            },
          "is_default": true
        }]
}

响应

响应体

参数	类型	必须	说明
code	int	是	错误码，非 0 表示失败
msg	String	是	返回码的描述
data	map	是	返回业务信息
∟approval_code	String	是	审批定义 Code

字段说明:

viewers 字段说明

viewers 字段指定了哪些人能从审批应用的前台发起该审批。

viewers 字段是由多个 viewer 构成的 list，每个 viewer 结构如下：

{
    "type":"TENANT",
    "user_id":"",
    "open_id":""
}

其中，type 的枚举包括：

TENANT - 所有人可见
NONE - 所有人不可见
USER - 指定用户可见
DEPARTMENT - 指定部门可见

当 type 为 USER 时，需要填写 user_id 或 open_id 中的一个，用于指定对哪个用户可见
当 type 为 DEPARTMENT 时，需要填写部门的 open_id，用于指定对哪个部门可见

approver & ccer 字段说明

approver 和 ccer 指定了在某个审批节点上的审批人和抄送人，该字段都是由 user 构成 list，user 结构如下：

{
    "type":"Personal",
    "user_id":"",
    "open_id":""
}

其中，type 的枚举包括：

Supervisor - 主管审批（由下往上）
SupervisorTopDown - 主管审批（从上往下）
DepartmentManager - 部门负责人审批（由下往上）
DepartmentManagerTopDown - 部门负责人审批（从上往下）
Personal - 指定成员
Free - 发起人自选

当 type 为 Supervisor、SupervisorTopDown、DepartmentManager 、DepartmentManagerTopDown 这 4 种时，需要在 user_id 中填写对应的级数，例如：由下往上三级主管审批，user_id = 3
当 type 为 Personal 时，需要填写 user_id 或 open_id 中的一个，用于指定用户
当 approver 为 Free 发起人自选时，不需要指定 user_id 或 open_id；ccer 不支持 Free 发起人自选

form_content 字段说明

表单项的 id 和 name 需要自行指定，id 不可重复，name 为表单名称的国际化文案 Key，以 @i18n@ 开头，长度不得少于 9 个字符，可以为单行文本、多行文本、单选、联系人、部门控件设置默认值，详情请参考控件支持设置默认值 open api 说明文档

单行文本 input，多行文本 textarea，数字 number，图片 image，附件 attachmentV2

{
    "id":"",
    "name":"",
    "type":"input",
    "required":true
}

金额 amount

{
    "id":"",
    "name":"",
    "type":"amount",
    "required":true,
    "value":"CNY"
}

value 为金额控件的枚举值，包括：
CNY - 人民币
USD - 美元
EUR - 欧元
JPY - 日元
CAD - 加拿大元
CHF - 瑞士法郎
SGD - 新加坡元
AUD - 澳大利亚元
KBW - 韩元
INR - 印度卢比
TWD - 新台币
HKD - 港元
MOP - 澳门元
THB - 泰铢
IDR - 印尼盾
PHP - 菲律宾比索
MYR - 马来西亚令吉

说明 text

{
    "id":"",
    "name":"",
    "type":"text",
    "required":true,
    "value":"@i18n@text"
}

value 为说明内容的国际化文案 Key，以 @i18n@ 开头，长度不得少于 9 个字符

单选 radioV2，多选 checkboxV2

case1: 普通单选/多选

{
    "id":"",
    "name":"",
    "type":"radioV2",
    "required":true,
    "value":[{"key":"1","text":"@i18n@choice1"},{"key":"2","text":"@i18n@choice2"}]
}

case2: 联动外部数据源单选/多选：【关联外部选项说明】

{
    "id":"",
    "name":"",
    "type":"radioV2",
    "required":true,
    "value":[],
    "externalData":{
        "externalUrl":"https://xxx.xxx.xxx/",
        "token":"t",
        "key":"k",
        "linkageConfigs":[
            {
                "linkageWidgetID":"widget1",
                "key":"linkageWidget1",
                "value":"example"
            }
        ],
        "externalDataLinkage":true
    }
}

value为每个选项 Key 和 Text，其中 Key 不能重复，Text 以 @i18n@开头，长度不得少于9个字符

日期 date

{
    "id":"",
    "name":"",
    "type":"date",
    "required":true,
    "value": "YYYY-MM-DD"
}

value 为日期格式：
YYYY-MM-DD：年-月-日
YYYY-MM-DD a：年-月-日上午/下午
YYYY-MM-DD hh:mm：年-月-日时:分

关联 connect

{
    "id":"",
    "name":"",
    "type":"connect",
    "required":true,
    "value":["code1","code2"]
}

value 为关联审批定义的 code

联系人 contact

{
    "id":"",
    "name":"",
    "type":"contact",
    "required":true,
    "value":{
        "ignore": true,
        "multi": false
      }
}

value 为联系人控件的配置项：
ignore：是否可选自己，默认 false，可选自己
multi：是否可选多人，默认 false，不可选

地址 address

{
    "id":"",
    "name":"",
    "type":"address",
    "required":true,
    "value":{
        "enableDetailAddress": false,
        "requiredDetailAddress": false,
        "preLocating": false
      }
}

value 为地址控件的配置项：
enableDetailAddress：是否开启详细地址，默认 false，不开启
requiredDetailAddress：详细地址是否必填，默认 false，不必填
preLocating：是否自动定位，默认 false，不自动定位

日期区间 dateInterval

{
    "id":"",
    "name":"",
    "type":"dateInterval",
    "required":true,
    "value":{
        "format": "YYYY-MM-DD",
        "intervalAllowModify": false,
      }
}

value 为日期区间控件的配置项：
format：日期格式，同 date 控件
intervalAllowModify：时长是否可以修改，默认 false，不可以修改

电话 telephone

{
    "id":"",
    "name":"",
    "type":"telephone",
    "required":true,
    "option":{
        "availableType": "FIXED_LINE_OR_MOBILE"
      }
}

option 为电话控件的配置项：
availableType：电话可选类型，可选值为 MOBILE、FIXED_LINE、FIXED_LINE_OR_MOBILE

明细 fieldList

{
    "id": "",
    "name": "",
    "type": "fieldlist",
    "required": true,
    "value":
    [
        {
            "id": "",
            "name": "",
            "type": "input",
            "required": true
        }
    ],
    "option":
    {
        "inputType": "LIST",
        "printType": "LIST"
    }
}

option 为明细控件的配置项：
inputType：明细控件的填写格式，可选 LIST(纵向填写)、FORM(横向填写)
printType: 明细控件的打印格式，可选 LIST(纵向打印)、FORM(横向打印)

图标枚举: 下图从左至右，从上到下依次为 0-24 号图标。

响应体示例

json

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

事件

工作空间枚举

工作空间数据表

工作空间视图

角色

apiRef

内容

文件

文件夹

数据校验

表格操作

货币信息

地点 · 数据

事件

事件

审批 · 搜索

飞书原生审批

应用商店集成

第三方审批集成

创建审批定义 ​

请求 ​

请求头 ​

请求体 ​

请求体示例 ​

响应 ​

响应体 ​

响应体示例 ​

创建审批定义

请求

请求头

请求体

请求体示例

响应

响应体

响应体示例