飞书开放平台 Server API 文档

主题

创建岗位信息 ​

创建岗位，可定义岗位关联的职务、职级、序列，以及岗位描述等

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

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

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/corehr/v2/positions
HTTP MethodPOST
接口频率限制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"

查询参数 ​

名称类型必填描述
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；英文用en-US
示例值："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，详细信息可通过查询单个部门接口获得 - 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，即自定义字段的唯一标识，由租户自定义，可通过 查询岗位信息 获取 - 最多传入 200 个自定义字段
示例值："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\--
  └ position_idstring岗位ID

响应体示例 ​

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

错误码 ​

HTTP状态码错误码描述排查建议
4001160263Name or code already exists名称或编码已存在，请检查后重试
4001160903Name already exists名称已存在，请检查后重试
4001160352Invalid enum option枚举值非法，请检查后重试
4001160259Individual is offboarded on the effecitve date传入的人员类型字段的人员在生效日期当天已离职，请检查后重试
4001160517Number out of range传入的数字类型数字值超过最大限制，请检查后重试
4001160572URL is illegal链接有问题，请检查链接格式是否符合要求或确保链接有效
4001160402The data is not activated on the effective date关联的对象在生效日期是失效状态，请检查后重试
4001160251Required field(s) is empty必填字段不能为空，请检查并补充必填字段后重试
4001160701The job doesn't exist on the effective date.传入的职务在生效日期当天不存在，请检查后重试
4001160253Name can't include "/" or ";"名称包含不允许的字符，请修改名称后重试
4001160702The job will be deactivated on or after the effective date.传入的职务在生效日期当天或未来停用，请检查后重试
4001160269Effective date can't be later than the year 9999生效日期不能晚于9999，请检查并调整生效日期后重试
4001160353Effective Date cannot earlier than 1900生效日期不能早于1900，请检查并调整生效日期后重试
4001160703The job family doesn't exist on the effective date.传入的序列在生效日期当天不存在，请检查后重试
4001160704The 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.岗位在传入的生效日期当天不存在，请检查后重试
4001160715The position will be deactivated on or after the effective date岗位在传入的生效日期当天或未来停用，请检查后重试
4001160349Field(s) will be deactivated on or after this 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岗位名称重复，请修改名称后重试
5031161204Requset timeout接口超时，请重试。必要时请联系 技术支持
4291161604QPS over limitQPS 超出限制，请降低请求频率重试，必要时请联系 技术支持

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

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