飞书开放平台 Server API 文档

主题

查询指定时间范围地点版本 ​

  • 接口支持查询出对象生效时间段在指定的start_date和end_date之间的版本（即：会查询出生效时间段和查询时间段有交集的版本）
  • 接口支持对象版本相关字段的查询和返回（默认返回id和version_id）

Tip: 延迟说明：数据库主从延迟2s以内，即：直接创建对象后2s内调用此接口可能查询不到数据。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/corehr/v2/locations/query_multi_timeline
HTTP MethodPOST
接口频率限制5 次/秒
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可corehr:locations:read 获取地点信息 corehr:locations:write 更新地点信息

请求头 ​

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

请求体 ​

名称类型必填描述
location_idsstring\[\]是地点ID。ID获取方式： - 调用【创建地点】【批量分页查询地点】等接口可以返回地点ID
示例值：["7094136522860922111"]
数据校验规则：
- 长度范围：1 ～ 10
start_datestring否查询开始时间（包含）
示例值："2024-01-01"
数据校验规则：
- 长度范围：10 ～ 10 字符 - 正则校验：`^((([0-9]{3}[1-9]
end_datestring否查询结束时间(不包含)
示例值："2024-12-31"
数据校验规则：
- 长度范围：10 ～ 10 字符 - 正则校验：`^((([0-9]{3}[1-9]
fieldsstring\[\]否返回数据的字段列表，可选值 - location_name：地点名称 - code：编码 - active ：是否启用 - parent_location：上级地点 - description：描述 - effective_date：当前版本生效日期 - expiration_date：当前版本失效日期 - location_usage：地点用途 - working_hours_type：工时制度 - locale：区域设置 - time_zone：时区 - display_language：默认语言 - address：地址
示例值：["location_name"]
数据校验规则：
- 长度范围：0 ～ 100

请求体示例 ​

json
{
    "location_ids": [
        "7094136522860922111"
    ],
    "start_date": "2024-01-01",
    "end_date": "2024-12-31",
    "fields": [
        "location_name"
    ]
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ itemslocation_timeline\[\]地点信息
    └ location_version_datalocation_version_data\[\]地点版本信息
      └ location_idstring地点ID
      └ location_version_idstring地点版本ID
      └ location_namesi18n\[\]地点名称
        └ langstring语言 - 中文用zh-CN，英文用en-US。
        └ valuestring文本内容
      └ parent_location_idstring上级地点ID - 若查询的是一级地点，则该字段不展示
      └ effective_datestring当前版本生效日期 - 返回格式：YYYY-MM-DD （最小单位到日） - 日期范围:1900-01-01 ～9999-12-31 - 详情可以参考时间轴介绍
      └ expiration_datestring当前版本失效日期 - 返回格式：YYYY-MM-DD （最小单位到日） - 日期范围:1900-01-01 ～9999-12-31 - 详情可以参考时间轴介绍
      └ activeboolean是否启用
      └ descriptionsi18n\[\]描述
        └ langstring语言 - 中文用zh-CN，英文用en-US。
        └ valuestring文本内容
      └ codestring编码
      └ location_usagesenum\[\]地点用途，枚举值及详细信息可通过【批量查询地点用途】接口查询获得。 - 请求参数object_api_name=location；custom_api_name=location_usage
        └ enum_namestring枚举值
        └ displayi18n\[\]枚举多语展示
          └ langstring语言 - 中文用zh-CN，英文用en-US。
          └ valuestring文本内容
      └ localeenum区域设置ID - 枚举值及详细信息可通过【获取字段详情】接口查询获得。 - 请求参数object_api_name=location；custom_api_name=locale
        └ enum_namestring枚举值
        └ displayi18n\[\]枚举多语展示
          └ langstring语言 - 中文用zh-CN，英文用en-US。
          └ valuestring文本内容
      └ time_zone_idstring时区 ID - 详细信息可通过【查询时区信息】接口查询获得。
      └ display_language_idstring默认语言 ID - 详细信息可通过【查询语言信息】。
      └ working_hours_type_idstring工时制度 ID - 详细信息可通过【批量查询工时制度】
    └ addressaddress\[\]地址信息
      └ full_address_local_scriptstring完整地址（本地文字）
      └ full_address_western_scriptstring完整地址（西方文字）
      └ address_idstring地址 ID
      └ country_region_idstring国家 / 地区 ID。ID获取方式： - 可通过【查询国家/地区信息】接口获取
      └ region_idstring主要行政区 ID。ID获取方式： - 可通过【查询省份/行政区信息】接口获取
      └ city_idstring城市ID。ID获取方式： - 调用【查询城市信息】接口可以返回城市ID
      └ distinct_idstring区县ID。ID获取方式： - 调用【查询区县信息】接口可以返回区县ID
      └ address_line1string地址行 1
      └ address_line2string地址行 2
      └ address_line3string地址行 3
      └ address_line4string地址行 4
      └ address_line5string地址行 5
      └ address_line6string地址行 6
      └ address_line7string地址行 7
      └ address_line8string地址行 8
      └ address_line9string地址行 9
      └ local_address_line1string地址行 1（非拉丁语系的本地文字）
      └ local_address_line2string地址行 2（非拉丁语系的本地文字）
      └ local_address_line3string地址行 3（非拉丁语系的本地文字）
      └ local_address_line4string地址行 4（非拉丁语系的本地文字）
      └ local_address_line5string地址行 5（非拉丁语系的本地文字）
      └ local_address_line6string地址行 6（非拉丁语系的本地文字）
      └ local_address_line7string地址行 7（非拉丁语系的本地文字）
      └ local_address_line8string地址行 8（非拉丁语系的本地文字）
      └ local_address_line9string地址行 9（非拉丁语系的本地文字）
      └ postal_codestring邮政编码
      └ address_type_listenum\[\]地址类型 - 枚举值及详细信息可通过【获取字段详情】接口查询获得。 - 请求参数object_api_name=address；custom_api_name=address_type
        └ enum_namestring枚举值
        └ displayi18n\[\]枚举多语展示
          └ langstring语言 - 中文用zh-CN，英文用en-US。
          └ valuestring文本内容
      └ is_primaryboolean主要地址
      └ is_publicboolean公开地址

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "items": [
            {
                "location_version_data": [
                    {
                        "location_id": "4719456877659520852",
                        "location_version_id": "7238516215202170412",
                        "location_names": [
                            {
                                "lang": "zh-CN",
                                "value": "中文示例"
                            }
                        ],
                        "parent_location_id": "8961456877659520953",
                        "effective_date": "2020-05-01",
                        "expiration_date": "2020-05-02",
                        "active": true,
                        "descriptions": [
                            {
                                "lang": "zh-CN",
                                "value": "中文示例"
                            }
                        ],
                        "code": "BD38591",
                        "location_usages": [
                            {
                                "enum_name": "phone_type",
                                "display": [
                                    {
                                        "lang": "zh-CN",
                                        "value": "中文示例"
                                    }
                                ]
                            }
                        ],
                        "locale": {
                            "enum_name": "phone_type",
                            "display": [
                                {
                                    "lang": "zh-CN",
                                    "value": "中文示例"
                                }
                            ]
                        },
                        "time_zone_id": "4690238309151997779",
                        "display_language_id": "4690238309151997779",
                        "working_hours_type_id": "4690238309151997779"
                    }
                ],
                "address": [
                    {
                        "full_address_local_script": "中国北京北京",
                        "full_address_western_script": "Beijing, Beijing, China,",
                        "address_id": "6989822217869624863",
                        "country_region_id": "6862995757234914824",
                        "region_id": "6863326815667095047",
                        "city_id": "6863333254578046471",
                        "distinct_id": "6863333516579440141",
                        "address_line1": "丹佛测试地址-纽埃时区",
                        "address_line2": "PoewH",
                        "address_line3": "PoewH",
                        "address_line4": "jmwJc",
                        "address_line5": "jmwJc",
                        "address_line6": "jmwJc",
                        "address_line7": "jmwJc",
                        "address_line8": "rafSu",
                        "address_line9": "McPRG",
                        "local_address_line1": "丹佛测试地址-纽埃时区",
                        "local_address_line2": "PoewH",
                        "local_address_line3": "PoewH",
                        "local_address_line4": "jmwJc",
                        "local_address_line5": "jmwJc",
                        "local_address_line6": "jmwJc",
                        "local_address_line7": "jmwJc",
                        "local_address_line8": "rafSu",
                        "local_address_line9": "McPRG",
                        "postal_code": "611530",
                        "address_type_list": [
                            {
                                "enum_name": "phone_type",
                                "display": [
                                    {
                                        "lang": "zh-CN",
                                        "value": "中文示例"
                                    }
                                ]
                            }
                        ],
                        "is_primary": true,
                        "is_public": true
                    }
                ]
            }
        ]
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
5031161204Request timeout接口超时，可尝试重试。如果无法解决可以联系飞书人事 技术支持
4291161604QPS over limit接口请求次数超过接口频率限制，可尝试降低请求频率

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

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