飞书开放平台 Server API 文档

主题

创建审批实例 ​

调用本接口使用指定审批定义 Code 创建一个审批实例，接口调用者需对审批定义的表单有详细了解，按照定义的表单结构，将表单 Value 通过本接口传入。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/approval/v4/instances
HTTP MethodPOST
接口频率限制100 次/分钟
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可approval:approval 查看、创建、更新、删除审批应用相关信息 approval:instance 查看、创建、更新、删除原生审批实例相关信息

请求头 ​

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

请求体 ​

名称类型必填描述
approval_codestring是审批定义 Code。获取方式：
- 调用创建审批定义接口后，从响应参数 approval_code 获取。 - 登录审批管理后台，在指定审批定义的 URL 中获取，具体操作参见什么是 Approval Code。
示例值："7C468A54-8745-2245-9675-08B7C63E7A85"
user_idstring否审批发起人的 user_id，与 open_id 必须传入其中一个。如果传入了 user_id 则优先使用 user_id。获取方式参考如何获取用户的 User ID。
示例值："f7cb567e"
open_idstring否审批发起人的 open_id，与 user_id 必须传入其中一个。如果传入了 user_id 则优先使用 user_id。获取方式参考如何获取用户的 Open ID
示例值："ou_3cda9c969f737aaa05e6915dce306cb9"
department_idstring否审批发起人所属部门 ID。如果用户只属于一个部门，可以不填。如果用户属于多个部门，不填值则默认选择部门列表第一个部门。获取方式参见部门 ID。
说明：
- 不支持填写根部门。 - 需填写 department_id 类型的部门 ID。
示例值："9293493ccacbdb9a"
formstring是填写的审批表单控件值，JSON 数组，传值时需要压缩转义为字符串。各控件值的参数说明参考审批实例表单控件参数。
示例值："[{\"id\":\"111\", \"type\": \"input\", \"value\":\"test\"}]"
node_approver_user_id_listnode_approver\[\]否如果审批定义的流程中，有节点需要发起人自选审批人，则需要通过本参数填写对应节点的审批人（通过用户 user_id 指定审批人）。
说明：如果同时传入了 node_approver_user_id_list、node_approver_open_id_list，则取两个参数的并集生效审批人。
  └ keystring否节点的 node_id 或 custom_node_id，可调用 查看指定审批定义 接口，从接口返回的 node_list 参数中获取。
示例值："46e6d96cfa756980907209209ec03b64"
  └ valuestring\[\]否审批人列表，需传入用户 user_id。获取方式参考如何获取用户的 User ID。
示例值：["f7cb567e"]
node_approver_open_id_listnode_approver\[\]否如果审批定义的流程中，有节点需要发起人自选审批人，则需要通过本参数填写对应节点的审批人（通过用户 open_id 指定审批人）。
说明：如果同时传入了 node_approver_user_id_list、node_approver_open_id_list，则取两个参数的并集生效审批人。
  └ keystring否节点的 node_id 或 custom_node_id，可调用 查看指定审批定义 接口，从接口返回的 node_list 参数中获取。
示例值："46e6d96cfa756980907209209ec03b64"
  └ valuestring\[\]否审批人列表，需传入用户 open_id。获取方式参考如何获取用户的 Open ID。
示例值：["f7cb567e"]
node_cc_user_id_listnode_cc\[\]否如果审批定义的流程中，有节点需要发起人自选抄送人，则需要通过本参数填写对应节点的抄送人（通过用户 user_id 指定审批人）。
说明：如果同时传入了 node_cc_user_id_list、node_cc_open_id_list，则取两个参数的并集生效抄送人。
数据校验规则：
- 最大长度：20
  └ keystring否节点的 node_id，可调用 查看指定审批定义 接口，从接口返回的 node_list 参数中获取。
示例值："46e6d96cfa756980907209209ec03b75"
  └ valuestring\[\]否抄送人列表，需传入用户 user_id。获取方式参考如何获取用户的 User ID。
示例值：["f7cb567e"]
node_cc_open_id_listnode_cc\[\]否如果审批定义的流程中，有节点需要发起人自选抄送人，则需要通过本参数填写对应节点的抄送人（通过用户 open_id 指定审批人）。
说明：如果同时传入了 node_cc_user_id_list、node_cc_open_id_list，则取两个参数的并集生效抄送人。
数据校验规则：
- 最大长度：20
  └ keystring否节点的 node_id，可调用 查看指定审批定义 接口，从接口返回的 node_list 参数中获取。
示例值："46e6d96cfa756980907209209ec03b75"
  └ valuestring\[\]否抄送人列表，需传入用户 open_id。获取方式参考如何获取用户的 Open ID。
示例值：["f7cb567e"]
uuidstring否审批实例 uuid，用于幂等操作，单个企业内的唯一 key。同一个 uuid 只能用于创建一个审批实例，如果冲突则创建失败并返回错误码 60012 ，格式建议为 XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX，不区分大小写。
示例值："7C468A54-8745-2245-9675-08B7C63E7A87"
数据校验规则：
- 长度范围：1 ～ 64 字符
allow_resubmitboolean否是否配置 提交 按钮，适用于任务的审批人退回审批单据后，审批提交人可以在同一个审批实例内点击 提交，提交单据。
示例值：true
allow_submit_againboolean否是否配置 再次提交 按钮，适用于周期性提单场景，按照当前表单内容再次发起一个新审批实例。
示例值：true
cancel_bot_notificationstring否取消指定的 Bot 推送通知。可选值有：
- 1：取消审批实例通过推送。 - 2：取消审批实例拒绝推送。 - 4：取消审批实例取消推送。
支持同时取消多个 bot 推送通知。位运算，即如需取消 1 和 2 两种通知，则需要传入加和值 3。
示例值："1"
forbid_revokeboolean否是否禁止撤销审批实例
示例值：false
默认值：false
i18n_resourcesi18n_resource\[\]否国际化文案。目前只支持为表单的单行、多行文本控件赋值。
  └ localestring是语言
