飞书开放平台 Server API 文档

主题

搜索合同 ​

该接口可用于搜索合同信息，包括合同开始时间、合同预计结束时间、合同实际结束时间、合同公司主体等信息

Tip: 该接口会按照应用拥有的「员工资源」的权限范围返回数据，请确定在「开发者后台 - 权限管理 - 数据权限」中申请「员工资源」权限范围。

Warning: 创建合同后，调用搜索接口，会有5s 内数据延迟才能搜索到结果

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/corehr/v2/contracts/search
HTTP MethodPOST
接口频率限制1000 次/分钟、50 次/秒
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可corehr:contract:read 查看合同信息 corehr:contract:write 创建、更新、删除合同信息
字段权限要求> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 corehr:contract.company:read 获取合同主体信息 corehr:contract.period:read 获取合同期限信息 corehr:contract.company:write 读写合同主体信息 contact:user.employee_id:readonly 获取用户 user ID corehr:contract.period:write 读写合同期限信息

请求头 ​

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

查询参数 ​

名称类型必填描述
page_sizeint是分页大小，最大 100
示例值：100
数据校验规则：
- 取值范围：1 ～ 100
page_tokenstring否分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果
示例值：10
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？ - people_corehr_id: 以飞书人事的 ID 来识别用户
默认值：open_id
当值为 user_id，字段权限要求： contact:user.employee_id:readonly 获取用户 user ID

请求体 ​

名称类型必填描述
employment_id_liststring\[\]否雇佣 ID 列表，雇佣ID可通过【查询员工信息】接口查询；最多支持传入20个ID。
示例值：["7140964208476371111"]
contract_id_liststring\[\]否合同 ID 列表，该ID可以通过【批量查询合同】接口获取；最多支持传入20个ID。
> Tip: 注意：以上两个筛选条件如果都填写，则是 「与」 的关系；如果都不填写，默认返回所有的合同列表信息
示例值：["7140964208476372371"]

请求体示例 ​

json
{
    "employment_id_list": [
        "7140964208476371111"
    ],
    "contract_id_list": [
        "7140964208476372371"
    ]
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ itemscontract\[\]查询的合同信息
    └ idstring合同ID
    └ effective_timestring合同开始日期
字段权限要求（满足任一）： corehr:contract.period:read 获取合同期限信息 corehr:contract.period:write 读写合同期限信息
    └ contract_end_datestring合同结束日期
字段权限要求（满足任一）： corehr:contract.period:read 获取合同期限信息 corehr:contract.period:write 读写合同期限信息
    └ expiration_timestring实际结束日期
字段权限要求（满足任一）： corehr:contract.period:read 获取合同期限信息 corehr:contract.period:write 读写合同期限信息
    └ employment_idstring雇佣 ID，详细信息可通过【查询员工信息】接口查询
    └ contract_typeenum合同类型，枚举值可通过文档【飞书人事枚举常量】合同类型（contract_type）枚举定义部分获得
      └ enum_namestring枚举值
      └ displayi18n\[\]枚举多语展示
        └ langstring语言
        └ valuestring内容
    └ first_party_company_idstring合同主体, 详细信息可通过【查询公司详情接口】接口查询获得
字段权限要求（满足任一）： corehr:contract.company:read 获取合同主体信息 corehr:contract.company:write 读写合同主体信息
    └ person_idstring个人信息 ID，详细信息可通过接口文档【批量查询员工信息接口】接口查询获得
    └ duration_typeenum期限类型，枚举值可通过文档【飞书人事枚举常量】合同期限类型（duration_type）枚举定义部分获得
      └ enum_namestring枚举值
      └ displayi18n\[\]枚举多语展示
        └ langstring语言
        └ valuestring内容
    └ contract_numberstring合同编号
    └ signing_typeenum签订类型，枚举值可通过文档【飞书人事枚举常量】签订类型（signing_type）枚举定义部分获得
      └ enum_namestring枚举值
      └ displayi18n\[\]枚举多语展示
        └ langstring语言
        └ valuestring内容
    └ contract_statusenum合同协议状态，枚举值可通过文档【飞书人事枚举常量】合同协议状态（contract_status）枚举定义部分获得
      └ enum_namestring枚举值
      └ displayi18n\[\]枚举多语展示
        └ langstring语言
        └ valuestring内容
    └ renewal_statusenum续签状态，枚举值可通过文档【飞书人事枚举常量】续签状态（renewal_status）枚举定义部分获得
      └ enum_namestring枚举值
      └ displayi18n\[\]枚举多语展示
        └ langstring语言
        └ valuestring内容
    └ signing_timesint第几次签署
  └ page_tokenstring分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token
  └ has_moreboolean是否还有更多项

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "items": [
            {
                "id": "7147527056140813828",
                "effective_time": "2023-01-01 00:00:00",
                "contract_end_date": "2024-01-01",
                "expiration_time": "2023-11-01 00:00:00",
                "employment_id": "6893014062142064135",
                "contract_type": {
                    "enum_name": "labor_contract",
                    "display": [
                        {
                            "lang": "zh-CN",
                            "value": "劳动合同"
                        }
                    ]
                },
                "first_party_company_id": "7091599096804394540",
                "person_id": "7088589447189022252",
                "duration_type": {
                    "enum_name": "fix_term",
                    "display": [
                        {
                            "lang": "zh-CN",
                            "value": "固定期限"
                        }
                    ]
                },
                "contract_number": "0000011",
                "signing_type": {
                    "enum_name": "new",
                    "display": [
                        {
                            "lang": "zh-CN",
                            "value": "新签"
                        }
                    ]
                },
                "contract_status": {
                    "enum_name": "contract_open",
                    "display": [
                        {
                            "lang": "zh-CN",
                            "value": "合同生效中"
                        }
                    ]
                },
                "renewal_status": {
                    "enum_name": "rejected",
                    "display": [
                        {
                            "lang": "zh-CN",
                            "value": "已拒绝"
                        }
                    ]
                },
                "signing_times": 1
            }
        ],
        "page_token": "eVQrYzJBNDNONlk4VFZBZVlSdzlKdFJ4bVVHVExENDNKVHoxaVdiVnViQT0=",
        "has_more": true
    }
}

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

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