飞书开放平台 Server API 文档

主题

创建部门 ​

支持在单个接口中进行部门信息添加，包括部门基本信息、部门负责人、部门自定义字段信息等

Tip: 此接口字段是否必填以【飞书人事-组织配置】为准。建议参照【飞书人事-组织管理-部门-新建】页面来传参

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/corehr/v1/departments
HTTP MethodPOST
接口频率限制1000 次/分钟、50 次/秒
支持的应用类型custom
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可corehr:corehr 更新核心人事信息 corehr:department:write 读写部门信息
字段权限要求> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 contact:user.employee_id:readonly 获取用户 user ID

请求头 ​

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

查询参数 ​

名称类型必填描述
client_tokenstring否根据client_token是否一致来判断是否为同一请求
示例值：12454646
user_id_typestring否用户 ID 类型
示例值：people_corehr_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 来识别用户
默认值：people_corehr_id
当值为 user_id，字段权限要求： contact:user.employee_id:readonly 获取用户 user ID
department_id_typestring否此次调用中使用的部门 ID 类型
示例值：people_corehr_department_id
可选值有：
- open_department_id: 【飞书】用来在具体某个应用中标识一个部门，同一个department_id 在不同应用中的 open_department_id 相同。 - department_id: 【飞书】用来标识租户内一个唯一的部门。 - people_corehr_department_id: 【飞书人事】用来标识「飞书人事」中的部门。
默认值：people_corehr_department_id

请求体 ​

名称类型必填描述
sub_typeenum否部门类型，通过请求接口查询获取。请求参数：object_api_name=department；custom_api_name=subtype。
  └ enum_namestring是枚举值
示例值："type_1"
managerstring否部门负责人 - 详细信息可通过【搜索员工信息】 或 【批量查询员工】 接口获取
示例值："6893013238632416776"
is_confidentialboolean否是否保密（该功能暂不支持，可忽略）
示例值：true
hiberarchy_commonhiberarchy_common是组织实体公共字段，包括名称、描述、上级、启停用状态、生效日期、编码等基础信息
  └ parent_idstring否上级组织 ID，该字段为通用字段，若为部门维度则为必填。详细信息可通过【查询单个部门】接口获得
示例值："4719168654814483759"
  └ namei18n\[\]是名称
    └ langstring是名称信息的语言，支持中文和英文。中文用zh-CN；英文用en-US。
示例值："zh-CN"
    └ valuestring是名称信息的内容，支持中文和英文。填写规范 - 名称不能包含「/」「；」「;」「\」「'」字符。 - 同一个上级部门的启用的部门名称不允许重复
示例值："研发部"
  └ activeboolean是是否启用该部门
示例值：true
  └ codestring否部门编码 (不能与其他记录的编码重复)
它的生效规则和 is_prefer_manual_encoding (是否优先使用手动编码)相关： - 当系统开启自动编码时： 若 is_prefer_manual_encoding=true：传入的 code 会生效，不传则自动生成编码。 若 is_prefer_manual_encoding=false：传的 code 会被忽略，以系统自动生成的编码为准。 - 当系统未开启自动编码时：无论 is_prefer_manual_encoding取值如何，均以传入的 code 为准。
示例值："12456"
  └ descriptioni18n\[\]否描述
    └ langstring是描述信息的语言，支持中文和英文。中文用zh-CN；英文用en-US。
示例值："zh-CN"
    └ valuestring是描述信息的内容
示例值："张三"
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"
custom_fieldsobject_field_data\[\]否自定义字段类型，详细见获取自定义字段列表
  └ field_namestring是自定义字段 API Name，即自定义字段的唯一标识
示例值："name"
  └ valuestring是字段值，为 JSON 转义后的字符串。
注意：具体传值方式参见获取自定义字段的元数据
示例值：""Sandy""
cost_center_idstring否成本中心id 详细信息可通过【搜索成本中心信息】接口查询获得
示例值："7142384817131652652"
staffing_modelenum否岗职管理模式 - 详细枚举类型请查看枚举场景中关于staffing_model定义
  └ enum_namestring是枚举值