示例值："zh-CN"
可选值有：
- zh-CN: 中文 - en-US: 英文 - ja-JP: 日文
  └ textsi18n_resource_text\[\]是文案的 Key:Value。Key 需要以 @i18n@ 开头，并按照各个参数的要求传入 Value。
说明：该字段主要用于适配国际化，允许同时设置多个语言的文案，审批中心会根据实际用户当前的语音环境使用匹配的文案。如果没有设置用户当前的语音环境文案，则会使用默认的语言文案。
示例值：{ "@i18n@1": "权限申请", "@i18n@2": "OA审批", "@i18n@3": "Permission" }
    └ keystring是文案 Key，需要和各个参数 Key 相匹配。
示例值："@i18n@1"
    └ valuestring是文案 Value，即文案 Key 对应的参数值。
示例值："people"
  └ is_defaultboolean是是否为默认语言。默认语言需要包含所有所需的文案 Key，非默认语言如果 Key 不存在，则会使用默认语言代替。
示例值：true
titlestring否审批实例的展示名称。如果填写了该参数，则审批列表中的审批名称使用该参数，如果不填该参数，则审批名称使用审批定义的名称。
说明：这里传入的是国际化文案 Key（即 i18n_resources.texts 参数中的 Key），必须以 @i18n@ 开头，还需要在 i18n_resources.texts 参数中以 Key:Value 格式进行赋值。
示例值："@i18n@1"
title_display_methodint否审批详情页 title 展示模式。
示例值：0
可选值有：
- 0: 如果审批定义和审批实例都有 title，则全部展示，通过竖线分割。 - 1: 如果审批定义和审批实例都有 title，只展示审批实例的 title。
默认值：0
node_auto_approval_listnode_auto_approval\[\]否设置自动通过的节点。
数据校验规则：
- 最大长度：10
  └ node_id_typestring否节点 ID 类型
示例值："NON_CUSTOM"
可选值有：
- CUSTOM: 自定义节点ID - NON_CUSTOM: 非自定义节点ID
  └ node_idstring否节点 ID 值，可调用 查看指定审批定义 接口，从接口返回的 node_list 参数中获取。
示例值："manager_node_id"

请求体示例 ​

json
{
    "approval_code":"4202AD96-9EC1-4284-9C48-B923CDC4F30B",
    "user_id":"59a92c4a",
    "open_id":"ou_806a18fb5bdf525e38ba219733bdbd73",
    "form":"[{\"id\":\"111\",\"type\":\"input\",\"value\":\"11111\"},{\"id\":\"222\",\"required\":true,\"type\":\"dateInterval\",\"value\":{\"start\":\"2019-10-01T08:12:01+08:00\",\"end\":\"2019-10-02T08:12:01+08:00\",\"interval\": 2.0}},{\"id\":\"333\",\"type\":\"radioV2\",\"value\":\"1\"},{\"id\":\"444\",\"type\":\"number\", \"value\":\"4\"},{\"id\":\"555\",\"type\":\"textarea\",\"value\":\"fsafs\"}]",
    "node_approver_user_id_list":[
        {"key": "46e6d96cfa756980907209209ec03b64","value":["59a92c4a"]},
        {"key": "manager_node_id","value":["59a92c4a"]}
    ],
    "node_approver_open_id_list":[
        {"key": "46e6d96cfa756980907209209ec03b64","value":["ou_806a18fb5bdf525e38ba219733bdbd73"]},
        {"key": "manager_node_id","value":["ou_806a18fb5bdf525e38ba219733bdbd73"]}
    ],
    "node_cc_user_id_list":[
        {"key": "46e6d96cfa756980907209209ec03b64","value":["59a92c4a"]},
        {"key": "manager_node_id","value":["59a92c4a"]}
    ],
    "node_cc_open_id_list":[
        {"key": "46e6d96cfa756980907209209ec03b64","value":["ou_806a18fb5bdf525e38ba219733bdbd73"]},
        {"key": "manager_node_id","value":["ou_806a18fb5bdf525e38ba219733bdbd73"]}
    ]
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ instance_codestring审批实例 Code

响应体示例 ​

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

错误码 ​

HTTP状态码错误码描述排查建议
4001390001param is invalid参数错误。排查方案： - 根据接口文档的参数说明，检查请求时传入的参数是否正确。 - 如果传入的有表单参数（form），则需要检查该参数内传入的表单控件数据是否正确。如果报错信息内包含控件 ID（如 控件= widget17261088448220001），可以调用查看指定审批定义或者获取单个审批实例详情接口，获取响应参数 form 值，检索有问题的控件 ID，然后检查该控件的配置是否正确。
4001390015approval is not active审批定义已停用，请确保当前所用的审批定义已启用后重试。你可以登录飞书审批管理后台，查看相应审批定义是否被停用。 image.png
4001390013unsupported approval for free process不支持自定义审批流程。
4001395001There have been some errors. Please try again later服务出现错误。排查方案： 1. 参考接口文档的参数说明，检查请求时传入的参数是否正确。如果传入的有表单参数（form），则需要检查传入的表单控件数据是否正确。 2. 降低请求频率，并重试。如果重试仍然报错，请联系技术支持。

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

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

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