飞书开放平台 Server API 文档

主题

通过地点 ID 批量获取地点信息 ​

该接口用于根据地点 ID批量查询地点信息，信息包含地点名称、描述、地点用途、工时制度、区域设置、时区以及关联的地址信息等。

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

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/corehr/v2/locations/batch_get
HTTP MethodPOST
接口频率限制1000 次/分钟、50 次/秒
支持的应用类型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获取方式： - 调用【创建地点】【批量分页查询地点】等接口可以返回地点ID
示例值：["1215"]
数据校验规则：
- 长度范围：1 ～ 100

请求体示例 ​

json
{
    "location_ids": [
        "1215"
    ]
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ itemslocation\[\]查询的地点信息
    └ location_idstring地点 ID，地点维护管理员在 飞书人事系统，组织管理模块维护的地点记录 ID。
    └ hiberarchy_commonhiberarchy_common地点基本信息，该结构维护了地点的名称、编码、启用状态、上级地点 等基础信息。
      └ parent_idstring上级地点 - 在创建场景下， 该字段必填，枚举值及详细信息可通过【查询地点列表】接口查询获得 - 若查询的是一级地点，则该字段不展示
      └ namei18n\[\]地点名称
        └ langstring语言 - 中文用zh-CN，英文用en-US。
        └ valuestring文本内容
      └ typeenum组织类型
        └ enum_namestring地点类型 ，枚举值及详细信息可通过【批量查询枚举信息】接口查询获得。 - 请求参数object_api_name=organization；custom_api_name=org_type - 该接口返回固定值location
        └ displayi18n\[\]枚举多语展示
          └ langstring语言 - 中文用zh-CN，英文用en-US。
          └ valuestring文本内容
      └ activeboolean启用状态，true为启用，fasle为停用
      └ effective_timestring当前版本生效日期 - 返回格式：YYYY-MM-DD 00:00:00（最小单位到日） - 日期范围:1900-01-01 00:00:00～9999-12-31 00:00:00 - 详情可以参考时间轴介绍 - 该字段和data.effective_time值一致
      └ expiration_timestring当前版本失效日期 - 返回格式：YYYY-MM-DD 00:00:00（最小单位到日） - 日期范围:1900-01-01 00:00:00～9999-12-31 00:00:00 - 系统默认为失效日期当天的 00:00:00 失效 - 详情可以参考时间轴介绍 - 该字段和data.expiration_time值一致
      └ codestring地点编码
      └ descriptioni18n\[\]描述
        └ langstring语言 - 中文用zh-CN，英文用en-US。
        └ valuestring文本内容
      └ tree_orderstring树形排序(可忽略)，代表同层级的部门排序序号（该功能暂不支持，可忽略）
      └ list_orderstring列表排序(可忽略)，代表所有部门的混排序号（该功能暂不支持，可忽略）
      └ custom_fieldsobject_field_data\[\]自定义字段（该功能暂不支持，可忽略）
        └ field_namestring自定义字段 API Name，即自定义字段的唯一标识
        └ valuestring字段值，是json转义后的字符串，根据元数据定义不同，字段格式不同。如：("\"123\"", "\"123.23\"", "\"true\"", [\"id1\",\"id2\"], \"2006-01-02 15:04:05\")
    └ location_usage_listenum\[\]地点用途，枚举值及详细信息可通过【批量查询地点用途】接口查询获得。 - 请求参数object_api_name=location；custom_api_name=location_usage
      └ enum_namestring枚举值
      └ displayi18n\[\]枚举多语展示
        └ langstring语言 - 中文用zh-CN，英文用en-US。
        └ valuestring文本内容
    └ addressaddress\[\]地址
      └ full_address_local_scriptstring完整地址（本地文字）
      └ full_address_western_scriptstring完整地址（西方文字）
      └ address_idstring地址 ID
      └ country_region_idstring国家 / 地区 ID
可通过【查询国家/地区信息】接口获取
      └ region_idstring主要行政区 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公开地址
      └ custom_fieldscustom_field_data\[\]自定义字段（该功能暂不支持，可忽略）
        └ custom_api_namestring自定义字段 apiname，即自定义字段的唯一标识
        └ namecustom_name自定义字段名称
          └ zh_cnstring中文
          └ en_usstring英文
        └ typeint自定义字段类型，详细见获取自定义字段列表
        └ valuestring字段值，是json转义后的字符串，根据元数据定义不同，字段格式不同。如：("\"123\"", "\"123.23\"", "\"true\"", [\"id1\",\"id2\"], \"2006-01-02 15:04:05\")
    └ working_hours_type_idstring工时制度 ID，枚举值及详细信息可通过【批量查询工时制度】接口查询获得
    └ effective_timestring版本生效时间 - 填写格式：YY-MM-DD 00:00:00 - 生效时间， 系统默认为填写日期当天的 00:00:00 生效 - 详情可以参考时间轴介绍 - 该字段和data.hiberarchy_common.effective_time值一致
    └ expiration_timestring版本失效时间 - 填写格式： YYYY-MM-DD 00:00:00 - 本次编辑的记录版本失效的时间， 如果用户在本次操作的生效日期之后修改了地点信息，则系统会将下一次操作的日期作为当前记录的失效时间。 - 系统默认为填写日期当天的 00:00:00 失效 - 详情可以参考时间轴介绍 - 该字段和data.hiberarchy_common.expiration_time值一致
    └ custom_fieldscustom_field_data\[\]自定义字段（该功能暂不支持，可忽略）
      └ custom_api_namestring自定义字段 apiname，即自定义字段的唯一标识
      └ namecustom_name自定义字段名称
        └ zh_cnstring中文
        └ en_usstring英文
      └ typeint自定义字段类型，详细见获取自定义字段列表
      └ valuestring字段值，是json转义后的字符串，根据元数据定义不同，字段格式不同。如：("\"123\"", "\"123.23\"", "\"true\"", [\"id1\",\"id2\"], \"2006-01-02 15:04:05\")
    └ localeenum区域设置ID ，枚举值及详细信息可通过【批量查询枚举信息】接口查询获得
      └ enum_namestring枚举值
      └ displayi18n\[\]枚举多语展示
        └ langstring语言 - 中文用zh-CN，英文用en-US。
        └ valuestring文本内容
    └ time_zone_idstring时区
    └ display_language_idstring默认显示语言

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "items": [
            {
                "location_id": "4718803945687580505",
                "hiberarchy_common": {
                    "parent_id": "4719168654814483759",
                    "name": [
                        {
                            "lang": "zh-CN",
                            "value": "中文示例"
                        }
                    ],
                    "type": {
                        "enum_name": "location",
                        "display": [
                            {
                                "lang": "zh-CN",
                                "value": " 地点"
                            }
                        ]
                    },
                    "active": true,
                    "effective_time": "2020-05-01 00:00:00",
                    "expiration_time": "2020-05-02 00:00:00",
                    "code": "12456",
                    "description": [
                        {
                            "lang": "zh-CN",
                            "value": "中文示例"
                        }
                    ],
                    "tree_order": "123",
                    "list_order": "123",
                    "custom_fields": [
                        {
                            "field_name": "name",
                            "value": "\"Sandy\""
                        }
                    ]
                },
                "location_usage_list": [
                    {
                        "enum_name": "work_location",
                        "display": [
                            {
                                "lang": "zh-CN",
                                "value": "中文示例"
                            }
                        ]
                    }
                ],
                "address": [
                    {
                        "full_address_local_script": "中国北京北京",
                        "full_address_western_script": "Beijing, Beijing, China,",
                        "address_id": "6989822217869624863",
                        "country_region_id": "6862995757234914824",
                        "region_id": "6863326815667095047",
                        "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": "home_address",
                                "display": [
                                    {
                                        "lang": "zh-CN",
                                        "value": "中文示例"
                                    }
                                ]
                            }
                        ],
                        "is_primary": true,
                        "is_public": true,
                        "custom_fields": [
                            {
                                "custom_api_name": " custom_field_1__c",
                                "name": {
                                    "zh_cn": "自定义姓名",
                                    "en_us": "Custom Name"
                                },
                                "type": 1,
                                "value": "\"231\""
                            }
                        ]
                    }
                ],
                "working_hours_type_id": "4690238309151997779",
                "effective_time": "2020-05-01 00:00:00",
                "expiration_time": "2020-05-02 00:00:00",
                "custom_fields": [
                    {
                        "custom_api_name": "name",
                        "name": {
                            "zh_cn": "自定义姓名",
                            "en_us": "Custom Name"
                        },
                        "type": 1,
                        "value": "\"231\""
                    }
                ],
                "locale": {
                    "enum_name": "zh_cn",
                    "display": [
                        {
                            "lang": "zh-CN",
                            "value": "中文示例"
                        }
                    ]
                },
                "time_zone_id": "123456789",
                "display_language_id": "123456789"
            }
        ]
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
4001160001参数错误校验传参是否正确

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

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