飞书开放平台 Server API 文档

主题

查询抄送列表 ​

该接口通过不同条件查询审批系统中符合条件的审批抄送列表。

使用限制 ​

  • 该接口查询结果可能存在延迟，无法保证实时性。

  • 查询时：

    • user_id、approval_code、instance_code、instance_external_id、group_external_id 不能同时为空。

    • approval_code 和 group_external_id 查询结果取并集；instance_code 和 instance_external_id 查询结果取并集；其他查询条件之间均取交集。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/approval/v4/instances/search_cc
HTTP MethodPOST
接口频率限制1000 次/分钟、50 次/秒
支持的应用类型custom
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用approval:approval.list:readonly 查询审批列表
字段权限要求> 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"

查询参数 ​

名称类型必填描述
page_sizeint否分页大小
示例值：10
默认值：10
数据校验规则：
- 取值范围：5 ～ 200
page_tokenstring否分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果
示例值：nF1ZXJ5VGhlbkZldGNoCgAAAAAA6PZwFmUzSldvTC1yU
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

请求体 ​

名称类型必填描述
user_idstring否用户 ID，ID 类型与查询参数 user_id_type 保持一致。
示例值："lwiu098wj"
approval_codestring否审批定义 Code。获取方式：
- 调用创建审批定义接口后，从响应参数 approval_code 获取。 - 登录审批管理后台，在指定审批定义的 URL 中获取，具体操作参见什么是 Approval Code。
注意：
- user_id、approval_code、instance_code、instance_external_id、group_external_id 不能同时为空。
- approval_code 和 group_external_id 查询结果取并集。
示例值："EB828003-9FFE-4B3F-AA50-2E199E2ED942"
instance_codestring否审批实例 Code。获取方式：
- 调用创建审批实例接口后，从响应参数 instance_code 获取。 - 调用批量获取审批实例 ID接口，获取所需的审批实例 Code。
注意：
- user_id、approval_code、instance_code、instance_external_id、group_external_id 不能同时为空。
- instance_code 和 instance_external_id 查询结果取并集。
示例值："EB828003-9FFE-4B3F-AA50-2E199E2ED943"
instance_external_idstring否审批实例的第三方 ID。
注意：
- user_id、approval_code、instance_code、instance_external_id、group_external_id 不能同时为空。
- instance_code 和 instance_external_id 查询结果取并集。
示例值："EB828003-9FFE-4B3F-AA50-2E199E2ED976"
group_external_idstring否审批定义分组的第三方 ID。
注意：
- user_id、approval_code、instance_code、instance_external_id、group_external_id 不能同时为空。
- approval_code 和 group_external_id 查询结果取并集。
示例值："1234567"
cc_titlestring否审批抄送标题。
说明：仅第三方审批存在审批抄送标题。
示例值："test"
read_statusstring否审批抄送状态。
注意：若不设置则查询全部状态，若不在集合中，则报错。
示例值："read"
可选值有：
- READ: 已读 - UNREAD: 未读 - ALL: 所有状态
cc_create_time_fromstring否抄送查询开始时间，Unix 毫秒时间戳。与 cc_create_time_from 参数构成时间段查询条件，仅会返回在该时间段内的审批抄送。
注意：查询时间跨度不得大于 30 天，开始和结束时间必须同时设置或者同时不设置。
示例值："1547654251506"
cc_create_time_tostring否抄送查询结束时间，Unix 毫秒时间戳。与 cc_create_time_from 参数构成时间段查询条件，仅会返回在该时间段内的审批抄送。
注意：查询时间跨度不得大于 30 天，开始和结束时间必须同时设置或者同时不设置。
示例值："1547654251506"
localestring否语言
示例值："zh-CN"
可选值有：
- zh-CN: 中文 - en-US: 英文 - ja-JP: 日文

请求体示例 ​

