飞书开放平台 Server API 文档

主题

创建三方审批定义 ​

三方审批定义用于设置审批的名称、描述等基本信息，以及三方审批系统的审批发起页、回调 URL 等信息，使企业员工在飞书审批内即可发起并操作三方审批。

注意事项 ​

飞书审批中心不负责审批流程的流转，只负责审批的展示、状态操作、消息通知。因此，创建三方审批定义时，没有审批流程的参数配置项。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/approval/v4/external_approvals
HTTP MethodPOST
接口频率限制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
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-，在租户内全局唯一。
默认值：open_department_id
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_resources.texts 参数中的 Key），还需要在 i18n_resources.texts 参数中以 Key:Value 格式进行赋值。 - 该参数需要以 @i18n@ 开头，长度不得少于 9 个字符。
示例值："@i18n@demoname"
approval_codestring是应用自定义Code，最大支持128字符，用于唯一关联三方审批定义，具体说明： - 如果传入的值系统可以匹配到已存在的审批定义 approval_code，则调用该接口会更新相应的审批定义。 - 如果传入的值系统匹配不到任何审批定义 approval_code，则会新建一个审批定义，并返回新建的审批定义真实的 approval_code（并非通过该参数传入的值）。
示例值："F46EB460-9476-4789-9524-ECD564291234"
group_codestring否审批定义所属审批分组，用户自定义。具体说明：
- 如果传入的 group_code 当前不存在，则会新建审批分组。 - 如果 group_code 已经存在，则会使用 group_name 更新审批分组名称。 - 更新审批定义时可以不传该字段，会继续使用当前绑定的分组。
示例值："work_group"
group_namestring否审批分组名称，审批发起页的审批定义分组名称来自该字段。具体说明：
- 这里传入的是国际化文案 Key（即 i18n_resources.texts 参数中的 Key），还需要在 i18n_resources.texts 参数中以 Key:Value 格式进行赋值。 - 该参数需要以 @i18n@ 开头。 - 如果 group_code 当前不存在，则该 group_name 必填，表示新建审批分组时设置分组名称。 - 如果 group_code 存在，则会更新分组名称，不填则不更新分组名称。
示例值："@i18n@2"
descriptionstring否审批定义的说明，后续企业员工发起审批时，该说明会在审批发起页展示。 - 这里传入的是国际化文案 Key（即 i18n_resources.texts 参数中的 Key），还需要在 i18n_resources.texts 参数中以 Key:Value 格式进行赋值。 - 该参数需要以 @i18n@ 开头。
示例值："@i18n@2"
externalapproval_create_external是三方审批相关信息。
  └ biz_namestring否列表中用于提示审批来自哪个三方系统。 注意：
- 这里传入的是国际化文案 Key（即 i18n_resources.texts 参数中的 Key），还需要在 i18n_resources.texts 参数中以 Key:Value 格式进行赋值。 - 该参数需要以 @i18n@ 开头。 - 在 i18n_resources 中为该参数赋值时，无需设置 来自 前缀，审批中心默认会拼接 来自 前缀。
示例值："@i18n@3"
  └ biz_typestring否审批定义业务类别，自定义设置。
示例值："permission"
  └ create_link_mobilestring否移动端发起三方审批的链接。
- 如果设置了该链接，则在移动端发起审批时，会跳转到该链接对应的三方审批发起页。 - 如果不设置该链接，则在移动端不显示该审批。
示例值："https://applink.feishu.cn/client/mini_program/open?appId=cli_9c90fc38e07a9101&path=pages/approval-form/index?id=9999"
  └ create_link_pcstring否PC端发起三方审批的链接。 - 如果设置了该链接，则在 PC 端发起审批时，会跳转到该链接对应的三方审批发起页。 - 如果不设置该链接，则在 PC 端不显示该审批。
示例值："https://applink.feishu.cn/client/mini_program/open?mode=appCenter&appId=cli_9c90fc38e07a9101&path=pc/pages/create-form/index?id=9999"
  └ support_pcboolean否审批定义是否要在 PC 端的发起审批页面展示，如果为 true 则展示，否则不展示，默认为false。
注意：support_pc 和 support_mobile 不可都为 false。
示例值：true
  └ support_mobileboolean否审批定义是否要在移动端的发起审批页面展示，如果为 true 则展示，否则不展示，默认为false。
注意：support_pc 和 support_mobile 不可都为 false。
示例值：true
  └ support_batch_readboolean否是否支持批量已读，默认为false
示例值：true
  └ enable_mark_readedboolean否是否支持标注可读
注意：该字段无效，暂不支持使用。
示例值：true
  └ enable_quick_operateboolean否是否支持快速操作
注意：该字段无效，暂不支持使用。
示例值：true
  └ action_callback_urlstring否三方系统的操作回调 URL，待审批 实例的任务审批人点击同意或拒绝操作后，审批中心调用该 URL 通知三方系统，回调地址相关信息可参见三方审批快捷审批回调。
