飞书开放平台 Server API 文档

主题

获取单个审批实例详情 ​

通过审批实例 Code 获取指定审批实例的详细信息，包括审批实例的名称、创建时间、发起审批的用户、状态以及任务列表等信息。

请求 ​

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

请求头 ​

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

路径参数 ​

名称类型描述
instance_idstring审批实例 Code。获取方式：
- 创建审批实例 后，从返回结果中获取审批实例 Code。如果在创建的时候传了 uuid 参数，则本参数也可以通过传 uuid 获取指定审批实例详情。 - 调用批量获取审批实例 ID，获取指定审批定义内的审批实例 Code。 - 调用查询实例列表，设置过滤条件查询指定的审批实例 Code。
示例值："81D31358-93AF-92D6-7425-01A5D67C4E71"

查询参数 ​

名称类型必填描述
localestring否语言。默认值为创建审批定义时在 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_idstring否发起审批的用户 ID，ID 类型由 user_id_type 参数指定。
示例值：f7cb567e
user_id_typestring否用户 ID 类型
示例值：user_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
nested_mutable_groupboolean否返回完整的多维表格控件
示例值：true

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ approval_namestring审批名称
  └ start_timestring审批创建时间，毫秒级时间戳。
  └ end_timestring审批完成时间，毫秒级时间戳。审批未完成时该参数值为 0。
  └ user_idstring发起审批的用户 user_id
  └ open_idstring发起审批的用户 open_id
  └ serial_numberstring审批单编号
  └ department_idstring发起审批用户所在部门的 ID
  └ statusstring审批实例状态
可选值有：
- PENDING: 审批中 - APPROVED: 通过 - REJECTED: 拒绝 - CANCELED: 撤回 - DELETED: 删除
  └ uuidstring审批实例的唯一标识 id
  └ formstring审批表单控件 JSON 字符串，控件值详细说明参见本文下方 控件值说明 章节。
  └ task_listinstance_task\[\]审批任务列表
    └ idstring审批任务 ID
    └ user_idstring审批人的 user_id，自动通过、自动拒绝时该参数返回值为空。
    └ open_idstring审批人的 open_id，自动通过、自动拒绝时该参数返回值为空。
    └ statusstring审批任务状态
可选值有：
- PENDING: 审批中 - APPROVED: 通过 - REJECTED: 拒绝 - TRANSFERRED: 已转交 - DONE: 完成
    └ node_idstring审批任务所属的审批节点 ID
    └ node_namestring审批任务所属的审批节点名称
    └ custom_node_idstring审批任务所属的审批节点的自定义 ID。如果没设置自定义 ID，则不返回该参数值。
    └ typestring审批方式
可选值有：
- AND: 会签 - OR: 或签 - AUTO_PASS: 自动通过 - AUTO_REJECT: 自动拒绝 - SEQUENTIAL: 按顺序
    └ start_timestring审批任务的开始时间，毫秒级时间戳。
    └ end_timestring审批任务的完成时间，毫秒级时间戳。未完成时返回 0。
  └ comment_listinstance_comment\[\]评论列表
    └ idstring评论 ID
    └ user_idstring发表评论的用户 user_id
    └ open_idstring发表评论的用户 open_id
    └ commentstring评论内容
    └ create_timestring评论时间，毫秒级时间戳。
    └ filesfile\[\]评论附件
      └ urlstring附件路径
      └ file_sizeint附件大小。单位：字节
      └ titlestring附件标题
      └ typestring附件类别
- image：图片 - attachment：附件，与上传时选择的类型一致
  └ timelineinstance_timeline\[\]审批动态
    └ typestring动态类型。不同的动态类型，对应 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_timestring发生时间，毫秒级时间戳。
    └ user_idstring产生该动态的用户 user_id
    └ open_idstring产生该动态的用户 open_id
    └ user_id_liststring\[\]被抄送人列表，列表内包含的是用户 user_id。
    └ open_id_liststring\[\]被抄送人列表，列表内包含的是用户 open_id。
    └ task_idstring产生动态关联的任务 ID
    └ commentstring理由
    └ cc_user_listinstance_cc_user\[\]抄送人列表
      └ user_idstring抄送人的 user_id
      └ cc_idstring审批实例内抄送唯一标识
      └ open_idstring抄送人的 open_id
    └ extstring其他信息，JSON 格式，目前包括 user_id_list, user_id，open_id_list，open_id
    └ node_keystring产生审批任务的节点 key
    └ filesfile\[\]审批附件
      └ urlstring附件路径
      └ file_sizeint附件大小。单位：字节
      └ titlestring附件标题
      └ typestring附件类别
- image：图片 - attachment：附件，与上传时选择的类型一致
  └ modified_instance_codestring修改的原实例 Code，仅在查询修改实例时显示该字段
  └ reverted_instance_codestring撤销的原实例 Code，仅在查询撤销实例时显示该字段
  └ approval_codestring审批定义 Code
  └ revertedboolean单据是否被撤销
  └ instance_codestring审批实例 Code

控件值说明 ​

类型说明
input单行文本控件
textarea多行文本控件
date日期控件。RFC3339 格式，示例值：2019-10-01T08:12:01+08:00。
radio/radioV2单选控件。value 对应的是选项文本，如果关联外部选项则对应的是选项 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 说明可参见用户身份概述。

以上控件的 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，你可以调用获取单个审批实例详情接口，根据审批实例 Code 获取实例详情。
attachment附件控件。value 为附件地址。
checkbox/checkboxV2多选控件。value 对应的是选项文本，如果关联外部选项则对应的是选项 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，详细介绍参见文档；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。
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状态码错误码描述排查建议
4001390001param is invalid参数错误。排查方案： - 根据接口文档的参数说明，检查请求时传入的参数是否正确。 - 如果传入的有表单参数（form），则需要检查该参数内传入的表单控件数据是否正确。如果报错信息内包含控件 ID（如 控件= widget17261088448220001），可以调用查看指定审批定义或者获取单个审批实例详情接口，获取响应参数 form 值，检索有问题的控件 ID，然后检查该控件的配置是否正确。
4001395001There have been some errors. Please try again later服务出现错误。排查方案： 1. 参考接口文档的参数说明，检查请求时传入的参数是否正确。如果传入的有表单参数（form），则需要检查传入的表单控件数据是否正确。 2. 降低请求频率，并重试。如果重试仍然报错，请联系技术支持。
4001390003instance code not found找不到审批实例 Code，检查传入的审批实例 Code 是否正确。 审批实例 Code 获取方式： - 调用创建审批实例接口后，从响应参数 instance_code 获取。 - 调用批量获取审批实例 ID接口，获取所需的审批实例 Code。 - 调用查询实例列表，设置过滤条件查询指定的审批实例 Code。
4031390009no operation permission没有操作权限。请前往飞书审批管理后台，进入指定审批定义编辑页面，在流程设计里的审批操作权限内，检查操作权限是否正确配置。
4001390004user_id or open_id not found检查传入的 user_id 参数是否正确，user_id 的类型需要和 user_id_type 一致，且需要确保 ID 值正确。

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

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

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