# 获取单个审批实例详情 通过审批实例 Code 获取指定审批实例的详细信息，包括审批实例的名称、创建时间、发起审批的用户、状态以及任务列表等信息。 ## 请求 基本 |   ---|--- HTTP URL | https://open.feishu.cn/open-apis/approval/v4/instances/:instance_id HTTP Method | GET 接口频率限制 | [1000 次/分钟、50 次/秒](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN) 支持的应用类型 | Custom App、Store App 权限要求
**调用该 API 所需的权限。开启其中任意一项权限即可调用**
开启任一权限即可 | 查看、创建、更新、删除审批应用相关信息(approval:approval)
访问审批应用(approval:approval:readonly)
查看、创建、更新、删除原生审批实例相关信息(approval:instance) 字段权限要求 | **注意事项**：该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请
获取用户 user ID(contact:user.employee_id:readonly) ### 请求头 名称 | 类型 | 必填 | 描述 ---|---|---|--- Authorization | string | 是 | `tenant_access_token`
**值格式**："Bearer `access_token`"
**示例值**："Bearer t-7f1bcd13fc57d46bac21793a18e560"
[了解更多：如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use) ### 路径参数 名称 | 类型 | 描述 ---|---|--- instance_id | string | 审批实例 Code。获取方式：
- [创建审批实例](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/instance/create) 后，从返回结果中获取审批实例 Code。如果在创建的时候传了 uuid 参数，则本参数也可以通过传 uuid 获取指定审批实例详情。
- 调用[批量获取审批实例 ID](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/instance/list)，获取指定审批定义内的审批实例 Code。
- 调用[查询实例列表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/instance/query)，设置过滤条件查询指定的审批实例 Code。
**示例值**："81D31358-93AF-92D6-7425-01A5D67C4E71" ### 查询参数 名称 | 类型 | 必填 | 描述 ---|---|---|--- locale | string | 否 | 语言。默认值为[创建审批定义](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/approval/create)时在 i18n_resources 参数中配置的 is_default 取值为 true 的语言。
**示例值**：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：俄语 user_id | string | 否 | 发起审批的用户 ID，ID 类型由 user_id_type 参数指定。
**示例值**：f7cb567e user_id_type | string | 否 | 用户 ID 类型
**示例值**：user_id
**可选值有**：
- open_id：标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。[了解更多：如何获取 Open ID](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-openid)
- union_id：标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。[了解更多：如何获取 Union ID？](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-union-id)
- user_id：标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。[了解更多：如何获取 User ID？](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-user-id)
**默认值**：`open_id`
**当值为 `user_id`，字段权限要求**：
获取用户 user ID(contact:user.employee_id:readonly) nested_mutable_group | boolean | 否 | 返回完整的多维表格控件
**示例值**：true ## 响应 ### 响应体 名称 | 类型 | 描述 ---|---|--- code | int | 错误码，非 0 表示失败 msg | string | 错误描述 data | \- | \- approval_name | string | 审批名称 start_time | string | 审批创建时间，毫秒级时间戳。 end_time | string | 审批完成时间，毫秒级时间戳。审批未完成时该参数值为 0。 user_id | string | 发起审批的用户 user_id open_id | string | 发起审批的用户 open_id serial_number | string | 审批单编号 department_id | string | 发起审批用户所在部门的 ID status | string | 审批实例状态
**可选值有**：
- PENDING：审批中
- APPROVED：通过
- REJECTED：拒绝
- CANCELED：撤回
- DELETED：删除 uuid | string | 审批实例的唯一标识 id form | string | 审批表单控件 JSON 字符串，控件值详细说明参见本文下方 **控件值说明** 章节。 task_list | instance_task\[\] | 审批任务列表 id | string | 审批任务 ID user_id | string | 审批人的 user_id，自动通过、自动拒绝时该参数返回值为空。 open_id | string | 审批人的 open_id，自动通过、自动拒绝时该参数返回值为空。 status | string | 审批任务状态
**可选值有**：
- PENDING：审批中
- APPROVED：通过
- REJECTED：拒绝
- TRANSFERRED：已转交
- DONE：完成 node_id | string | 审批任务所属的审批节点 ID node_name | string | 审批任务所属的审批节点名称 custom_node_id | string | 审批任务所属的审批节点的自定义 ID。如果没设置自定义 ID，则不返回该参数值。 type | string | 审批方式
**可选值有**：
- AND：会签
- OR：或签
- AUTO_PASS：自动通过
- AUTO_REJECT：自动拒绝
- SEQUENTIAL：按顺序 start_time | string | 审批任务的开始时间，毫秒级时间戳。 end_time | string | 审批任务的完成时间，毫秒级时间戳。未完成时返回 0。 comment_list | instance_comment\[\] | 评论列表 id | string | 评论 ID user_id | string | 发表评论的用户 user_id open_id | string | 发表评论的用户 open_id comment | string | 评论内容 create_time | string | 评论时间，毫秒级时间戳。 files | file\[\] | 评论附件 url | string | 附件路径 file_size | int | 附件大小。单位：字节 title | string | 附件标题 type | string | 附件类别
- image：图片
- attachment：附件，与上传时选择的类型一致 timeline | instance_timeline\[\] | 审批动态 type | string | 动态类型。不同的动态类型，对应 ext 返回值也不同，具体参考以下各枚举值描述。
**可选值有**：
- START：审批开始。对应的 ext 参数不会返回值。
- PASS：通过。对应的 ext 参数不会返回值。
- REJECT：拒绝。对应的 ext 参数不会返回值。
- AUTO_PASS：自动通过。对应的 ext 参数不会返回值。
- AUTO_REJECT：自动拒绝。对应的 ext 参数不会返回值。
- REMOVE_REPEAT：去重。对应的 ext 参数不会返回值。
- TRANSFER：转交。对应的 ext 参数返回的 user_id_list 包含被转交人的用户 ID。
- ADD_APPROVER_BEFORE：前加签。对应的 ext 参数返回的 user_id_list 包含被加签人的用户 ID。
- ADD_APPROVER：并加签。对应的 ext 参数返回的 user_id_list 包含被加签人的用户 ID。
- ADD_APPROVER_AFTER：后加签。对应的 ext 参数返回的 user_id_list 包含被加签人的用户 ID。
- DELETE_APPROVER：减签。对应的 ext 参数返回的 user_id_list 包含被加签人的用户 ID。
- ROLLBACK_SELECTED：指定回退。对应的 ext 参数不会返回值。
- ROLLBACK：全部回退。对应的 ext 参数不会返回值。
- CANCEL：撤回。对应的 ext 参数不会返回值。
- DELETE：删除。对应的 ext 参数不会返回值。
- CC：抄送。对应的 ext 参数返回的 user_id 包含抄送人的用户 ID。 create_time | string | 发生时间，毫秒级时间戳。 user_id | string | 产生该动态的用户 user_id open_id | string | 产生该动态的用户 open_id user_id_list | string\[\] | 被抄送人列表，列表内包含的是用户 user_id。 open_id_list | string\[\] | 被抄送人列表，列表内包含的是用户 open_id。 task_id | string | 产生动态关联的任务 ID comment | string | 理由 cc_user_list | instance_cc_user\[\] | 抄送人列表 user_id | string | 抄送人的 user_id cc_id | string | 审批实例内抄送唯一标识 open_id | string | 抄送人的 open_id ext | string | 其他信息，JSON 格式，目前包括 user_id_list, user_id，open_id_list，open_id node_key | string | 产生审批任务的节点 key files | file\[\] | 审批附件 url | string | 附件路径 file_size | int | 附件大小。单位：字节 title | string | 附件标题 type | string | 附件类别
- image：图片
- attachment：附件，与上传时选择的类型一致 modified_instance_code | string | 修改的原实例 Code，仅在查询修改实例时显示该字段 reverted_instance_code | string | 撤销的原实例 Code，仅在查询撤销实例时显示该字段 approval_code | string | 审批定义 Code reverted | boolean | 单据是否被撤销 instance_code | string | 审批实例 Code ### 控件值说明 |类型|说明| |-|-| |input|单行文本控件| |textarea|多行文本控件| |date|日期控件。RFC3339 格式，示例值：2019-10-01T08:12:01+08:00。| |radio/radioV2|单选控件。value 对应的是选项文本，如果[关联外部选项](https://open.feishu.cn/document/ukTMukTMukTM/uADM4QjLwADO04CMwgDN)则对应的是选项 ID。| |address|地址控件。示例格式：`China/Beijing/Beijing/Chaoyang Qu/chang an jie`，如果地址控件允许输入详细地址，则最后一项为用户输入的详细地址。| 以上控件的 JSON 示例值如下： ```json { "id": "widget1", "custom_id": "user_info", "name": "Item application", "type": "input", "value": "data" } ``` |类型|说明| |-|-| |number|数字控件| |amount|金额控件| |formula|计算公式控件| 以上控件的 JSON 示例值如下： ```json { "id": "widget1", "name": "Item application", "type": "number", "value": 1234.56 } ``` |类型|说明| |-|-| |contact|联系人控件。value 包含的是用户 user_id；open_ids 包含的是用户 open_id。不同用户 ID 说明可参见[用户身份概述](https://open.feishu.cn/document/home/user-identity-introduction/introduction)。| 以上控件的 JSON 示例值如下： ```json { "id": "widget1", "name": "Item application", "type": "contact", "value": ["f8ca557e"], "open_ids": ["ou_12345"] } ``` |类型|说明| |-|-| |attachmentV2|附件控件。ext 为附件名字、value 为附件地址，按逗号分隔，且链接有效时长为 12 小时。| |image/imageV2|图片控件。ext 为图片名字、value 为图片地址，按逗号分隔，且链接有效时长为 12 小时。
**注意**：客户端页面上发起审批所传递的图片控件，使用接口无法获取图片名称。 以上控件的 JSON 示例值如下： ```json { "id": "widget1", "name": "Item application", "type": "attachmentV2", "ext": "'Item 1 name','Item 2 name'", "value": ["Item 1", "Item 2"] } ``` |类型|说明| |-|-| |connect| 关联审批控件。value 包含的是被关联的审批实例 Code，你可以调用[获取单个审批实例详情](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/instance/get)接口，根据审批实例 Code 获取实例详情。| |attachment|附件控件。value 为附件地址。| |checkbox/checkboxV2|多选控件。value 对应的是选项文本，如果[关联外部选项](https://open.feishu.cn/document/ukTMukTMukTM/uADM4QjLwADO04CMwgDN)则对应的是选项 ID。| 以上控件的 JSON 示例值如下： ```json { "id": "widget1", "name": "Item application", "type": "checkbox", "value": ["Item 1"] } ``` |类型|说明| |-|-| |dateInterval|日期区间控件。start 和 end 表示区间开始时间与结束时间，满足 RFC3339 格式；interval 表示时长（天）。| 以上控件的 JSON 示例值如下： ```json { "id": "widget1", "name": "Item application", "type": "dateInterval", "value": { "start": "2019-10-01T08:12:01+08:00", "end": "2019-10-02T08:12:01+08:00", "interval": 2.0 } } ``` |类型|说明| |-|-| |fieldList|明细/表格控件。value 是二维数组，根据审批定义内 **明细/表格** 控件所包含的控件，依次设置的控件 JSON 值。| 以上控件的 JSON 示例值如下： ```json { "id": "widget1", "name": "Item application", "type": "fieldList", "value": [ [ { "id": "widget1", "type": "checkbox", "value": ["jxpsebqp-0"] } ] ] } ``` |类型|说明| |-|-| |document|文档控件。token 返回的是文档的 document_id，详细介绍参见[文档](https://open.feishu.cn/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/document-docx/docx-overview#e18a49a1)；type 是文档类型；title 是文档标题；url 是文档链接。| 以上控件的 JSON 示例值如下： ```json { "id":"widget1", "type":"document", "value": { "token": "doxcx7B8OzLFHExkiwYuPGAwf", "type": "doc", "title": "title", "url": "https://xxx.xxx.xxx/docx/doxcx7B8OzLFHExkiwYuPGAwf" } } ``` 以上控件的 JSON 示例值如下： |类型|说明| |-|-| |department|部门控件。open_id 返回的是部门的 open_department_id，关于部门 open_department_id 的说明参见[部门 ID](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview#9c02ed7a)。| ```json { "id":"widget1", "type":"department", "value":[ { "open_id":"od-xxx" } ] } ``` |类型|说明| |-|-| |leaveGroup|请假控件组。value 内，name 是假期名称；start 和 end 是假期开始时间与结束时间，满足 RFC3339 格式；interval 是时长（天），部分假期类型用户手动输入请假时长。| 以上控件的 JSON 示例值如下： ```json { "id": "widget1", "name": "leave", "type": "leaveGroup", "value": { "name": "annual leave" "start": "2019-10-01T00:00:00+08:00", "end": "2019-10-02T00:0:00+08:00", "interval": 2.0 } } ``` |类型|说明| |-|-| |leaveGroupV2|请假控件组。value 内，name 是假期名称；start 和 end 是假期开始时间与结束时间，满足 RFC3339 格式；interval 是时长（天），部分假期类型用户手动输入请假时长；unit 是时长单位，取值 DAY/HOUR；reason 是请假原因。| 以上控件的 JSON 示例值如下： ```json { "id": "widget1", "name": "leave", "type": "widgetLeaveGroupV2", "value": { "name": "annual leave" "start": "2019-10-01T00:00:00+08:00", "end": "2019-10-02T00:0:00+08:00", "interval": 2.0, "unit": "DAY", "reason": "out going" } } ``` |类型|说明| |-|-| |remedyGroup|补卡控件组。value 内 time 为补卡时间，满足 RFC3339 格式；reason 是补卡原因。| 以上控件的 JSON 示例值如下： ```json { "id": "widget1", "name": "remedy", "type": "remedyGroup", "value": { "time": "2019-10-01T08:12:01+08:00", "reason": "forgot" } } ``` |类型|说明| |-|-| |shiftGroup|换班控件组。value 内，shiftTime 是换班时间、returnTime 是 对调日期，均满足 RFC3339 格式；reason 是换班原因。| 以上控件的 JSON 示例值如下： ```json { "id": "widget1", "name": "shift", "type": "shiftGroup", "value": { "shiftTime": "2019-10-01T08:12:01+08:00", "returnTime": "2019-10-02T08:12:01+08:00", "reason": "ask for leave" } } ``` |类型|说明| |-|-| |workGroup|加班控件组。value 内，name 是加班名称；start 和 end 是加班开始时间和结束时间，满足 RFC3339 格式；interval 是加班时长（天）；reason 是加班原因。| 以上控件的 JSON 示例值如下： ```json { "id": "widget1", "name": "work", "type": "workGroup", "value": { "name": "Overtime pay" "start": "2019-10-01T08:12:01+08:00", "end": "2019-10-02T08:12:01+08:00", "interval": 2.0, "reason": "ask for leave" } } ``` |类型|说明| |-|-| |tripGroup|出差控件组。各参数说明参见以下代码注释。| 以上控件的 JSON 示例值如下： ```json { "id": "widget1", "name": "trip", "type": "tripGroup", "value": { "schedule": [{ "start": "2019-10-0T00:00:00Z+08:00", // 出差开始时间，满足 RFC3339 格式。 "end": "2019-10-01T00:00:00Z+08:00", // 出差结束时间，满足 RFC3339 格式。 "interval": 123.45, // 当次出差时长（天） "departure": "China/Beijing/Beijing", // 出发地 "destination": "China/Shanghai/Shanghai", // 目的地 "transport": "Airplane", // 交通工具 "oneRound": "One Way", // 单程/往返 "remark": "business", // 备注 }], "interval": 2.0, // 出差总时长（天） "reason": "business", // 出差事由 "peer": ["f7cb567e"], // 同行人的用户 ID } } ``` |类型|说明| |-|-| |telephone|电话控件。value 内，country_code 是区号；national_number 是手机号。| 以上控件的 JSON 示例值如下： ```json { "id":"widget1", "type":"telephone", "value": { "country_code":"+86", "national_number":"13122222222" } } ``` ### 响应体示例 ```json { "code": 0, "msg": "success", "data": { "approval_name": "Payment", "start_time": "1564590532967", "end_time": "1564590532967", "user_id": "f3ta757q", "open_id": "ou_3cda9c969f737aaa05e6915dce306cb9", "serial_number": "202102060002", "department_id": "od-8ec33ffec336c3a39a278bc25e931676", "status": "PENDING", "uuid": "1234567", "form": "[{\"id\": \"widget1\",\"custom_id\": \"user_info\",\"name\": \"Item application\",\"type\": \"textarea\"}]", "task_list": [ { "id": "1234", "user_id": "f7cb567e", "open_id": "ou_123457", "status": "PENDING", "node_id": "46e6d96cfa756980907209209ec03b64", "node_name": "开始", "custom_node_id": "manager", "type": "AND", "start_time": "1564590532967", "end_time": "0" } ], "comment_list": [ { "id": "1234", "user_id": "f7cb567e", "open_id": "ou_123456", "comment": "ok", "create_time": "1564590532967", "files": [ { "url": "https://p3-approval-sign.byteimg.com/lark-approval-attachment/image/20220714/1/332f3596-0845-4746-a4bc-818d54ad435b.png~tplv-ottatrvjsm-image.image?x-expires=1659033558&x-signature=6edF3k%2BaHeAuvfcBRGOkbckoUl4%3D#.png", "file_size": 186823, "title": "e018906140ed9388234bd03b0.png", "type": "image" } ] } ], "timeline": [ { "type": "PASS", "create_time": "1564590532967", "user_id": "f7cb567e", "open_id": "ou_123456", "user_id_list": [ "f7cb567e" ], "open_id_list": [ "ou_123456" ], "task_id": "1234", "comment": "ok", "cc_user_list": [ { "user_id": "eea5gefe", "cc_id": "123445", "open_id": "ou_12345" } ], "ext": "{\"user_id\":\"62d4a44c\",\"open_id\":\"ou_123456\"}", "node_key": "APPROVAL_240330_4058663", "files": [ { "url": "https://p3-approval-sign.byteimg.com/lark-approval-attachment/image/20220714/1/332f3596-0845-4746-a4bc-818d54ad435b.png~tplv-ottatrvjsm-image.image?x-expires=1659033558&x-signature=6edF3k%2BaHeAuvfcBRGOkbckoUl4%3D#.png", "file_size": 186823, "title": "e018906140ed9388234bd03b0.png", "type": "image" } ] } ], "modified_instance_code": "81D31358-93AF-92D6-7425-01A5D67C4E71", "reverted_instance_code": "81D31358-93AF-92D6-7425-01A5D67C4E71", "approval_code": "7C468A54-8745-2245-9675-08B7C63E7A85", "reverted": false, "instance_code": "81D31358-93AF-92D6-7425-01A5D67C4E71" } } ``` ### 错误码 HTTP状态码 | 错误码 | 描述 | 排查建议 ---|---|---|--- 400 | 1390001 | param is invalid | 参数错误。排查方案：
- 根据接口文档的参数说明，检查请求时传入的参数是否正确。
- 如果传入的有表单参数（form），则需要检查该参数内传入的表单控件数据是否正确。如果报错信息内包含控件 ID（如 `控件= widget17261088448220001`），可以调用[查看指定审批定义](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/approval/get)或者[获取单个审批实例详情](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/instance/get)接口，获取响应参数 form 值，检索有问题的控件 ID，然后检查该控件的配置是否正确。 400 | 1395001 | There have been some errors. Please try again later | 服务出现错误。排查方案：
1. 参考接口文档的参数说明，检查请求时传入的参数是否正确。如果传入的有表单参数（form），则需要检查传入的表单控件数据是否正确。
2. 降低请求频率，并重试。如果重试仍然报错，请联系[技术支持](https://applink.feishu.cn/TLJpeNdW)。 400 | 1390003 | instance code not found | 找不到审批实例 Code，检查传入的审批实例 Code 是否正确。
审批实例 Code 获取方式：
- 调用[创建审批实例](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/instance/create)接口后，从响应参数 instance_code 获取。
- 调用[批量获取审批实例 ID](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/instance/list)接口，获取所需的审批实例 Code。
- 调用[查询实例列表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/approval-v4/instance/query)，设置过滤条件查询指定的审批实例 Code。 403 | 1390009 | no operation permission | 没有操作权限。请前往[飞书审批管理后台](https://www.feishu.cn/approval/admin/approvalList)，进入指定审批定义编辑页面，在流程设计里的审批操作权限内，检查操作权限是否正确配置。 400 | 1390004 | user_id or open_id not found | 检查传入的 user_id 参数是否正确，user_id 的类型需要和 user_id_type 一致，且需要确保 ID 值正确。 更多错误码信息，参见[通用错误码](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN)。