飞书开放平台 Server API 文档

主题

创建地点 ​

在系统中第一次创建地点数据

Tip: 非必填字段，不传时默认为空

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/corehr/v1/locations
HTTP MethodPOST
接口频率限制1000 次/分钟、50 次/秒
支持的应用类型custom
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可corehr:corehr 更新核心人事信息 corehr:locations:write 更新地点信息

请求头 ​

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

查询参数 ​

名称类型必填描述
client_tokenstring否操作的唯一标识，用于幂等的进行更新操作，格式为标准的 UUIDV4。此值为空表示将发起一次新的请求，此值非空表示幂等的进行更新操作。
示例值："fe599b60-450f-46ff-b2ef-9f6675625b97"

请求体 ​

名称类型必填描述
hiberarchy_commonhiberarchy_common是地点基本信息，该结构维护了地点的名称、编码、启用状态、上级地点等基础信息。
  └ parent_idstring否上级地点ID。ID获取方式： - 调用【创建地点】【批量分页查询地点】等接口可以返回地点ID
示例值："4719168654814483759"
  └ namei18n\[\]是地点名称 - 名称不能包含「/」「；」「;」「\」「'」字符。 - 地点中英文名称会有全局唯一校验
    └ langstring是语言 - 中文用zh-CN，英文用en-US。
示例值："zh-CN"
    └ valuestring是内容
示例值："刘梓新"
  └ activeboolean是启用状态，true为启用，false为停用
示例值：true
  └ codestring否地点编码 (不能与其他记录的编码重复) - 开启自动编码时，以自动生成的编码值为准，传入值不生效 - 未开启自动编码时，编码字段值以传入值为准
示例值："12456"
  └ descriptioni18n\[\]否描述
    └ langstring是语言 - 中文用zh-CN，英文用en-US。
示例值："zh-CN"
    └ valuestring是内容
示例值："刘梓新"
location_usage_listenum\[\]否地点用途(当地点用途是"工作地点"时，地址必填)
  └ enum_namestring是地点用途 ID，枚举值及详细信息可通过【批量查询地点用途】接口查询获得。 - 请求参数object_api_name=location；custom_api_name=location_usage
示例值："work_space"
addressaddress\[\]否地址
  └ country_region_idstring是国家 / 地区 ID
可通过【查询国家/地区信息】接口获取
示例值："6862995757234914824"
  └ region_idstring否主要行政区 ID
可通过【查询省份/行政区信息】接口获取
示例值："6863326815667095047"
  └ city_idstring否城市ID。ID获取 调用【查询城市信息】等接口可以返回城市ID
示例值："6863333254578046471"
  └ distinct_idstring否区县ID。ID获取 调用【查询区县信息】等接口可以返回区县ID
示例值："6863333516579440141"
  └ address_line1string否地址行 1 - 填写规则可见【地址填写指南】
示例值："丹佛测试地址-纽埃时区"
  └ address_line2string否地址行 2 - 填写规则可见【地址填写指南】
示例值："PoewH"
  └ address_line3string否地址行 3 - 填写规则可见【地址填写指南】
示例值："PoewH"
  └ address_line4string否地址行 4 - 填写规则可见【地址填写指南】
示例值："jmwJc"
  └ address_line5string否地址行 5 - 填写规则可见【地址填写指南】
示例值："jmwJc"
  └ address_line6string否地址行 6 - 填写规则可见【地址填写指南】
示例值："jmwJc"
  └ address_line7string否地址行 7 - 填写规则可见【地址填写指南】
示例值："jmwJc"
  └ address_line8string否地址行 8 - 填写规则可见【地址填写指南】
示例值："rafSu"
  └ address_line9string否地址行 9 - 填写规则可见【地址填写指南】
示例值："McPRG"
  └ local_address_line1string否地址行 1（非拉丁语系的本地文字） - 填写规则可见【地址填写指南】
示例值："丹佛测试地址-纽埃时区"
  └ local_address_line2string否地址行 2（非拉丁语系的本地文字） - 填写规则可见【地址填写指南】
示例值："PoewH"
  └ local_address_line3string否地址行 3（非拉丁语系的本地文字） - 填写规则可见【地址填写指南】
示例值："PoewH"
  └ local_address_line4string否地址行 4（非拉丁语系的本地文字） - 填写规则可见【地址填写指南】
示例值："jmwJc"
  └ local_address_line5string否地址行 5（非拉丁语系的本地文字） - 填写规则可见【地址填写指南】
示例值："jmwJc"
  └ local_address_line6string否地址行 6（非拉丁语系的本地文字） - 填写规则可见【地址填写指南】
示例值："jmwJc"
  └ local_address_line7string否地址行 7（非拉丁语系的本地文字） - 填写规则可见【地址填写指南】
示例值："jmwJc"
  └ local_address_line8string否地址行 8（非拉丁语系的本地文字） - 填写规则可见【地址填写指南】
