查看指定审批定义

根据审批定义 Code 以及语言、用户 ID 等筛选条件获取指定审批定义的信息，包括审批定义名称、状态、表单控件以及节点等信息。获取审批定义信息后，可根据信息构造创建审批实例的请求。

请求

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

请求头

名称	类型	必填	描述
Authorization	string	是	`tenant_access_token` 值格式："Bearer `access_token`" 示例值："Bearer t-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token

路径参数

名称	类型	描述
`approval_code`	`string`	审批定义 Code。获取方式： - 调用创建审批定义接口后，从响应参数 approval_code 获取。 - 登录审批管理后台，在指定审批定义的 URL 中获取，具体操作参见什么是 Approval Code。示例值："7C468A54-8745-2245-9675-08B7C63E7A85"

查询参数

名称	类型	必填	描述
`locale`	`string`	否	语言可选值，默认为审批定义配置的默认语言。示例值：zh-CN 可选值有： - `zh-CN`: 中文 - `en-US`: 英文 - `ja-JP`: 日文 - `zh-HK`: 繁体中文（中国香港） - `zh-TW`: 繁体中文（中国台湾） - `de-DE`: 德语 - `es-ES`: 西班牙语 - `fr-FR`: 法语 - `id-ID`: 印度尼西亚语 - `it-IT`: 意大利语 - `ko-KR`: 韩语 - `pt-BR`: 葡萄牙语 - `th-TH`: 泰语 - `vi-VN`: 越南语 - `ms-MY`: 马来语 - `ru-RU`: 俄语
`with_admin_id`	`boolean`	否	是否返回有数据管理权限的审批流程管理员 ID 列表（即响应参数 approval_admin_ids）。默认值：false 示例值：false
`user_id_type`	`string`	否	用户 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
`with_option`	`boolean`	否	可选是否返回外部数据源和假勤控件选项示例值：false
`user_id`	`string`	否	用户id 示例值：ou_7a4aaac5650dc0b77e85e96e7476ff1d
`nested_mutable_group`	`boolean`	否	是否返回完整的多维表格控件示例值：true

响应

响应体

名称	类型	描述
`code`	`int`	错误码，非 0 表示失败
`msg`	`string`	错误描述
`data`	`\-`	-
└ `approval_name`	`string`	审批名称
└ `status`	`string`	审批定义状态可选值有： - `ACTIVE`: 已启用 - `INACTIVE`: 已停用 - `DELETED`: 已删除 - `UNKNOWN`: 未知
└ `form`	`string`	控件参数信息，见下方 form 字段说明章节。
└ `node_list`	`approval_node_info\[\]`	节点信息
└ `name`	`string`	节点名称
└ `need_approver`	`boolean`	是否为发起人自选节点。取值为 true 表示发起审批时需要提交人自选审批人。
└ `node_id`	`string`	节点 ID
└ `custom_node_id`	`string`	节点自定义 ID，如果没有设置则不返回
└ `node_type`	`string`	审批方式可选值有： - `AND`: 会签 - `OR`: 或签 - `SEQUENTIAL`: 依次审批 - `CC_NODE`: 抄送节点
└ `approver_chosen_multi`	`boolean`	选择方式是否支持多选。流程的开始、结束节点该值无意义。
└ `approver_chosen_range`	`approver_chosen_range\[\]`	提交人自选审批人的范围
└ `approver_range_type`	`int`	指定范围可选值有： - `0`: 全公司范围 - `1`: 指定角色范围 - `2`: 指定用户范围
└ `approver_range_ids`	`string\[\]`	资源 ID。 - approver_range_type 取值为 0 时，该参数为空。 - approver_range_type 取值为 1 时，该参数取值为角色 ID。 - approver_range_type 取值为 2 时，该参数取值为用户 open_id。
└ `require_signature`	`boolean`	审批同意时是否需要手写签名。
└ `viewers`	`approval_viewer_info\[\]`	审批定义的可见人列表
└ `type`	`string`	可见人类型可选值有： - `TENANT`: 企业内可见 - `DEPARTMENT`: 指定部门 - `USER`: 指定用户 - `ROLE`: 指定角色 - `USER_GROUP`: 指定用户组 - `NONE`: 任何人都不可见
└ `id`	`string`	资源 ID。 - 在可见人类型为 DEPARTMENT 时，ID 为部门 ID。 - 在可见人类型为 USER 时，ID 为用户 open_id。 - 在可见人类型为 ROLE 时，ID 为角色 ID。 - 在可见人类型为 USER_GROUP 时，ID 为用户组 ID。
└ `user_id`	`string`	在可见人类型为 USER 时，表示可见人用户 open_id。
└ `approval_admin_ids`	`string\[\]`	有数据管理权限的审批流程管理员的 open_id，由参数 with_admin_id 控制是否返回。
└ `form_widget_relation`	`string`	组件之间值关联关系

form 字段说明

审批定义各表单控件参数说明详情参见审批定义表单控件参数。

参数	类型	是否必须	说明
form	String	是	控件信息，JSON 数组格式。
∟id	String	是	控件 ID
∟custom_id	String	否	控件自定义 ID
∟name	String	是	控件名称
∟type	String	是	控件类型，各控件类型参考下文控件 type 说明章节
∟enable_default_value	bool	是	此控件是否启用了默认值
∟widget_default_value	String	是	控件的默认值
∟default_value_type	String	是	控件的默认值类型
∟display_condition	String	否	控件显隐条件
∟conditional	String	否	或（OR）条件
∟conditions	list	否	条件列表
∟conditional	String	否	多个条件同时满足（AND）
∟expressions	list	否	表达式列表
∟source_widget	String	否	控件 ID
∟compare_type	String	否	判断规则
∟standard_value	String	否	条件值

