# 创建部门
支持在单个接口中进行部门信息添加，包括部门基本信息、部门负责人、部门自定义字段信息等
**注意事项**：此接口字段是否必填以【飞书人事-组织配置】为准。建议参照【飞书人事-组织管理-部门-新建】页面来传参
## 请求
基本 |
---|---
HTTP URL | https://open.feishu.cn/open-apis/corehr/v1/departments
HTTP Method | POST
接口频率限制 | [1000 次/分钟、50 次/秒](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
支持的应用类型 | Custom App
权限要求
**调用该 API 所需的权限。开启其中任意一项权限即可调用**
开启任一权限即可 | 更新核心人事信息(corehr:corehr)
读写部门信息(corehr:department:write)
字段权限要求 | **注意事项**：该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请
获取用户 user ID(contact:user.employee_id:readonly)
### 请求头
名称 | 类型 | 必填 | 描述
---|---|---|---
Authorization | string | 是 | `tenant_access_token`
**值格式**："Bearer `access_token`"
**示例值**："Bearer t-7f1bcd13fc57d46bac21793a18e560"
[了解更多：如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use)
Content-Type | string | 是 | **固定值**："application/json; charset=utf-8"
### 查询参数
名称 | 类型 | 必填 | 描述
---|---|---|---
client_token | string | 否 | 根据client_token是否一致来判断是否为同一请求
**示例值**：12454646
user_id_type | string | 否 | 用户 ID 类型
**示例值**：people_corehr_id
**可选值有**：
- open_id：标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。[了解更多：如何获取 Open ID](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-openid)
- union_id：标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。[了解更多：如何获取 Union ID？](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-union-id)
- user_id：标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。[了解更多：如何获取 User ID？](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-user-id)
- people_corehr_id：以飞书人事的 ID 来识别用户
**默认值**：`people_corehr_id`
**当值为 `user_id`，字段权限要求**：
获取用户 user ID(contact:user.employee_id:readonly)
department_id_type | string | 否 | 此次调用中使用的部门 ID 类型
**示例值**：people_corehr_department_id
**可选值有**：
- open_department_id：【飞书】用来在具体某个应用中标识一个部门，同一个department_id 在不同应用中的 open_department_id 相同。
- department_id：【飞书】用来标识租户内一个唯一的部门。
- people_corehr_department_id：【飞书人事】用来标识「飞书人事」中的部门。
**默认值**：`people_corehr_department_id`
### 请求体
名称 | 类型 | 必填 | 描述
---|---|---|---
sub_type | enum | 否 | 部门类型，通过[请求接口](https://open.larkoffice.com/document/server-docs/corehr-v1/basic-infomation/custom_field/get_by_param)查询获取。请求参数：object_api_name=department；custom_api_name=subtype。
enum_name | string | 是 | 枚举值
**示例值**："type_1"
manager | string | 否 | 部门负责人
- 详细信息可通过[【搜索员工信息】](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/corehr-v2/employee/search) 或 [【批量查询员工】](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/corehr-v2/employee/batch_get) 接口获取
**示例值**："6893013238632416776"
is_confidential | boolean | 否 | 是否保密（该功能暂不支持，可忽略）
**示例值**：true
hiberarchy_common | hiberarchy_common | 是 | 组织实体公共字段，包括名称、描述、上级、启停用状态、生效日期、编码等基础信息
parent_id | string | 否 | 上级组织 ID，该字段为通用字段，若为部门维度则为必填。详细信息可通过[【查询单个部门】](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/department/get)接口获得
**示例值**："4719168654814483759"
name | i18n\[\] | 是 | 名称
lang | string | 是 | 名称信息的语言，支持中文和英文。中文用zh-CN；英文用en-US。
**示例值**："zh-CN"
value | string | 是 | 名称信息的内容，支持中文和英文。填写规范
- 名称不能包含「/」「；」「;」「\」「'」字符。
- 同一个上级部门的启用的部门名称不允许重复
**示例值**："研发部"
active | boolean | 是 | 是否启用该部门
**示例值**：true
code | string | 否 | 部门编码 (不能与其他记录的编码重复)
它的生效规则和 is_prefer_manual_encoding (是否优先使用手动编码)相关：
- 当系统开启自动编码时：
若 is_prefer_manual_encoding=true：传入的 code 会生效，不传则自动生成编码。
若 is_prefer_manual_encoding=false：传的 code 会被忽略，以系统自动生成的编码为准。
- 当系统未开启自动编码时：无论 is_prefer_manual_encoding取值如何，均以传入的 code 为准。
**示例值**："12456"
description | i18n\[\] | 否 | 描述
lang | string | 是 | 描述信息的语言，支持中文和英文。中文用zh-CN；英文用en-US。
**示例值**："zh-CN"
value | string | 是 | 描述信息的内容
**示例值**："张三"
effective_time | string | 是 | 版本生效日期
- 填写格式：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"
custom_fields | object_field_data\[\] | 否 | 自定义字段类型，详细见[获取自定义字段列表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/custom_field/query)
field_name | string | 是 | 自定义字段 API Name，即自定义字段的唯一标识
**示例值**："name"
value | string | 是 | 字段值，为 JSON 转义后的字符串。
**注意：具体传值方式参见**[获取自定义字段的元数据](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/custom-fields-guide)
**示例值**："\"Sandy\""
cost_center_id | string | 否 | 成本中心id
详细信息可通过[【搜索成本中心信息】](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/corehr-v2/cost_center/search)接口查询获得
**示例值**："7142384817131652652"
staffing_model | enum | 否 | 岗职管理模式
- 详细枚举类型请查看[枚举场景](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/feishu-people-enum-constant)中关于staffing_model定义
enum_name | string | 是 | 枚举值
**示例值**："position"
is_prefer_manual_encoding | boolean | 否 | 是否优先使用手动编码
- 设为 true：优先使用传入的 code。即使系统开启了自动编码，只要传了 code，以传入值为准；
未传code时，会回退到自动生成编码。
- 设为 false：遵循系统默认策略。此时若系统开启了自动编码，传入的 code 不会生效，以系统自动生成的编码为准
**示例值**：false
### 请求体示例
```json
{
"sub_type": {
"enum_name": "type_1"
},
"manager": "6893013238632416776",
"is_confidential": true,
"hiberarchy_common": {
"parent_id": "4719168654814483759",
"name": [
{
"lang": "zh-CN",
"value": "研发部"
}
],
"active": true,
"code": "12456",
"description": [
{
"lang": "zh-CN",
"value": "张三"
}
]
},
"effective_time": "2020-05-01 00:00:00",
"custom_fields": [
{
"field_name": "name",
"value": "\"Sandy\""
}
],
"cost_center_id": "7142384817131652652",
"staffing_model": {
"enum_name": "position"
},
"is_prefer_manual_encoding": false
}
```
## 响应
### 响应体
名称 | 类型 | 描述
---|---|---
code | int | 错误码，非 0 表示失败
msg | string | 错误描述
data | \- | \-
department | department_create | 创建成功的部门信息
id | string | 部门ID(返回的是people_corehr_department_id)
sub_type | enum | 部门类型，通过[请求接口](https://open.larkoffice.com/document/server-docs/corehr-v1/basic-infomation/custom_field/get_by_param)查询获取。请求参数：object_api_name=department；custom_api_name=subtype。
enum_name | string | 枚举值
display | i18n\[\] | 枚举多语展示
lang | string | 枚举值信息的语言，支持中文和英文。中文用zh-CN；英文用en-US。
value | string | 枚举值信息的内容
manager | string | 部门负责人，填写员工的雇佣ID
详细信息可通过[【搜索员工信息】](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/corehr-v2/employee/search)接口获取
is_confidential | boolean | 是否保密（该功能暂不支持，可忽略）
hiberarchy_common | hiberarchy_common | 组织实体公共字段，包括名称、描述、上级、启停用状态、生效日期、编码等基础信息
parent_id | string | 上级组织 ID，详细信息可通过[【查询单个部门】](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/department/get)接口获得
name | i18n\[\] | 名称
lang | string | 名称信息的语言，支持中文和英文。中文用zh-CN；英文用en-US。
value | string | 名称信息的内容，支持中文和英文。填写规范
- 名称不能包含「/」「；」「;」「\」「'」字符。
- 同一个上级部门的启用的部门名称不允许重复
type | enum | 组织类型，枚举值可通过文档[【飞书人事枚举常量】](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/feishu-people-enum-constant)组织类型（organization_type）枚举定义部分获得
enum_name | string | 枚举值
display | i18n\[\] | 枚举多语展示
lang | string | 枚举值信息的语言，支持中文和英文。中文用zh-CN；英文用en-US。
value | string | 枚举值信息的内容
active | boolean | 是否启用
effective_time | string | 版本生效时间
- 返回格式：YYYY-MM-DD 00:00:00（最小单位到日）
- 日期范围:1900-01-01 00:00:00～9999-12-31 23:59:59
- 和data.effective_time值一致
expiration_time | string | 版本失效时间
- 返回格式：YYYY-MM-DD 00:00:00（最小单位到日）
- 日期范围:1900-01-01 00:00:00～9999-12-31 23:59:59
- 和data. expiration_time值一致
code | string | 编码
description | i18n\[\] | 描述
lang | string | 名称信息的语言，支持中文和英文。中文用zh-CN；英文用en-US。
value | string | 名称信息的内容
tree_order | string | 树形排序，代表同层级的部门排序序号
- 数据类型为字符串，实际按数值大小排序，数值越小，同层级部门展示越靠前；仅对同一父部门下的直接子部门生效
- 数值生成规则：
- 编号长度由同层级部门数量动态决定：同层级部门≤10 个为 6 位编号，10~20 个为 7 位编号，超过 100 个统一为 16 位编号，以此类推
- 新建部门时系统自动赋值：同层级下一个新部门编号，会在上一个部门编号基础上按固定数值自动累加；例如 6 位编号每次固定加 1000，7 位编号每次固定加 10000
- 重排触发：当同层级部门数量超出当前编号长度可容纳范围，或多次拖拽排序无法正常插入位置时，会触发同层级编号全局重新编排；所有部门编号会按新的长度和累加规则重新生成，数值可能出现明显变大
- 当同一父部门下的子部门数量超过 1000 个时，系统在维护排序编号时可能出现异常问题。
- 更新时机：
- 创建部门场景tree_order不会实时生成，10分钟内更新完毕
- 在页面拖动部门排序时tree_order可以实时生成
- 变更部门上级时，会清空tree_order，并触发重算list_order和tree_order，10分钟内更新完毕（list_order由部门上级路径的所有tree_order用“-”拼接生成）
list_order | string | ListOrder
列表排序，代表所有部门的混排序号，为该部门上级路径上所有tree_order用“-”拼接。
- 该字段在新建/更新场景非立即更新，10分钟后会延迟更新
- 由于list_order变更会导致[部门变更接口](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/department/events/updated)产生大量事件，因此事件接口不会针对该字段同步变更事件，如果有需求订阅请联系Oncall单独开启。
custom_fields | object_field_data\[\] | 自定义字段类型，详细见[获取自定义字段列表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/custom_field/query)
field_name | string | 自定义字段 API Name，即自定义字段的唯一标识
value | string | 字段值，是json转义后的字符串，根据元数据定义不同，字段格式不同。如：```("\"123\"", "\"123.23\"", "\"true\"", [\"id1\",\"id2\"], \"2006-01-02 15:04:05\")```
effective_time | string | 版本生效时间
- 返回格式：YYYY-MM-DD 00:00:00（最小单位到日）
- 日期范围:1900-01-01 00:00:00～9999-12-31 23:59:59
- 和data.hiberarchy_common.effective_time值一致
expiration_time | string | 版本失效时间
- 返回格式：YYYY-MM-DD 00:00:00（最小单位到日）
- 日期范围:1900-01-01 00:00:00～9999-12-31 23:59:59
- 和data.hiberarchy_common.expiration_time值一致
custom_fields | object_field_data\[\] | 自定义字段
field_name | string | 字段名
value | string | 字段值，是json转义后的字符串，根据元数据定义不同，字段格式不同(如123, 123.23, "true", [\"id1\",\"id2\"], "2006-01-02 15:04:05")
cost_center_id | string | 成本中心id，详细信息可通过[【搜索成本中心信息】](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/corehr-v2/cost_center/search)接口查询获得
staffing_model | enum | 岗职管理模式
- 详细枚举类型请查看[枚举场景](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/feishu-people-enum-constant)中关于staffing_model定义
enum_name | string | 枚举值
display | i18n\[\] | 枚举多语展示
lang | string | 语言，支持中文和英文。中文用zh-CN；英文用en-US。
value | string | 内容
### 响应体示例
```json
{
"code": 0,
"msg": "success",
"data": {
"department": {
"id": "4719456877659520852",
"sub_type": {
"enum_name": "type_1",
"display": [
{
"lang": "zh-CN",
"value": "张三"
}
]
},
"manager": "6893013238632416776",
"is_confidential": true,
"hiberarchy_common": {
"parent_id": "4719168654814483759",
"name": [
{
"lang": "zh-CN",
"value": "张三"
}
],
"type": {
"enum_name": "type_1",
"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": "001000",
"list_order": "001000-001000",
"custom_fields": [
{
"field_name": "name",
"value": "\"Sandy\""
}
]
},
"effective_time": "2020-05-01 00:00:00",
"expiration_time": "2020-05-02 00:00:00",
"custom_fields": [
{
"field_name": "name",
"value": "\"Sandy\""
}
],
"cost_center_id": "7142384817131652652",
"staffing_model": {
"enum_name": "position",
"display": [
{
"lang": "zh-CN",
"value": "刘梓新"
}
]
}
}
}
}
```
### 错误码
HTTP状态码 | 错误码 | 描述 | 排查建议
---|---|---|---
400 | 1160004 | request ID repeat | 重复请求，请确认是否已处理完成
400 | 1160104 | custom field format error | 请检查自定义字段的格式是否正确
400 | 1160106 | date format should be yyyy-mm-dd hh:mm:ss | 请检查时间类型字段的格式是否正确
400 | 1160251 | superior department is required | 上级部门为必填，请检查上级部门是否为空
400 | 1160252 | the number of characters in the text field exceeds the limit | 文本类字段的长度超过限制，请减少字符数
400 | 1160253 | the name can't contain "/","；",or ";" | 部门名称中包含「/」、「；」、「;」、「\」、「'」请删除相关特殊字符
400 | 1160254 | name already exists | 请检查名称是否与其他记录重复
400 | 1160258 | the individual hasn't been onboard on effective date | 请检查人员在生效日期下是否未入职
400 | 1160259 | the individual offboarded on effective date | 请检查人员在生效日期下是是否已离职
400 | 1160263 | code already exists | 请检查编码是否与其他记录重复
400 | 1160264 | this operation will make the relationship between the superior and the subordinate into a ring | 部门上下级关系成环，请检查上级部门是否正确
400 | 1160269 | effective date can't exceed 9999 | 生效日期不允许大于 9999 年，请检查生效日期是否正确
400 | 1160321 | the name already exists | 名称已存在，请使用其他名称
400 | 1160322 | department still have active subordinates on or after the effective date | 已废弃
400 | 1160327 | the field doesn't exist | 请检查字段是否正确
400 | 1160337 | effective date is required | 请检查生效日期是否为空
400 | 1160340 | field must be in the yyyy-MM-dd HH:mm:ss format | 已废弃
400 | 1160341 | doesn't exist | 已废弃
400 | 1160343 | Duplicate code | 已废弃
400 | 1160347 | superior department will be deactivated on or after the effective date | 上级部门在生效日期或之后将停用，请检查上级部门是否准确
400 | 1160349 | superior department will be deactivated on or after the effective date | 上级部门在生效日期或之后将停用，请检查上级部门是否准确
400 | 1160351 | superior department hasn't taken effect on effective date | 已废弃
400 | 1160352 | the option has been deactivated | 请检查枚举类字段的选项是否已停用
400 | 1160353 | the effective date can't be earlier than 1900 | 生效日期不能早于 1900 年
400 | 1160354 | 必须是 string | 已废弃
400 | 1160402 | lookup object value deactivated on the effective date | 已废弃