飞书开放平台 Server API 文档

主题

发起流程 ​

发起一个流程实例，目前只支持发起自定义业务类型的流程。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/corehr/v2/process_start
HTTP MethodPOST
接口频率限制20 次/分钟
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用corehr:process.instance: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"

查询参数 ​

名称类型必填描述
user_id_typestring否用户 ID 类型
示例值：open_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 来识别用户
默认值：open_id
当值为 user_id，字段权限要求： contact:user.employee_id:readonly 获取用户 user ID
department_id_typestring否此次调用中使用的部门 ID 类型
示例值：open_department_id
可选值有：
- open_department_id: 以 open_department_id 来标识部门 - department_id: 以 department_id 来标识部门 - people_corehr_department_id: 以 people_corehr_department_id 来标识部门
默认值：open_department_id

请求体 ​

名称类型必填描述
flow_definition_idstring是流程定义id
示例值："people_7023711013443944467_7437160904904494892"
initiator_idstring否发起人用户ID，按user_id_type类型传递。如果system_initiator为false，则必填；为true时非必填。
示例值："ou_91791271921729102012"
system_initiatorboolean否是否为系统身份发起流程，如果为false，则initiator_id必填
示例值：true
flow_dataprocess_form_variable_v2\[\]否业务数据
数据校验规则：
- 长度范围：0 ～ 100000
  └ variable_api_namestring否变量唯一标识
示例值："custom123"
  └ variable_valuefield_variable_value_to_for_review否变量值
    └ text_valuestring否文本值
示例值："测试测试"
    └ bool_valueboolean否布尔值
示例值：true
    └ number_valuestring否数字值
示例值："100"
    └ enum_valuestring否枚举值，这里是枚举的id
示例值："home_address"
    └ date_valuestring否从 1970 开始的天数
示例值："19838"
    └ date_time_valuestring否时间戳，毫秒
示例值："1714013877512"
    └ i18n_valuefield_variable_value_i18n否多语字段值
示例值：ou_c57053dad6eea0aea4696c48433d8562
      └ zh_cnstring否中文值
示例值："北京"
      └ en_usstring否英文值
示例值："Beijing"
    └ object_valuefield_variable_value_to_object否对象值，包括对象id和对象类型
示例值：od-a761814f6bc3f14bd3b00905ec1d7c6f
      └ wk_idstring否wukong的对象唯一标识
示例值："6863326263210149383"
      └ wk_api_namestring否wukong的元数据唯一标识
示例值："country_region_subdivision"
    └ department_valuestring否部门id，根据入参选择对应的部门id
示例值："od-a761814f6bc3f14bd3b00905ec1d7c6f"
    └ employment_valuestring否员工类型字段值，为用户id，根据入参选择返回的用户id
示例值："ou_c57053dad6eea0aea4696c48433d8562"
    └ list_valuesstring\[\]否数组类型值，里面包含多个值，每个元素都对应subValues中的key
示例值：["key1"]
数据校验规则：
- 长度范围：0 ～ 10000
    └ file_valuefield_variable_value_to_file_for_write否文件类型字段值
      └ open_file_idstring否通过上传文件接口获得的id
示例值："66867ed00740ddd4a0bad4a5_c99b5322dc744fe4b99b76426ffe5d53"
      └ file_namestring否文件名称（需带有文件后缀），如果填写，则会覆盖上传文件的名称，否则通过open_file_id获取原始名称
示例值："file_name.jpg"
      └ lengthint否文件大小，单位：Byte，如果填写，则会覆盖上传文件的大小，否则通过open_file_id获取文件原始大小
示例值：65535
数据校验规则：
- 取值范围：0 ～ 52428800
    └ record_valuesfield_variable_value_to_record\[\]否record类型字段值
      └ variable_api_namestring否变量唯一标识
示例值："city_v2"
      └ sub_value_keystring否变量值，对应subValues中的key
示例值："key1"
      └ record_idstring否记录唯一ID
示例值："6863326263210149383"
  └ sub_valuesfield_variable_sub_vlaue_for_review\[\]否在list_values和record_values中引用的变量
数据校验规则：
- 长度范围：0 ～ 100000
    └ keystring否用于关联list和record类型变量值中的key
示例值："key1"
    └ valuefield_variable_value_to_for_review否变量值
      └ text_valuestring否文本值
示例值："测试测试"
      └ bool_valueboolean否布尔值
示例值：true
      └ number_valuestring否数字值
示例值："100"
      └ enum_valuestring否枚举值，这里是枚举的id
示例值："home_address"
      └ date_valuestring否从 1970 开始的天数
示例值："19838"
      └ date_time_valuestring否时间戳，毫秒
示例值："1714013877512"
      └ i18n_valuefield_variable_value_i18n否多语字段值
示例值：ou_c57053dad6eea0aea4696c48433d8562
        └ zh_cnstring否中文值
