服务端 API/审批/原生审批实例/创建审批实例 # 创建审批实例 调用本接口使用指定审批定义 Code 创建一个审批实例，接口调用者需对审批定义的表单有详细了解，按照定义的表单结构，将表单 Value 通过本接口传入。 ## 请求 基本 |   ---|--- HTTP URL | https://open.larksuite.com/open-apis/approval/v4/instances HTTP Method | POST 接口频率限制 | [100 次/分钟](https://open.larksuite.com/document/ukTMukTMukTM/uUzN04SN3QjL1cDN) 支持的应用类型 | Custom App、Store App 权限要求
**调用该 API 所需的权限。开启其中任意一项权限即可调用**
开启任一权限即可 | 查看、创建、更新、删除审批应用相关信息(approval:approval)
查看、创建、更新、删除原生审批实例相关信息(approval:instance) ### 请求头 名称 | 类型 | 必填 | 描述 ---|---|---|--- Authorization | string | 是 | `tenant_access_token`
**值格式**："Bearer `access_token`"
**示例值**："Bearer t-7f1bcd13fc57d46bac21793a18e560"
[了解更多：如何选择与获取 access token](https://open.larksuite.com/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use) Content-Type | string | 是 | **固定值**："application/json; charset=utf-8" ### 请求体 名称 | 类型 | 必填 | 描述 ---|---|---|--- approval_code | string | 是 | 审批定义 Code。获取方式：
- 调用[创建审批定义](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/approval/create)接口后，从响应参数 approval_code 获取。
- 登录审批管理后台，在指定审批定义的 URL 中获取，具体操作参见[什么是 Approval Code](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/approval/overview-of-approval-resources#8151e0ae)。
**示例值**："7C468A54-8745-2245-9675-08B7C63E7A85" user_id | string | 否 | 审批发起人的 user_id，与 open_id 必须传入其中一个。如果传入了 user_id 则优先使用 user_id。获取方式参考[如何获取用户的 User ID](https://open.larksuite.com/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-user-id)。
**示例值**："f7cb567e" open_id | string | 否 | 审批发起人的 open_id，与 user_id 必须传入其中一个。如果传入了 user_id 则优先使用 user_id。获取方式参考[如何获取用户的 Open ID](https://open.larksuite.com/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-openid)
**示例值**："ou_3cda9c969f737aaa05e6915dce306cb9" department_id | string | 否 | 审批发起人所属部门 ID。如果用户只属于一个部门，可以不填。如果用户属于多个部门，不填值则默认选择部门列表第一个部门。获取方式参见[部门 ID](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview#9c02ed7a)。
**说明**：
- 不支持填写根部门。
- 需填写 department_id 类型的部门 ID。
**示例值**："9293493ccacbdb9a" form | string | 是 | 填写的审批表单控件值，JSON 数组，传值时需要压缩转义为字符串。各控件值的参数说明参考[审批实例表单控件参数](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/instance/approval-instance-form-control-parameters)。
**示例值**："[{\"id\":\"111\", \"type\": \"input\", \"value\":\"test\"}]" node_approver_user_id_list | node_approver\[\] | 否 | 如果审批定义的流程中，有节点需要发起人自选审批人，则需要通过本参数填写对应节点的审批人（通过用户 user_id 指定审批人）。
**说明**：如果同时传入了 node_approver_user_id_list、node_approver_open_id_list，则取两个参数的并集生效审批人。 key | string | 否 | 节点的 node_id 或 custom_node_id，可调用 [查看指定审批定义](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/approval/get) 接口，从接口返回的 node_list 参数中获取。
**示例值**："46e6d96cfa756980907209209ec03b64" value | string\[\] | 否 | 审批人列表，需传入用户 user_id。获取方式参考[如何获取用户的 User ID](https://open.larksuite.com/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-user-id)。
**示例值**：["f7cb567e"] node_approver_open_id_list | node_approver\[\] | 否 | 如果审批定义的流程中，有节点需要发起人自选审批人，则需要通过本参数填写对应节点的审批人（通过用户 open_id 指定审批人）。
**说明**：如果同时传入了 node_approver_user_id_list、node_approver_open_id_list，则取两个参数的并集生效审批人。 key | string | 否 | 节点的 node_id 或 custom_node_id，可调用 [查看指定审批定义](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/approval/get) 接口，从接口返回的 node_list 参数中获取。
**示例值**："46e6d96cfa756980907209209ec03b64" value | string\[\] | 否 | 审批人列表，需传入用户 open_id。获取方式参考[如何获取用户的 Open ID](https://open.larksuite.com/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-openid)。
**示例值**：["f7cb567e"] node_cc_user_id_list | node_cc\[\] | 否 | 如果审批定义的流程中，有节点需要发起人自选抄送人，则需要通过本参数填写对应节点的抄送人（通过用户 user_id 指定审批人）。
**说明**：如果同时传入了 node_cc_user_id_list、node_cc_open_id_list，则取两个参数的并集生效抄送人。
**数据校验规则**：
- 最大长度：`20` key | string | 否 | 节点的 node_id，可调用 [查看指定审批定义](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/approval/get) 接口，从接口返回的 node_list 参数中获取。
**示例值**："46e6d96cfa756980907209209ec03b75" value | string\[\] | 否 | 抄送人列表，需传入用户 user_id。获取方式参考[如何获取用户的 User ID](https://open.larksuite.com/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-user-id)。
**示例值**：["f7cb567e"] node_cc_open_id_list | node_cc\[\] | 否 | 如果审批定义的流程中，有节点需要发起人自选抄送人，则需要通过本参数填写对应节点的抄送人（通过用户 open_id 指定审批人）。
**说明**：如果同时传入了 node_cc_user_id_list、node_cc_open_id_list，则取两个参数的并集生效抄送人。
**数据校验规则**：
- 最大长度：`20` key | string | 否 | 节点的 node_id，可调用 [查看指定审批定义](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/approval/get) 接口，从接口返回的 node_list 参数中获取。
**示例值**："46e6d96cfa756980907209209ec03b75" value | string\[\] | 否 | 抄送人列表，需传入用户 open_id。获取方式参考[如何获取用户的 Open ID](https://open.larksuite.com/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-openid)。
**示例值**：["f7cb567e"] uuid | string | 否 | 审批实例 uuid，用于幂等操作，单个企业内的唯一 key。同一个 uuid 只能用于创建一个审批实例，如果冲突则创建失败并返回错误码 60012 ，格式建议为 XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX，不区分大小写。
**示例值**："7C468A54-8745-2245-9675-08B7C63E7A87"
**数据校验规则**：
- 长度范围：`1` ～ `64` 字符 allow_resubmit | boolean | 否 | 是否配置 **提交** 按钮，适用于任务的审批人退回审批单据后，审批提交人可以在同一个审批实例内点击 **提交**，提交单据。
**示例值**：true allow_submit_again | boolean | 否 | 是否配置 **再次提交** 按钮，适用于周期性提单场景，按照当前表单内容再次发起一个新审批实例。
**示例值**：true cancel_bot_notification | string | 否 | 取消指定的 Bot 推送通知。可选值有：
- 1：取消审批实例通过推送。
- 2：取消审批实例拒绝推送。
- 4：取消审批实例取消推送。
支持同时取消多个 bot 推送通知。位运算，即如需取消 1 和 2 两种通知，则需要传入加和值 3。
**示例值**："1" forbid_revoke | boolean | 否 | 是否禁止撤销审批实例
**示例值**：false
**默认值**：`false` i18n_resources | i18n_resource\[\] | 否 | 国际化文案。目前只支持为表单的单行、多行文本控件赋值。 locale | string | 是 | 语言
**示例值**："zh-CN"
**可选值有**：
- zh-CN：中文
- en-US：英文
- ja-JP：日文 texts | i18n_resource_text\[\] | 是 | 文案的 Key:Value。Key 需要以 @i18n@ 开头，并按照各个参数的要求传入 Value。
**说明**：该字段主要用于适配国际化，允许同时设置多个语言的文案，审批中心会根据实际用户当前的语音环境使用匹配的文案。如果没有设置用户当前的语音环境文案，则会使用默认的语言文案。
**示例值**：{ "@i18n@1": "权限申请", "@i18n@2": "OA审批", "@i18n@3": "Permission" } key | string | 是 | 文案 Key，需要和各个参数 Key 相匹配。
**示例值**："@i18n@1" value | string | 是 | 文案 Value，即文案 Key 对应的参数值。
**示例值**："people" is_default | boolean | 是 | 是否为默认语言。默认语言需要包含所有所需的文案 Key，非默认语言如果 Key 不存在，则会使用默认语言代替。
**示例值**：true title | string | 否 | 审批实例的展示名称。如果填写了该参数，则审批列表中的审批名称使用该参数，如果不填该参数，则审批名称使用审批定义的名称。
**说明**：这里传入的是国际化文案 Key（即 i18n_resources.texts 参数中的 Key），必须以 @i18n@ 开头，还需要在 i18n_resources.texts 参数中以 Key:Value 格式进行赋值。
**示例值**："@i18n@1" title_display_method | int | 否 | 审批详情页 title 展示模式。
**示例值**：0
**可选值有**：
- 0：如果审批定义和审批实例都有 title，则全部展示，通过竖线分割。
- 1：如果审批定义和审批实例都有 title，只展示审批实例的 title。
**默认值**：`0` node_auto_approval_list | node_auto_approval\[\] | 否 | 设置自动通过的节点。
**数据校验规则**：
- 最大长度：`10` node_id_type | string | 否 | 节点 ID 类型
**示例值**："NON_CUSTOM"
**可选值有**：
- CUSTOM：自定义节点ID
- NON_CUSTOM：非自定义节点ID node_id | string | 否 | 节点 ID 值，可调用 [查看指定审批定义](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/approval/get) 接口，从接口返回的 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"]} ] } ``` ## 响应 ### 响应体 名称 | 类型 | 描述 ---|---|--- code | int | 错误码，非 0 表示失败 msg | string | 错误描述 data | \- | \- instance_code | string | 审批实例 Code ### 响应体示例 ```json { "code": 0, "msg": "success", "data": { "instance_code": "81D31358-93AF-92D6-7425-01A5D67C4E71" } } ``` ### 错误码 HTTP状态码 | 错误码 | 描述 | 排查建议 ---|---|---|--- 400 | 1390001 | param is invalid | 参数错误。排查方案：
- 根据接口文档的参数说明，检查请求时传入的参数是否正确。
- 如果传入的有表单参数（form），则需要检查该参数内传入的表单控件数据是否正确。如果报错信息内包含控件 ID（如 `控件= widget17261088448220001`），可以调用[查看指定审批定义](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/approval/get)或者[获取单个审批实例详情](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/instance/get)接口，获取响应参数 form 值，检索有问题的控件 ID，然后检查该控件的配置是否正确。 400 | 1390015 | approval is not active | 审批定义已停用，请确保当前所用的审批定义已启用后重试。你可以登录[Lark审批管理后台](https://www.larksuite.com/approval/admin/approvalList)，查看相应审批定义是否被停用。
![image.png](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/3991337412ec292a8f61d5c57a5d590b_MbHV5E0Qmr.png) 400 | 1390013 | unsupported approval for free process | 不支持自定义审批流程。 400 | 1395001 | There have been some errors. Please try again later | 服务出现错误。排查方案：
1. 参考接口文档的参数说明，检查请求时传入的参数是否正确。如果传入的有表单参数（form），则需要检查传入的表单控件数据是否正确。
2. 降低请求频率，并重试。如果重试仍然报错，请联系[技术支持](https://applink.larksuite.com/TLJpeNdW)。 更多错误码信息，参见[通用错误码](https://open.larksuite.com/document/ukTMukTMukTM/ugjM14COyUjL4ITN)。