控件 type 说明

控件/控件组	type
文档	document
单行文本	input
多行文本	textarea
说明	text
数字	number
金额	amount
计算公式	formula
单选	radioV2
多选	checkboxV2
日期	date
日期区间	dateInterval
明细/表格	fieldList
引用多维表格	mutableGroup
图片/视频	image/imageV2
附件	attachment/attachmentV2
部门	department
联系人	contact
关联审批	connect
地址	address
定位	location
收款账户	account
电话	telephone
流水号	serialNumber
请假控件组	leaveGroupV2
加班控件组	workGroup
出差控件组	tripGroup
外出控件组	outGroup
录用控件组	apaascorehrOnboardingGroup
换班控件组	shiftGroupV2
转正控件组	apaascorehrRegularateGroup
补卡控件组	remedyGroupV2
调岗控件组	apaascorehrJobAdjustGroup
离职控件组	apaascorehrOffboardingGroup

响应体示例

json

{
    "code": 0,
    "msg": "success",
    "data": {
        "approval_name": "Payment",
        "status": "ACTIVE",
        "form": "[{\"id\": \"widget1\", \"custom_id\": \"user_name\",\"name\": \"Item application\",\"type\": \"textarea\",\"printable\": true,\"required\": true}]",
        "node_list": [
            {
                "name": "Approval",
                "need_approver": true,
                "node_id": "46e6d96cfa756980907209209ec03b64",
                "custom_node_id": "46e6d96cfa756980907209209ec03b64",
                "node_type": "AND",
                "approver_chosen_multi": true,
                "approver_chosen_range": [
                    {
                        "approver_range_type": 2,
                        "approver_range_ids": [
                            "0"
                        ]
                    }
                ],
                "require_signature": false
            }
        ],
        "viewers": [
            {
                "type": "TENANT",
                "id": "ou_e03053f0541cecc3269d7a9dc34a0b21",
                "user_id": "f7cb567e"
            }
        ],
        "approval_admin_ids": [
            "ou_3cda9c969f737aaa05e6915dce306cb9"
        ],
        "form_widget_relation": "{\"groups\":[{\"id\":\"1\",\"parent_widgets_ids\":[\"widget1\",\"widget4\"],\"children_widget_ids\":[\"widget2.widget3\"],\"conditions\":[{\"parents_expr\":{\"type\":\"Multi\",\"expr\":{\"type\":\"and\",\"exprs\":[{\"type\":\"SingleWidget\",\"expr\":{\"type\":\"in\",\"widget_id\":\"widget1\",\"expect\":{\"type\":\"local\",\"value\":[{\"value\":\"value_0\"},{\"value\":\"value_1\"}]}}},{\"type\":\"Const\",\"expr\":{\"value\":true,\"widget_ids\":[\"widget4\"]}}]}},\"children_rule\":{\"expr\":{\"type\":\"SingleWidget\",\"expr\":{\"type\":\"in\",\"widget_id\":\"widget2.widget3\",\"expect\":{\"type\":\"local\",\"value\":[{\"value\":\"value_3\"},{\"value\":\"value_5\"}]}}},\"actions\":[{\"type\":\"SetOptions\",\"widget_id\":\"widget2.widget3\",\"value\":{\"type\":\"local\",\"value\":[{\"value\":\"value_3\"},{\"value\":\"value_4\"}]}}]}}]}]}"
    }
}

错误码

HTTP状态码	错误码	描述	排查建议
400	1390001	param is invalid	参数错误。排查方案： - 根据接口文档的参数说明，检查请求时传入的参数是否正确。 - 如果传入的有表单参数（form），则需要检查该参数内传入的表单控件数据是否正确。如果报错信息内包含控件 ID（如 `控件= widget17261088448220001`），可以调用查看指定审批定义或者获取单个审批实例详情接口，获取响应参数 form 值，检索有问题的控件 ID，然后检查该控件的配置是否正确。
400	1390002	approval code not found	找不到审批定义 Code，检查传入的审批定义 Code 是否正确。审批定义 Code 获取方式： - 调用创建审批定义接口后，从响应参数 approval_code 获取。 - 登录审批管理后台，在指定审批定义的 URL 中获取，具体操作参见什么是 Approval Code。
400	1395001	There have been some errors. Please try again later	服务出现错误。排查方案： 1. 参考接口文档的参数说明，检查请求时传入的参数是否正确。如果传入的有表单参数（form），则需要检查传入的表单控件数据是否正确。 2. 降低请求频率，并重试。如果重试仍然报错，请联系技术支持。
400	1390016	approval is deleted	审批定义已删除，不支持当前操作。

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

通用事件

事件接口

特殊事件

查看指定审批定义

请求

请求头

路径参数

查询参数

响应

响应体

form 字段说明

控件 type 说明

响应体示例

错误码

查看指定审批定义 ​

请求 ​

请求头 ​

路径参数 ​

查询参数 ​

响应 ​

响应体 ​

form 字段说明 ​

控件 type 说明 ​

响应体示例 ​

错误码 ​

查看指定审批定义

请求

请求头

路径参数

查询参数

响应

响应体

form 字段说明

控件 type 说明

响应体示例

错误码