示例值："北京"
        └ en_usstring否英文值
示例值："Beijing"
      └ object_valuefield_variable_value_to_object否对象值，包括对象id和对象类型
示例值：od-a761814f6bc3f14bd3b00905ec1d7c6f
        └ wk_idstring否wukong的对象唯一标识
示例值："6863326263210149383"
        └ wk_api_namestring否wukong的元数据唯一标识
示例值："country_region_subdivision"
      └ department_valuestring否部门id，根据入参选择对应的部门id
示例值："od-a761814f6bc3f14bd3b00905ec1d7c6f"
      └ employment_valuestring否员工类型字段值，为用户id，根据入参选择返回的用户id
示例值："ou_c57053dad6eea0aea4696c48433d8562"
      └ list_valuesstring\[\]否数组类型值，里面包含多个值，每个元素都对应subValues中的key
示例值：["key1"]
数据校验规则：
- 长度范围：0 ～ 10000
      └ file_valuefield_variable_value_to_file_for_write否文件类型字段值
        └ open_file_idstring否通过上传文件接口获得的id
示例值："66867ed00740ddd4a0bad4a5_c99b5322dc744fe4b99b76426ffe5d53"
        └ file_namestring否文件名称（需带有文件后缀），如果填写，则会覆盖上传文件的名称，否则通过open_file_id获取原始名称
示例值："file_name.jpg"
        └ lengthint否文件大小，单位：Byte，如果填写，则会覆盖上传文件的大小，否则通过open_file_id获取文件原始大小
示例值：65535
数据校验规则：
- 取值范围：0 ～ 52428800
      └ record_valuesfield_variable_value_to_record\[\]否record类型字段值
        └ variable_api_namestring否变量唯一标识
示例值："city_v2"
        └ sub_value_keystring否变量值，对应subValues中的key
示例值："key1"
        └ record_idstring否记录唯一ID
示例值："6863326263210149383"

请求体示例 ​

json
{
    "flow_definition_id": "people_7023711013443944467_7437160904904494892",
    "initiator_id": "ou_91791271921729102012",
    "system_initiator": true,
    "flow_data": [
        {
            "variable_api_name": "custom123",
            "variable_value": {
                "text_value": "测试测试",
                "bool_value": true,
                "number_value": "100",
                "enum_value": "home_address",
                "date_value": "19838",
                "date_time_value": "1714013877512",
                "i18n_value": {
                    "zh_cn": "北京",
                    "en_us": "Beijing"
                },
                "object_value": {
                    "wk_id": "6863326263210149383",
                    "wk_api_name": "country_region_subdivision"
                },
                "department_value": "od-a761814f6bc3f14bd3b00905ec1d7c6f",
                "employment_value": "ou_c57053dad6eea0aea4696c48433d8562",
                "list_values": [
                    "key1"
                ],
                "file_value": {
                    "open_file_id": "66867ed00740ddd4a0bad4a5_c99b5322dc744fe4b99b76426ffe5d53",
                    "file_name": "file_name.jpg",
                    "length": 65535
                },
                "record_values": [
                    {
                        "variable_api_name": "city_v2",
                        "sub_value_key": "key1",
                        "record_id": "6863326263210149383"
                    }
                ]
            },
            "sub_values": [
                {
                    "key": "key1",
                    "value": {
                        "text_value": "测试测试",
                        "bool_value": true,
                        "number_value": "100",
                        "enum_value": "home_address",
                        "date_value": "19838",
                        "date_time_value": "1714013877512",
                        "i18n_value": {
                            "zh_cn": "北京",
                            "en_us": "Beijing"
                        },
                        "object_value": {
                            "wk_id": "6863326263210149383",
                            "wk_api_name": "country_region_subdivision"
                        },
                        "department_value": "od-a761814f6bc3f14bd3b00905ec1d7c6f",
                        "employment_value": "ou_c57053dad6eea0aea4696c48433d8562",
                        "list_values": [
                            "key1"
                        ],
                        "file_value": {
                            "open_file_id": "66867ed00740ddd4a0bad4a5_c99b5322dc744fe4b99b76426ffe5d53",
                            "file_name": "file_name.jpg",
                            "length": 65535
                        },
                        "record_values": [
                            {
                                "variable_api_name": "city_v2",
                                "sub_value_key": "key1",
                                "record_id": "6863326263210149383"
                            }
                        ]
                    }
                }
            ]
        }
    ]
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ process_idstring流程运行实例 id，详细信息可通过获取单个流程详情获取

响应体示例 ​

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

错误码 ​

HTTP状态码错误码描述排查建议
4001161001参数错误参数错误，请操作接口字段说明自查
4031161002无权限请确认是否已申请权限
4001161059flow未启用请确认流程是否已启用
4001161060未能获取到租户id和用户id请检查租户id和用户id是否正确

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

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