飞书开放平台 Server API 文档

主题

查看指定三方审批定义 ​

调用该接口通过三方审批定义 Code 获取审批定义的详细数据，包括三方审批定义的名称、说明、三方审批发起链接、回调 URL 以及审批定义可见人列表等信息。

请求 ​

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

请求头 ​

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

路径参数 ​

名称类型描述
approval_codestring三方审批定义 Code。获取方式：
- 调用创建三方审批定义时，会返回审批定义 Code。 - 登录审批管理后台，在指定审批定义的 URL 中获取，具体操作参见什么是 Approval Code。
示例值："7C468A54-8745-2245-9675-08B7C63E7A85"

查询参数 ​

名称类型必填描述
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

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ approval_namestring审批定义名称。当前参数返回的是 @i18n@ 开头的 key，需要通过 i18n_resources.texts 参数值查阅当前 key 对应的取值（value）。
  └ approval_codestring创建三方审批定义时传入的 approval_code。
注意：创建三方审批定义接口的请求参数 approval_code 与响应参数 approval_code 不一定相同，当前参数所返回的是作为请求参数的 approval_code 的值。
  └ group_codestring审批定义所属分组
  └ group_namestring分组名称。当前参数返回的是 @i18n@ 开头的 key，需要通过 i18n_resources.texts 参数值查阅当前 key 对应的取值（value）。
  └ descriptionstring审批定义的说明。当前参数返回的是 @i18n@ 开头的 key，需要通过 i18n_resources.texts 参数值查阅当前 key 对应的取值（value）。
  └ externalapproval_create_external三方审批定义相关信息。
    └ biz_namestring列表中用于提示审批来自哪里。当前参数返回的是 @i18n@ 开头的 key，需要通过 i18n_resources.texts 参数值查阅当前 key 对应的取值（value）。
    └ biz_typestring审批定义业务类别，可由用户自定义，用于分类审批定义。
    └ create_link_mobilestring移动端发起三方审批的链接。如果没有配置移动端链接，则返回空值。
    └ create_link_pcstringPC 端发起三方审批的链接。如果没有配置 PC 端链接，则返回空值。
    └ support_pcboolean审批实例、审批任务、审批抄送是否在 PC 端展示。
    └ support_mobileboolean审批实例、审批任务、审批抄送是否在移动端展示。
    └ support_batch_readboolean是否支持批量已读
    └ enable_mark_readedboolean是否支持标注可读
    └ enable_quick_operateboolean是否支持快速操作
    └ action_callback_urlstring三方系统的操作回调 URL，待审批 实例的任务审批人点击同意或拒绝操作后，审批中心调用该 URL 通知三方系统，回调地址相关信息可参见三方审批快捷审批回调。
    └ action_callback_tokenstring回调时带的 token，用于业务系统验证请求来自审批中心。
    └ action_callback_keystring请求参数加密密钥。如果配置了该参数，则会对请求参数进行加密，接收请求后需要对请求进行解密。加解密算法参考关联外部选项说明。
    └ allow_batch_operateboolean是否支持批量审批
    └ exclude_efficiency_statisticsboolean审批流程数据是否不纳入效率统计
  └ viewersapproval_create_viewers\[\]可见人列表，在可见范围内的用户可在审批发起页看到当前审批。
    └ viewer_typestring可见人类型
可选值有：
- TENANT: 租户内可见 - DEPARTMENT: 指定部门 - USER: 指定用户 - NONE: 任何人都不可见
    └ viewer_user_idstring当 viewer_type 取值为 USER 时，该参数有返回值，返回的是指定用户的 ID，ID类型与查询参数 user_id_type 取值一致。
    └ viewer_department_idstring当 viewer_type 取值为 DEPARTMENT 时，该参数有返回值，返回的是指定部门的 ID。
  └ i18n_resourcesi18n_resource\[\]国际化文案
    └ localestring语言
可选值有：
- zh-CN: 中文 - en-US: 英文 - ja-JP: 日文
    └ textsi18n_resource_text\[\]文案的 Key:Value。Key 以 @i18n@ 开头，并匹配其他各个参数 Key。 说明：该字段主要用于适配国际化，允许同时设置多个语言的文案，审批中心会根据实际用户当前的语音环境使用匹配的文案。如果没有设置用户当前的语音环境文案，则会使用默认的语言文案。
      └ keystring文案 key
      └ valuestring文案 value
    └ is_defaultboolean是否为默认语言。
  └ managersstring\[\]审批流程管理员列表，列表内包含的是用户 ID，ID 类型与查询参数 user_id_type 取值一致。

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "approval_name": "@i18n@1",
        "approval_code": "permission_test",
        "group_code": "work_group",
        "group_name": "@i18n@2",
        "description": "@i18n@2",
        "external": {
            "biz_name": "@i18n@3",
            "biz_type": "permission",
            "create_link_mobile": "https://applink.feishu.cn/client/mini_program/open?appId=cli_9c90fc38e07a9101&path=pages/approval-form/index?id=9999",
            "create_link_pc": "https://applink.feishu.cn/client/mini_program/open?mode=appCenter&appId=cli_9c90fc38e07a9101&path=pc/pages/create-form/index?id=9999",
            "support_pc": true,
            "support_mobile": true,
            "support_batch_read": true,
            "enable_mark_readed": true,
            "enable_quick_operate": true,
            "action_callback_url": "http://www.feishu.cn/approval/openapi/instanceOperate",
            "action_callback_token": "sdjkljkx9lsadf110",
            "action_callback_key": "gfdqedvsadfgfsd",
            "allow_batch_operate": true,
            "exclude_efficiency_statistics": true
        },
        "viewers": [
            {
                "viewer_type": "USER",
                "viewer_user_id": "19a294c2",
                "viewer_department_id": "od-ac9d697abfa990b715dcc33d58a62a9d"
            }
        ],
        "i18n_resources": [
            {
                "locale": "zh-CN",
                "texts": [
                    {
                        "key": "@i18n@1",
                        "value": "审批定义"
                    }
                ],
                "is_default": true
            }
        ],
        "managers": [
            "19a294c2"
        ]
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
4001390001param is invalid参数错误。排查方案： - 根据接口文档的参数说明，检查请求时传入的参数是否正确。 - 如果传入的有表单参数（form），则需要检查该参数内传入的表单控件数据是否正确。如果报错信息内包含控件 ID（如 控件= widget17261088448220001），可以调用查看指定审批定义或者获取单个审批实例详情接口，获取响应参数 form 值，检索有问题的控件 ID，然后检查该控件的配置是否正确。
4001390002approval code not found找不到审批定义 Code，检查传入的审批定义 Code 是否正确。 审批定义 Code 获取方式： - 调用创建审批定义接口后，从响应参数 approval_code 获取。 - 登录审批管理后台，在指定审批定义的 URL 中获取，具体操作参见什么是 Approval Code。 找不到审批实例 Code，检查传入的审批实例 Code 是否正确。
4001390016approval is deleted审批定义已删除，不支持当前操作。

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

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

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