飞书开放平台 Server API 文档

主题

更新岗位信息 ​

更新岗位的版本信息，例如岗位关联的职务、职级、序列，以及岗位描述等

Tip: - 非必填字段，不传时即不做变更

  • 如果传入生效时间当天不存在版本则会自动生成一个版本。
  • 如果传入生效时间当天存在版本则会修改该版本。

Warning: 岗位在关联人员、异动、入职对象信息及建立自身上下级关系后，不允许更新部门

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/corehr/v2/positions/:position_id
HTTP MethodPATCH
接口频率限制5 次/秒
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用corehr:position:write 读写岗位信息

请求头 ​

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

路径参数 ​

名称类型描述
position_idstring岗位 ID 列表，详细信息可通过查询岗位信息接口获得
示例值："6862995757234914824"

查询参数 ​

名称类型必填描述
client_tokenstring否根据client_token是否一致来判断是否为同一请求
示例值：1245464678
数据校验规则：
- 长度范围：0 ～ 128 字符
department_id_typestring否此次调用中使用的部门 ID 类型，三种类型的 ID 都可通过飞书人事的批量查询部门（ V2） 来获取
示例值：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

请求体 ​

名称类型必填描述
codestring否编码 (不能与其他记录的编码重复) - 如果开启了岗位自动编码，此字段传入不生效
示例值："A01234"
namesi18n\[\]否名称
数据校验规则：
- 长度范围：0 ～ 2
  └ langstring是名称信息的语言，支持中文和英文。中文用zh-CN；英文用en-US
示例值："zh-CN"
  └ valuestring是- 支持 zh-CN 和 en-US，最大长度为 255 字符 - 名称不能包含「/」「；」「;」「\」「'」字符
示例值："张三"
descriptionsi18n\[\]否描述
数据校验规则：
- 长度范围：0 ～ 2
  └ langstring是语言
示例值："zh-CN"
  └ valuestring是支持 zh-CN 和 en-US，最大长度为 255 字符