示例值："http://www.feishu.cn/approval/openapi/instanceOperate"
  └ action_callback_tokenstring否回调时带的 token，用于业务系统验证请求来自审批中心。
示例值："sdjkljkx9lsadf110"
  └ action_callback_keystring否请求参数加密密钥。如果配置了该参数，则会对请求参数进行加密，接收请求后需要对请求进行解密。加解密算法参考关联外部选项说明。
示例值："gfdqedvsadfgfsd"
  └ allow_batch_operateboolean否是否支持批量审批。取值为 true 时，审批人在处理该定义下的审批任务时可以批量处理多个任务， 默认为false。
示例值：true
  └ exclude_efficiency_statisticsboolean否审批流程数据是否不纳入效率统计，默认为false
示例值：true
viewersapproval_create_viewers\[\]否审批可见人列表，列表长度上限 200，只有在审批可见人列表内的用户，才可以在审批发起页看到该审批。若该参数不传值，则表示任何人不可见。
  └ viewer_typestring否可见人类型，生效优先级NONE>TENANT>指定范围
示例值："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"
i18n_resourcesi18n_resource\[\]否国际化文案
  └ localestring是语言。
示例值："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: 俄语
  └ textsi18n_resource_text\[\]是文案的 Key:Value。Key 需要以 @i18n@ 开头，并按照各个参数的要求传入 Value。 说明：该字段主要用于适配国际化，允许同时设置多个语言的文案，审批中心会根据实际用户当前的语音环境使用匹配的文案。如果没有设置用户当前的语音环境文案，则会使用默认的语言文案。
示例值：{ "@i18n@1": "权限申请", "@i18n@2": "OA审批", "@i18n@3": "Permission" }
    └ keystring是文案 Key，需要和各个参数 Key 相匹配。
示例值："@i18n@2"
    └ valuestring是文案 Value，即文案 Key 对应的参数值。
示例值："people"
  └ is_defaultboolean是是否为默认语言。默认语言需要包含所有所需的文案 Key，非默认语言如果 Key 不存在，则会使用默认语言代替。
示例值：true
managersstring\[\]否设置审批流程管理员的用户 ID，最多支持设置 200 个。ID 类型与查询参数 user_id_type 取值一致。
示例值：["19a294c2"]

请求体示例 ​

json
{
    "approval_name": "@i18n@d937443c-686f-11f0-aa8c-b6e035aec42e",
    "approval_code": "F46EB460-9476-4789-9524-ECD564291234",
    "group_code": "work_group",
    "group_name": "@i18n@d937444f-686f-11f0-aa8c-b6e035aec42e",
    "external": {
        "create_link_pc": "https://applink.feishu.cn/client/mini_program/open?mode=appCenter&appId=cli_9c90fc38e07a9101&path=pc%2Fpages%2Fcreate-form%2Findex%3Fid%3D9999",
        "create_link_mobile": "https://applink.feishu.cn/client/mini_program/open?appId=cli_9c90fc38e07a9101&path=pages%2Fapproval-form%2Findex%3Fid%3D9999",
        "support_pc": true,
        "support_mobile": true,
        "support_batch_read": false,
        "action_callback_url":"http://feishu.cn/approval/openapi/operate",
        "action_callback_token":"sdjkljkx9lxxxxx",
        "action_callback_key":"gfdqedvsadxxxxx",
        "enable_mark_readed": false
    },
    "i18n_resources":[
     {
        "locale":"zh-CN",
        "is_default":true,
         "texts":[
             {
             "key": "@i18n@d937443c-686f-11f0-aa8c-b6e035aec42e",
             "value":"people"  
            },
            {
             "key": "@i18n@d937444f-686f-11f0-aa8c-b6e035aec42e",
             "value":"hr"  
            }
         ]
      }
    ],
    "viewers": [
        {
            "viewer_type": "TENANT"
        }
    ],
    "managers":["96449fb3"]
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ approval_codestring审批定义 Code。
注意：在传入已存在的审批定义 Code 进行更新操作的场景中，该参数返回的 Code 可能与传入的 Code 不同。如果不同，请继续使用你传入的 Code，而不是该参数返回的 Code。

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "approval_code": "C30381C8-7A5F-4717-A9CF-C233BF0202D4"
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
4001390001param is invalid参数错误。排查方案： - 根据接口文档的参数说明，检查请求时传入的参数是否正确。 - 如果传入的有表单参数（form），则需要检查该参数内传入的表单控件数据是否正确。如果报错信息内包含控件 ID（如 控件= widget17261088448220001），可以调用查看指定审批定义或者获取单个审批实例详情接口，获取响应参数 form 值，检索有问题的控件 ID，然后检查该控件的配置是否正确。
4001395001There have been some errors. Please try again later服务出现错误。排查方案： 1. 参考接口文档的参数说明，检查请求时传入的参数是否正确。如果传入的有表单参数（form），则需要检查传入的表单控件数据是否正确。 2. 降低请求频率，并重试。如果重试仍然报错，请联系技术支持。

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

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

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