json
{
    "user_id": "lwiu098wj",
    "approval_code": "EB828003-9FFE-4B3F-AA50-2E199E2ED942",
    "instance_code": "EB828003-9FFE-4B3F-AA50-2E199E2ED943",
    "instance_external_id": "EB828003-9FFE-4B3F-AA50-2E199E2ED976",
    "group_external_id": "1234567",
    "cc_title": "test",
    "read_status": "read",
    "cc_create_time_from": "1547654251506",
    "cc_create_time_to": "1547654251506",
    "locale": "zh-CN"
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ countint查询结果中包含的审批抄送总数
  └ cc_listcc_search_item\[\]审批抄送列表
    └ approvalinstance_search_approval审批定义信息
      └ codestring审批定义 Code
      └ namestring审批定义名称
      └ is_externalboolean是否为第三方审批
      └ externalinstance_search_approval_external第三方审批信息
        └ batch_cc_readboolean是否支持批量读
      └ approval_idstring审批定义 ID
      └ iconstring审批定义图标信息
    └ groupinstance_search_group审批定义分组
      └ external_idstring审批定义分组的第三方 ID
      └ namestring审批定义分组名称
    └ instanceinstance_search_node审批实例信息
      └ codestring审批实例 Code
      └ external_idstring审批实例的第三方 ID
      └ user_idstring审批实例发起人的 user_id
      └ start_timestring审批实例开始时间，Unix 毫秒时间戳
      └ end_timestring审批实例结束时间，Unix 毫秒时间戳
      └ statusstring审批实例状态
可选值有：
- rejected: 已拒绝 - pending: 审批中 - canceled: 已撤回 - deleted: 已删除 - approved: 已通过
      └ titlestring审批实例名称（只有第三方审批有返回值）
      └ extrastring审批实例扩展字段，字符串类型的 JSON 数据
      └ serial_idstring审批流水号
      └ linkinstance_search_link审批实例链接（只有第三方审批有返回值）
        └ pc_linkstring审批实例 PC 端链接
        └ mobile_linkstring审批实例移动端链接
    └ cccc_search_node审批抄送信息
      └ user_idstring审批抄送发起人的 user_id
      └ create_timestring审批抄送开始时间，Unix 毫秒时间戳
      └ read_statusstring审批抄送状态
可选值有：
- read: 已读 - unread: 未读
      └ titlestring审批抄送名称（只有第三方审批有返回值）
      └ extrastring审批抄送扩展字段，字符串类型的 JSON 数据
      └ linkinstance_search_link审批抄送链接（只有第三方审批有返回值）
        └ pc_linkstring审批实例 PC 端链接
        └ mobile_linkstring审批实例移动端链接
  └ page_tokenstring分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token
  └ has_moreboolean是否还有更多项

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "count": 10,
        "cc_list": [
            {
                "approval": {
                    "code": "EB828003-9FFE-4B3F-AA50-2E199E2ED943",
                    "name": "approval",
                    "is_external": true,
                    "external": {
                        "batch_cc_read": false
                    },
                    "approval_id": "7090754740375519252",
                    "icon": "https://lf3-ea.bytetos.com/obj/goofy/ee/approval/approval-admin/image/iconLib/v3/person.png"
                },
                "group": {
                    "external_id": "0004",
                    "name": "groupA"
                },
                "instance": {
                    "code": "EB828003-9FFE-4B3F-AA50-2E199E2ED943",
                    "external_id": "0004_3ED52DC1-AA6C",
                    "user_id": "lwiu098wj",
                    "start_time": "1547654251506",
                    "end_time": "1547654251506",
                    "status": "pending",
                    "title": "test",
                    "extra": "{}",
                    "serial_id": "201902020001",
                    "link": {
                        "pc_link": "https://www.baidu.com/",
                        "mobile_link": "https://www.baidu.com/"
                    }
                },
                "cc": {
                    "user_id": "lwiu098wj",
                    "create_time": "1547654251506",
                    "read_status": "read",
                    "title": "test",
                    "extra": "{}",
                    "link": {
                        "pc_link": "https://www.baidu.com/",
                        "mobile_link": "https://www.baidu.com/"
                    }
                }
            }
        ],
        "page_token": "nF1ZXJ5VGhlbkZldGNoCgAAAAAA6PZwFmUzSldvTC1yU",
        "has_more": false
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
4001390001param is invalid参数错误。排查方案： - 根据接口文档的参数说明，检查请求时传入的参数是否正确。 - 如果传入的有表单参数（form），则需要检查该参数内传入的表单控件数据是否正确。如果报错信息内包含控件 ID（如 控件= widget17261088448220001），可以调用查看指定审批定义或者获取单个审批实例详情接口，获取响应参数 form 值，检索有问题的控件 ID，然后检查该控件的配置是否正确。
4001390002approval code not found找不到审批定义 Code，检查传入的审批定义 Code 是否正确。 审批定义 Code 获取方式： - 调用创建审批定义接口后，从响应参数 approval_code 获取。 - 登录审批管理后台，在指定审批定义的 URL 中获取，具体操作参见什么是 Approval Code。
4001390003instance code not found找不到审批实例 Code，检查传入的审批实例 Code 是否正确。 审批实例 Code 获取方式： - 调用创建审批实例接口后，从响应参数 instance_code 获取。 - 调用批量获取审批实例 ID接口，获取所需的审批实例 Code。 - 调用查询实例列表，设置过滤条件查询指定的审批实例 Code。
4001395001There have been some errors. Please try again later服务出现错误。排查方案： 1. 参考接口文档的参数说明，检查请求时传入的参数是否正确。如果传入的有表单参数（form），则需要检查传入的表单控件数据是否正确。 2. 降低请求频率，并重试。如果重试仍然报错，请联系技术支持。

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

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

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