示例值："rafSu"
  └ local_address_line9string否地址行 9（非拉丁语系的本地文字） - 填写规则可见【地址填写指南】
示例值："McPRG"
  └ postal_codestring否邮政编码
示例值："611530"
  └ address_type_listenum\[\]否地址类型，枚举值及详细信息可通过【获取字段详情】接口查询获得。 - 请求参数object_api_name=address；custom_api_name=address_type
    └ enum_namestring是枚举值
示例值："registered_address"
  └ is_primaryboolean否是否为主要地址
示例值：true
  └ is_publicboolean否公开地址
示例值：true
working_hours_type_idstring否工时制度 ID，枚举值及详细信息可通过【批量查询工时制度】接口查询获得
示例值："4690238309151997779"
effective_timestring是版本生效日期 - 填写格式：YYYY-MM-DD 00:00:00（系统会自动将时分秒改为00:00:00） - 系统默认为填写日期当天的 00:00:00 生效 - 该接口只支持到最小单位为日 - 日期范围要求:1900-01-01 00:00:00～9999-12-31 23:59:59 - 详情可以参考时间轴介绍
示例值："2020-05-01 00:00:00"
localeenum否区域设置ID ，枚举值及详细信息可通过【批量查询枚举信息】接口查询获得。 - 请求参数object_api_name=location；custom_api_name=locale
示例值：zh_cn
  └ enum_namestring是枚举值
示例值："zh_cn"
time_zone_idstring否时区
示例值："123456789"
display_language_idstring否默认显示语言
示例值："123456789"

请求体示例 ​