示例值："position"
is_prefer_manual_encodingboolean否是否优先使用手动编码
- 设为 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
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ departmentdepartment_create创建成功的部门信息
    └ idstring部门ID(返回的是people_corehr_department_id)
    └ sub_typeenum部门类型，通过请求接口查询获取。请求参数：object_api_name=department；custom_api_name=subtype。
      └ enum_namestring枚举值
      └ displayi18n\[\]枚举多语展示
        └ langstring枚举值信息的语言，支持中文和英文。中文用zh-CN；英文用en-US。
        └ valuestring枚举值信息的内容
    └ managerstring部门负责人，填写员工的雇佣ID 详细信息可通过【搜索员工信息】接口获取
    └ is_confidentialboolean是否保密（该功能暂不支持，可忽略）
    └ hiberarchy_commonhiberarchy_common组织实体公共字段，包括名称、描述、上级、启停用状态、生效日期、编码等基础信息
      └ parent_idstring上级组织 ID，详细信息可通过【查询单个部门】接口获得
      └ namei18n\[\]名称
        └ langstring名称信息的语言，支持中文和英文。中文用zh-CN；英文用en-US。
        └ valuestring名称信息的内容，支持中文和英文。填写规范 - 名称不能包含「/」「；」「;」「\」「'」字符。 - 同一个上级部门的启用的部门名称不允许重复
      └ typeenum组织类型，枚举值可通过文档【飞书人事枚举常量】组织类型（organization_type）枚举定义部分获得
        └ enum_namestring枚举值
        └ displayi18n\[\]枚举多语展示
          └ langstring枚举值信息的语言，支持中文和英文。中文用zh-CN；英文用en-US。
          └ valuestring枚举值信息的内容
      └ activeboolean是否启用
      └ effective_timestring版本生效时间 - 返回格式：YYYY-MM-DD 00:00:00（最小单位到日） - 日期范围:1900-01-01 00:00:00～9999-12-31 23:59:59 - 和data.effective_time值一致
      └ expiration_timestring版本失效时间 - 返回格式：YYYY-MM-DD 00:00:00（最小单位到日） - 日期范围:1900-01-01 00:00:00～9999-12-31 23:59:59 - 和data. expiration_time值一致
      └ codestring编码
      └ descriptioni18n\[\]描述
        └ langstring名称信息的语言，支持中文和英文。中文用zh-CN；英文用en-US。
        └ valuestring名称信息的内容
      └ tree_orderstring树形排序，代表同层级的部门排序序号 - 数据类型为字符串，实际按数值大小排序，数值越小，同层级部门展示越靠前；仅对同一父部门下的直接子部门生效 - 数值生成规则： - 编号长度由同层级部门数量动态决定：同层级部门≤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_orderstringListOrder 列表排序，代表所有部门的混排序号，为该部门上级路径上所有tree_order用“-”拼接。 - 该字段在新建/更新场景非立即更新，10分钟后会延迟更新 - 由于list_order变更会导致部门变更接口产生大量事件，因此事件接口不会针对该字段同步变更事件，如果有需求订阅请联系Oncall单独开启。
      └ custom_fieldsobject_field_data\[\]自定义字段类型，详细见获取自定义字段列表
        └ field_namestring自定义字段 API Name，即自定义字段的唯一标识
        └ valuestring字段值，是json转义后的字符串，根据元数据定义不同，字段格式不同。如：("\"123\"", "\"123.23\"", "\"true\"", [\"id1\",\"id2\"], \"2006-01-02 15:04:05\")
    └ effective_timestring版本生效时间 - 返回格式：YYYY-MM-DD 00:00:00（最小单位到日） - 日期范围:1900-01-01 00:00:00～9999-12-31 23:59:59 - 和data.hiberarchy_common.effective_time值一致
    └ expiration_timestring版本失效时间 - 返回格式：YYYY-MM-DD 00:00:00（最小单位到日） - 日期范围:1900-01-01 00:00:00～9999-12-31 23:59:59 - 和data.hiberarchy_common.expiration_time值一致
    └ custom_fieldsobject_field_data\[\]自定义字段
      └ field_namestring字段名
      └ valuestring字段值，是json转义后的字符串，根据元数据定义不同，字段格式不同(如123, 123.23, "true", ["id1","id2"], "2006-01-02 15:04:05")
    └ cost_center_idstring成本中心id，详细信息可通过【搜索成本中心信息】接口查询获得
    └ staffing_modelenum岗职管理模式 - 详细枚举类型请查看枚举场景中关于staffing_model定义
      └ enum_namestring枚举值
      └ displayi18n\[\]枚举多语展示
        └ langstring语言，支持中文和英文。中文用zh-CN；英文用en-US。
        └ valuestring内容

响应体示例 ​

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状态码错误码描述排查建议
4001160004request ID repeat重复请求，请确认是否已处理完成
4001160104custom field format error请检查自定义字段的格式是否正确
4001160106date format should be yyyy-mm-dd hh:mm:ss请检查时间类型字段的格式是否正确
4001160251superior department is required上级部门为必填，请检查上级部门是否为空
4001160252the number of characters in the text field exceeds the limit文本类字段的长度超过限制，请减少字符数
4001160253the name can't contain "/","；",or ";"部门名称中包含「/」、「；」、「;」、「\」、「'」请删除相关特殊字符
4001160254name already exists请检查名称是否与其他记录重复
4001160258the individual hasn't been onboard on effective date请检查人员在生效日期下是否未入职
4001160259the individual offboarded on effective date请检查人员在生效日期下是是否已离职
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 年，请检查生效日期是否正确
4001160321the name already exists名称已存在，请使用其他名称
4001160322department still have active subordinates on or after the effective date已废弃
4001160327the field doesn't exist请检查字段是否正确
4001160337effective date is required请检查生效日期是否为空
4001160340field must be in the yyyy-MM-dd HH:mm:ss format已废弃
4001160341doesn't exist已废弃
4001160343Duplicate code已废弃
4001160347superior department will be deactivated on or after the effective date上级部门在生效日期或之后将停用，请检查上级部门是否准确
4001160349superior department will be deactivated on or after the effective date上级部门在生效日期或之后将停用，请检查上级部门是否准确
4001160351superior department hasn't taken effect on effective date已废弃
4001160352the option has been deactivated请检查枚举类字段的选项是否已停用
4001160353the effective date can't be earlier than 1900生效日期不能早于 1900 年
4001160354必须是 string已废弃
4001160402lookup object value deactivated on the effective date已废弃

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

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