示例值："张三"
job_family_idsstring\[\]否序列 ID 列表，详细信息可通过查询单个序列接口获得
示例值：["4719519211875096301"]
数据校验规则：
- 长度范围：0 ～ 50
cost_center_idstring否成本中心 ID，可以通过搜索成本中心信息接口获取对应的成本中心信息
示例值："4719519211875096301"
job_idstring否职务，可通过【查询单个职务】获取详细信息
示例值："4719519211875096301"
job_level_idsstring\[\]否职级 ID 列表，可通过【查询单个职级】获取详细信息
示例值：["4719519211875096301"]
数据校验规则：
- 长度范围：0 ～ 50
employee_type_idsstring\[\]否人员类型 ID 列表，可通过文档查询人员类型获得详细信息
示例值：["4719519211875096301"]
数据校验规则：
- 长度范围：0 ～ 50
job_grade_idsstring\[\]否职等 ID 列表，可通过 【查询职等】获取详细信息
示例值：["4719519211875096301"]
数据校验规则：
- 长度范围：0 ～ 50
work_location_idsstring\[\]否工作地点 ID 列表，详细信息可通过查询单个地点接口获得
示例值：["4719519211875096301"]
数据校验规则：
- 长度范围：0 ～ 50
working_hours_type_idstring否工时制度 ID 列表，可通过【查询单个工时制度】查询详细信息
示例值："4719519211875096301"
department_idstring否部门 ID，详细信息可通过查询单个部门接口获得 - 类型与 department_id_type 一致
示例值："4719519211875096301"
direct_leader_idstring否直属上级岗位ID，详细信息可通过查询岗位信息接口获得
示例值："4719519211875096301"
dotted_line_leader_idstring否虚线上级岗位ID，详细信息可通过查询岗位信息接口获得
示例值："4719519211875096301"
is_key_positionboolean否是否关键岗位
示例值：true
effective_timestring是版本生效日期
示例值："2020-05-01"
数据校验规则：
- 正则校验：`^((([0-9]{3}[1-9]
custom_fieldscustom_field_data\[\]否自定义字段
数据校验规则：
- 长度范围：0 ～ 200
  └ custom_api_namestring是自定义字段 apiname，即自定义字段的唯一标识
示例值："name"
  └ valuestring是字段值，是 json 转义后的字符串，根据元数据定义不同，字段格式不同（如 123, 123.23, "true", ["id1","id2"], "2006-01-02 15:04:05"）
示例值：""231""

请求体示例 ​

json
{
    "code": "A01234",
    "names": [
        {
            "lang": "zh-CN",
            "value": "张三"
        }
    ],
    "descriptions": [
        {
            "lang": "zh-CN",
            "value": "张三"
        }
    ],
    "job_family_ids": [
        "4719519211875096301"
    ],
    "cost_center_id": "4719519211875096301",
    "job_id": "4719519211875096301",
    "job_level_ids": [
        "4719519211875096301"
    ],
    "employee_type_ids": [
        "4719519211875096301"
    ],
    "job_grade_ids": [
        "4719519211875096301"
    ],
    "work_location_ids": [
        "4719519211875096301"
    ],
    "working_hours_type_id": "4719519211875096301",
    "department_id": "4719519211875096301",
    "direct_leader_id": "4719519211875096301",
    "dotted_line_leader_id": "4719519211875096301",
    "is_key_position": true,
    "effective_time": "2020-05-01",
    "custom_fields": [
        {
            "custom_api_name": "name",
            "value": "\"231\""
        }
    ]
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {}
}

错误码 ​

HTTP状态码错误码描述排查建议
4001160263Name or code already exists名称或编码已存在，请检查名称或编码是否与现有记录重复后重试
4001160903Name already exists名称已存在，请检查名称是否与现有记录重复后重试
4001160259Individual is offboarded on the effecitve date传入的人员类型字段的人员在生效日期当天已离职，请检查人员类型字段的人员在生效日期当天的在职状态后重试
4001160572URL is illegal链接类型字段非法，请检查链接格式是否符合要求后重试
4001160253"Name can't include "/" or ";"名称包含禁止的字符（如"/"、";"），请检查名称后重试
4001160266Effective date must be later than the first effective date传入的生效日期必须晚于第一个版本的生效日期，请检查后重试
4001160251Required field(s) is empty必填字段不能为空，请检查后重试
4001160701The job doesn't exist on the effective date.传入的职务在生效日期当天不存在，请检查后重试
4001160702The job will be deactivated on or after the effective date.传入的职务在生效日期当天或未来停用，请检查后重试
4001160703The job family doesn't exist on the effective date.传入的序列在生效日期不存在，请检查后重试
4001160269Effective date can't be later than the year 9999生效日期不能晚于9999
4001160353Effective Date cannot earlier than 1900生效日期不能早于1900
4001160704传入的序列在生效日期当天或未来停用，请检查后重试The job family will be deactivated on or after the effective date
4001160705The job level doesn't exist传入的职级不存在，请检查后重试
4001160707The job grade doesn't exist传入的职等不存在，请检查后重试
4001160709The job and job family doesn't match传入的职务和序列不匹配，请检查后重试
4001160710The job and job level doesn't match传入的职务和职级不匹配，请检查后重试
4001160711The job level and job family doesn't match传入的职级和序列不匹配，请检查后重试
4001160712the job level and job grade doesn't match传入的职级和职等不匹配，请检查后重试
4001160714The position doesn't exist on the effective date.岗位在传入的生效日期当天未生效，请检查后重试
4001160104Record doesn't exist岗位记录不存在，请检查后重试
4001160715The position will be deactivated on or after the effective date岗位在生效日期当天或未来停用，请检查后重试
4001160515Effective date must be later than the first effective date生效日期必须晚于第一个版本的生效日期，请检查后重试
4001160255Parent position hasn't taken effect on effective date上级岗位在传入的生效日期当天尚未生效，请检查后重试
4001160256Parent position will be deactivated on or after this effective date上级岗位在传入的生效日期当天或未来停用，请检查后重试
4001160264This operation will make the relationship between the superior and the subordinate into a ring更新后，会出现岗位上下级关系成环，请修改上级后重试
4001161603Name already exists岗位名称重复，请修改名称后重试
4001160271Unable to submit as no changes have been made数据无变更，请检查后重试
5031161204Requset timeout接口超时，请重试。必要时请联系 技术支持
4291161604QPS over limitQPS 超出限制，请降低请求频率重试，必要时请联系 技术支持

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

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