json
{
    "hiberarchy_common": {
        "parent_id": "4719168654814483759",
        "name": [
            {
                "lang": "zh-CN",
                "value": "刘梓新"
            }
        ],
        "active": true,
        "code": "12456",
        "description": [
            {
                "lang": "zh-CN",
                "value": "刘梓新"
            }
        ]
    },
    "location_usage_list": [
        {
            "enum_name": "work_space"
        }
    ],
    "address": [
        {
            "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": "registered_address"
                }
            ],
            "is_primary": true,
            "is_public": true
        }
    ],
    "working_hours_type_id": "4690238309151997779",
    "effective_time": "2020-05-01 00:00:00",
    "locale": {
        "enum_name": "zh_cn"
    },
    "time_zone_id": "123456789",
    "display_language_id": "123456789"
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ locationlocation4718803945687580505
    └ idstring实体在CoreHR内部的唯一键
    └ hiberarchy_commonhiberarchy_common地点基本信息，该结构维护了地点的名称、编码、启用状态、上级地点 等基础信息。
      └ parent_idstring上级地点，在创建场景下， 该字段必填，枚举值及详细信息可通过【查询地点列表】接口查询获得
      └ namei18n\[\]名称
        └ langstring语言 - 中文用zh-CN，英文用en-US。
        └ valuestring内容
      └ typeenum组织类型
        └ enum_namestring组织类型，默认值为 location， 枚举值及详细信息可通过【批量查询枚举类型】接口查询获得
        └ displayi18n\[\]枚举多语展示
          └ langstring语言 - 中文用zh-CN，英文用en-US。
          └ valuestring内容
      └ activeboolean启用
      └ effective_timestring生效时间 - 填写格式： YY-MM-DD 00:00:00 - 生效时间， 系统默认为填写日期当天的 00:00:00 生效
      └ expiration_timestring失效时间 - 填写格式： YYYY-MM-DD 00:00:00 - 本次编辑的记录版本失效的时间， 如果用户在本次操作的生效日期之后修改了地点信息，则系统会将下一次操作的日期作为当前记录的失效时间。 - 系统默认为填写日期当天的 00:00:00 失效
      └ codestring编码
      └ descriptioni18n\[\]描述
        └ langstring语言 - 中文用zh-CN，英文用en-US。
        └ valuestring内容
      └ custom_fieldsobject_field_data\[\]自定义字段
        └ field_namestring字段名
        └ valuestring字段值，是json转义后的字符串，根据元数据定义不同，字段格式不同。如：("\"123\"", "\"123.23\"", "\"true\"", [\"id1\",\"id2\"], \"2006-01-02 15:04:05\")
    └ location_usage_listenum\[\]地点用途
      └ enum_namestring枚举值，地点用途 ID，枚举值及详细信息可通过【批量查询地点用途】接口查询获得
      └ displayi18n\[\]枚举多语展示
        └ langstring语言 - 中文用zh-CN，英文用en-US。
        └ valuestring工作地点
    └ addressaddress\[\]地址
      └ full_address_local_scriptstring完整地址（本地文字）
      └ full_address_western_scriptstring完整地址（西方文字）
      └ idstring地址ID
      └ country_region_idstring国家 / 地区 ID
可通过【查询国家/地区信息】接口获取
      └ region_idstring主要行政区 ID
可通过【查询省份/行政区信息】接口获取
      └ city_idstring城市
      └ distinct_idstring区/县
      └ 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_fieldsobject_field_data\[\]自定义字段
        └ field_namestring字段名
        └ 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 生效
    └ expiration_timestring版本失效时间 - 填写格式： YYYY-MM-DD 00:00:00 - 本次编辑的记录版本失效的时间， 如果用户在本次操作的生效日期之后修改了地点信息，则系统会将下一次操作的日期作为当前记录的失效时间。 - 系统默认为填写日期当天的 00:00:00 失效
    └ custom_fieldsobject_field_data\[\]自定义字段
      └ field_namestring字段名
      └ 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": {
        "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": "刘梓新"
                    }
                ],
                "custom_fields": [
                    {
                        "field_name": "name",
                        "value": "\"Sandy\""
                    }
                ]
            },
            "location_usage_list": [
                {
                    "enum_name": "phone_type",
                    "display": [
                        {
                            "lang": "zh-CN",
                            "value": "工作地点"
                        }
                    ]
                }
            ],
            "address": [
                {
                    "full_address_local_script": "中国北京北京",
                    "full_address_western_script": "Beijing, Beijing, China,",
                    "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": "onboarding_address",
                            "display": [
                                {
                                    "lang": "zh-CN",
                                    "value": " 入职地址"
                                }
                            ]
                        }
                    ],
                    "is_primary": true,
                    "is_public": true,
                    "custom_fields": [
                        {
                            "field_name": "name",
                            "value": "\"Sandy\""
                        }
                    ]
                }
            ],
            "working_hours_type_id": "4690238309151997779",
            "effective_time": "2020-05-01 00:00:00",
            "expiration_time": "2020-05-02 00:00:00",
            "custom_fields": [
                {
                    "field_name": "name",
                    "value": "\"Sandy\""
                }
            ],
            "locale": {
                "enum_name": "zh_cn",
                "display": [
                    {
                        "lang": "zh-CN",
                        "value": "刘梓新"
                    }
                ]
            },
            "time_zone_id": "123456789",
            "display_language_id": "123456789"
        }
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
4001160004client_token repeat.重复请求，请确认是否已处理完成
4001160251superior location is required上级地点为必填，请检查上级地点是否为空
4001160252the number of characters in the text field exceeds the limit文本类字段的长度超过限制，请减少字符数
4001160253the name can't contain "/", "；", or ";"名称中包含「/」、「；」、「;」、「\」、「'」请删除相关特殊字符
4001160263code already exists请检查编码是否与其他记录重复
4001160264this operation will make the relationship between the superior and the subordinate into a ring地点上下级关系成环，请检查上级地点是否正确
4001160269effective date can't exceed 9999生效日期不允许大于 9999 年，请检查生效日期是否正确
4001160502The name already exists in same superior location. Please enter a different one.上级地点下已存在相同名称，请使用其他名称
4001160311Unable to create a sub-department as location will be deactivated该地点将被停用，无法为其新建下级
4001160313Unable to select "Geographical division" and other usages at the same time不能同时选择「地域划分」和其他用途
4001160314Unable to select "Work location" and "Work space" at the same time不能同时选择「工作地点」和「办公楼宇」
4001160315select a primary address请选择主要地址
4001160316detailed address isn't required无需填写详细地址
4001160317You can only select "work location" or "office location"仅可选择「工作地点」或「办公地点」
4001160321enter an array for field请检查填写的信息， 需输入数组类型
4001160327metadata of field doesn't exist该字段不是地点对象字段，请检查字段 APIName 是否正确
4001160328Enter an integer for field请填写 Integer 整型数据
4001160329field exceeds the maximum value请检查数字大小是否在范围内
4001160330field exceeds the minimum value请检查数字大小是否在范围内请检查数字格式是否正确
4001160331Enter an integer or decimal for field请检查数字格式是否正确
4001160332enter a boolean value for field请检查布尔类型字段是否正确
4001160333Enter an i18n object for field请检查多语字段传参是否正确
4001160334Enter an enumeration value for field请检查传参是否正确
4001160335Enter an array for field请检查传参是否正确
4001160336org doesn't exist请检查地点是否存在
4001160337deprecated已废弃
4001160338field must be a string请检查传参是否正确
4001160339field must be a string请检查传参是否正确
4001160340field must be in the yyyy-MM-dd HH:mm:ss format请检查时间格式是否正确
4001160341deprecated已废弃
4001160343Duplicate code请检查编码是否与其他记录重复
4001160256depercated已废弃
4001160347org will be deactivated请检查停启用状态
4001160349org deactivated on date请检查停启用状态
4001160352The option has been deactivated请检查枚举类字段的选项是否已停用
4001160353effective date can't be earlier than 1900生效日期不能早于 1900 年
4001160360unable to remove "work location"不能移除「工作地点」
4001160354service rate limiting protection, please try again later请稍后再试

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

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