飞书开放平台 Server API 文档

主题

更新部门 ​

更新部门信息，包括基础信息、自定义字段信息。

Error: 该接口不再推荐使用，请使用【更新部门】接口。

Warning: 权限说明：该接口不支持范围权限校验，不支持字段权限校验

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/corehr/v1/departments/:department_id
HTTP MethodPATCH
接口频率限制100 次/分钟
支持的应用类型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"

路径参数 ​

名称类型描述
department_idstring需要更新的部门ID，同部门实体在CoreHR内部的唯一键
示例值："6969828847121885087"

查询参数 ​

名称类型必填描述
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: 以 open_department_id 来标识部门 - department_id: 以 department_id 来标识部门 - people_corehr_department_id: 以 people_corehr_department_id 来标识部门
默认值：people_corehr_department_id

请求体 ​

名称类型必填描述
idstring否部门 ID
示例值："6969828847121885087"
sub_typeenum否部门子类型，枚举值可通过文档【飞书人事枚举常量】部门子类型（department_sub_type）枚举定义部分获得
  └ enum_namestring是枚举值
示例值："type_1"
managerstring否部门负责人 ID，枚举值及详细信息可通过【批量查询员工信息】查询获得
示例值："6893013238632416776"
is_confidentialboolean否是否保密
示例值：true
hiberarchy_commonhiberarchy_common否组织实体公共字段，包括名称、描述、上级、启停用状态、生效日期、编码等基础信息
  └ parent_idstring否上级组织 ID
示例值："4719168654814483759"
  └ namei18n\[\]否名称
    └ langstring是名称信息的语言，支持中文和英文。中文用zh-CN；英文用en-US。
示例值："zh-CN"
    └ valuestring是名称信息的内容
示例值："研发部"
  └ activeboolean否是否启用该部门
示例值：true
  └ codestring否编码
示例值："12456"
  └ descriptioni18n\[\]否描述
    └ langstring是名称信息的语言，支持中文和英文。中文用zh-CN；英文用en-US。
示例值："zh-CN"
    └ valuestring是名称信息的内容
示例值："张三"
effective_timestring是生效时间
示例值："2020-05-01 00:00:00"
custom_fieldsobject_field_data\[\]否自定义字段，枚举值可通过获取自定义字段列表获取
  └ field_namestring是自定义字段 apiname，即自定义字段的唯一标识
示例值："name"
  └ valuestring是字段值，是json转义后的字符串，根据元数据定义不同，字段格式不同(如123, 123.23, "true", ["id1","id2"], "2006-01-02 15:04:05")
示例值：""Sandy""
cost_center_idstring否成本中心 ID，可以通过搜索成本中心信息接口获取对应的成本中心信息
示例值："7142384817131652652"
staffing_modelenum否岗职管理模式 - 详细枚举类型请查看枚举场景中关于staffing_model定义
  └ enum_namestring是枚举值
示例值："job"

请求体示例 ​

json
{
    "id": "6969828847121885087",
    "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": "job"
    }
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ departmentdepartment部门
    └ idstring部门 ID
    └ sub_typeenum部门子类型，枚举值可通过文档【飞书人事枚举常量】部门子类型（department_sub_type）枚举定义部分获得
      └ 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生效时间
      └ expiration_timestring失效时间
      └ codestring编码
      └ descriptioni18n\[\]描述
        └ langstring名称信息的语言，支持中文和英文。中文用zh-CN；英文用en-US。
        └ valuestring名称信息的内容
      └ tree_orderstring树形排序，代表同层级的部门排序序号。新建的部门，该字段默认为空，有两种情况会自动写入值： - 管理员在部门管理页面上拖动排序； - 定时任务更新该字段为空的数据，3分钟/次
      └ list_orderstring列表排序，代表所有部门的混排序号。新建的部门，该字段默认为空，有两种情况会自动写入值： - 管理员在部门管理页面上拖动排序； - 定时任务更新该字段为空的数据，3分钟/次
      └ custom_fieldsobject_field_data\[\]自定义字段
        └ field_namestring自定义字段 apiname，即自定义字段的唯一标识，枚举值可通过获取自定义字段列表接口查询
        └ valuestring字段值，是json转义后的字符串，根据元数据定义不同，字段格式不同(如123, 123.23, "true", ["id1","id2"], "2006-01-02 15:04:05")
    └ effective_timestring生效时间
    └ expiration_timestring失效时间
    └ 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岗职务模式
      └ enum_namestring枚举值：job、non_job、position
      └ displayi18n\[\]枚举多语展示
        └ langstring语言，支持中文和英文。中文用zh-CN；英文用en-US。
        └ valuestring内容

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "department": {
            "id": "6969828847121885087",
            "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": "job",
                "display": [
                    {
                        "lang": "zh-CN",
                        "value": "刘梓新"
                    }
                ]
            }
        }
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
5001160101marshal error已废弃
5001160102unmarshal error已废弃
5001160103request ID is required请检查 ID 是否为空
5001160104custom field format error请检查自定义字段的格式是否正确
5001160105field is required已废弃
5001160106date format should be YYYY-MM-DD hh:mm:ss请检查时间类型字段的格式是否正确
4001160107param is invalid已废弃
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名称已存在，请使用其他名称
4001160327the field doesn't exist请检查字段是否正确
4001160343Duplicate code已废弃
4001160344unable to edit org as it was deactivated on date已废弃
4001160347superior department will be deactivated on or after the effective date上级部门在生效日期或之后将停用，请检查上级部门是否准确
4001160349superior department will be deactivated on or after the effective date上级部门在生效日期或之后将停用，请检查上级部门是否准确
4001160352the option has been deactivated请检查枚举类字段的选项是否已停用
4001160353the effective date can't be earlier than 1900生效日期不能早于 1900 年
4001160354service rate limiting protection, please try again later已废弃

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

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