Mud Tools

接口名称

员工管理 - (FeishuUserV1Employees)

功能描述

本接口提供了飞书企业内员工管理的完整功能，包括创建、更新、查询、离职、恢复员工等操作。员工指飞书企业内身份为「Employee」的成员，等同于通讯录OpenAPI中的「User」。当前接口使用用户令牌访问，适应于用户应用场景。

参考文档

函数列表

函数名称	功能描述	认证方式	HTTP 方法
CreateEmployeeAsync	创建员工	用户令牌	POST
UpdateEmployeeAsync	更新员工信息	用户令牌	PATCH
DeleteEmployeeByIdAsync	离职员工	用户令牌	DELETE
ResurrectEmployeeAsync	恢复已离职员工	用户令牌	POST
ResignedEmployeeAsync	在职员工流转到待离职	用户令牌	PATCH
RegularEmployeeAsync	待离职员工取消离职	用户令牌	PATCH
QueryEmployeesAsync	批量查询员工详情	用户令牌	POST
QueryEmployeePageListAsync	分页获取员工列表	用户令牌	POST
SearchEmployeePageListAsync	搜索员工信息	用户令牌	POST

函数详细内容

创建员工

函数签名

csharp

Task<FeishuApiResult<EmployeeCreateResult>?> CreateEmployeeAsync(
    [Body] EmployeeCreateRequest userModel,
    [Query("employee_id_type")] string? employee_id_type = Consts.User_Id_Type,
    [Query("department_id_type")] string? department_id_type = Consts.Department_Id_Type,
    CancellationToken cancellationToken = default);

认证用户令牌

参数

参数名	类型	必填	说明	示例值
userModel	EmployeeCreateRequest	✅	创建员工的请求体	-
employee_id_type	string	⚪	用户ID类型	"open_id"
department_id_type	string	⚪	部门ID类型	"department_id"

请求体参数 (EmployeeCreateRequest)

参数名	类型	必填	说明	示例值
employee	EmployeeCreateInfo	✅	待创建员工对象	-
options	EmployeeCreateOptions	⚪	接口拓展选项	-

员工信息参数 (EmployeeCreateInfo)

参数名	类型	必填	说明	示例值
name	EmployeeName	✅	员工姓名	-
mobile	string	⚪	员工的手机号	"13800138000"
custom_employee_id	string	⚪	自定义员工ID	"custom123"
avatar_key	string	⚪	员工头像key	"8abc397a-9950-44ea-9302-e1d8fe00858g"
email	string	⚪	员工工作邮箱	"zhangsan@example.com"
enterprise_email	string	⚪	员工企业邮箱	"zhangsan@company.com"

拓展选项参数 (EmployeeCreateOptions)

参数名	类型	必填	说明	示例值
geo_name	string	⚪	员工的数据驻留地	"CN"
subscription_ids	List<string>	⚪	分配给员工的席位ID列表	["sub1", "sub2"]

响应

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "employee_id": "ou_7d8a6e6df7621552ce5d2f3c4d7e2e4d"
  }
}

错误码

错误码	错误信息	说明
99991663	employee already exist	员工已存在
99991400	invalid mobile number	无效的手机号
99991401	invalid email	无效的邮箱

说明

创建员工时，至少需要提供姓名和手机号或邮箱之一
员工ID支持自定义，未自定义时系统自动生成
员工创建成功后，会自动发送邀请通知
使用用户令牌时，默认为管理员用户，将校验管理员管理范围

代码示例

typescript

import { FeishuUserV1Employees } from 'mud-feishu';

const employeeApi = new FeishuUserV1Employees();

// 创建员工
const result = await employeeApi.createEmployee({
  employee: {
    name: {
      zh_cn: "张三"
    },
    mobile: "13800138000",
    email: "zhangsan@example.com"
  },
  options: {
    subscription_ids: ["sub1"]
  }
});

if (result.code === 0) {
  console.log(`员工创建成功，ID: ${result.data.employee_id}`);
} else {
  console.error(`员工创建失败: ${result.msg}`);
}

更新员工信息

函数签名

csharp

Task<FeishuNullDataApiResult?> UpdateEmployeeAsync(
   [Path] string employee_id,
   [Body] EmployeeUpdateRequest userModel,
   [Query("employee_id_type")] string? employee_id_type = Consts.User_Id_Type,
   [Query("department_id_type")] string? department_id_type = Consts.Department_Id_Type,
   CancellationToken cancellationToken = default);

认证用户令牌

参数

参数名	类型	必填	说明	示例值
employee_id	string	✅	员工ID	"ou_7d8a6e6df7621552ce5d2f3c4d7e2e4d"
userModel	EmployeeUpdateRequest	✅	更新员工的请求体	-
employee_id_type	string	⚪	用户ID类型	"open_id"
department_id_type	string	⚪	部门ID类型	"department_id"

请求体参数 (EmployeeUpdateRequest)

参数名	类型	必填	说明	示例值
employee	EmployeeCreateInfo	✅	待更新员工对象	-

响应

json

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

错误码

错误码	错误信息	说明
99991663	employee not found	员工不存在
99991400	invalid mobile number	无效的手机号
99991401	invalid email	无效的邮箱

说明

未传递的参数不会进行更新
支持更新员工基本信息、部门信息、职位信息等
使用用户令牌时，默认为管理员用户，将校验管理员管理范围

代码示例

typescript

import { FeishuUserV1Employees } from 'mud-feishu';

const employeeApi = new FeishuUserV1Employees();

// 更新员工信息
const result = await employeeApi.updateEmployee(
  "ou_7d8a6e6df7621552ce5d2f3c4d7e2e4d",
  {
    employee: {
      name: {
        zh_cn: "张三丰"
      },
      mobile: "13900139000"
    }
  }
);

if (result.code === 0) {
  console.log("员工信息更新成功");
} else {
  console.error(`员工信息更新失败: ${result.msg}`);
}

离职员工

函数签名

csharp

Task<FeishuNullDataApiResult?> DeleteEmployeeByIdAsync(
  [Path] string employee_id,
  [Body] DeleteEmployeeRequest deleteEmployeeRequest,
  [Query("employee_id_type")] string? employee_id_type = Consts.User_Id_Type,
  CancellationToken cancellationToken = default);

认证用户令牌

参数

参数名	类型	必填	说明	示例值
employee_id	string	✅	员工ID	"ou_7d8a6e6df7621552ce5d2f3c4d7e2e4d"
deleteEmployeeRequest	DeleteEmployeeRequest	✅	离职员工请求体	-
employee_id_type	string	⚪	用户ID类型	"open_id"

请求体参数 (DeleteEmployeeRequest)

参数名	类型	必填	说明	示例值
options	DeleteEmployeeOptions	⚪	离职员工接口拓展选项	-

拓展选项参数 (DeleteEmployeeOptions)

参数名	类型	必填	说明	示例值
resigned_employee_resource_receiver	DeleteEmployeeResourceReceiver	✅	离职员工的资源转移方式	-

资源转移参数 (DeleteEmployeeResourceReceiver)

参数名	类型	必填	说明	示例值
department_chat_acceptor_employee_id	string	⚪	部门群接收者ID	"ou_xxx"
external_chat_acceptor_employee_id	string	⚪	外部群接收者ID	"ou_xxx"
docs_acceptor_employee_id	string	⚪	文档接收者ID	"ou_xxx"
calendar_acceptor_employee_id	string	⚪	日程接收者ID	"ou_xxx"

响应

json

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

错误码

错误码	错误信息	说明
99991663	employee not found	员工不存在
99991668	employee already resigned	员工已离职
99991669	cannot resign employee due to permission	无权限离职员工

说明

使用用户令牌时，默认为管理员用户，将校验管理员管理范围
当用户有多个管理员身份均可离职员工时，管理员管理范围取最大集
离职员工时可以设置资源转移方式，包括群聊、文档、日程等

代码示例

typescript

import { FeishuUserV1Employees } from 'mud-feishu';

const employeeApi = new FeishuUserV1Employees();

// 离职员工
const result = await employeeApi.deleteEmployeeById(
  "ou_7d8a6e6df7621552ce5d2f3c4d7e2e4d",
  {
    options: {
      resigned_employee_resource_receiver: {
        department_chat_acceptor_employee_id: "ou_receiver1",
        docs_acceptor_employee_id: "ou_receiver2"
      }
    }
  }
);

if (result.code === 0) {
  console.log("员工离职成功");
} else {
  console.error(`员工离职失败: ${result.msg}`);
}

恢复已离职员工

函数签名

csharp

Task<FeishuNullDataApiResult?> ResurrectEmployeeAsync(
  [Path] string employee_id,
  [Body] ResurrectEmployeeRequest resurrectEmployeeRequest,
  [Query("employee_id_type")] string? employee_id_type = Consts.User_Id_Type,
  [Query("department_id_type")] string? department_id_type = Consts.Department_Id_Type,
  CancellationToken cancellationToken = default);

认证用户令牌

参数

参数名	类型	必填	说明	示例值
employee_id	string	✅	员工ID	"ou_7d8a6e6df7621552ce5d2f3c4d7e2e4d"
resurrectEmployeeRequest	ResurrectEmployeeRequest	✅	恢复离职员工请求体	-
employee_id_type	string	⚪	用户ID类型	"open_id"
department_id_type	string	⚪	部门ID类型	"department_id"

响应

json

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

错误码

错误码	错误信息	说明
99991663	employee not found	员工不存在
99991670	cannot resurrect employee due to permission	无权限恢复员工

说明

仅可恢复已离职的员工，恢复后员工状态变为在职
恢复员工时需要指定员工所属部门

代码示例

typescript

import { FeishuUserV1Employees } from 'mud-feishu';

const employeeApi = new FeishuUserV1Employees();

// 恢复离职员工
const result = await employeeApi.resurrectEmployee(
  "ou_7d8a6e6df7621552ce5d2f3c4d7e2e4d",
  {
    options: {
      department_ids: ["od_xxx"]
    }
  }
);

if (result.code === 0) {
  console.log("员工恢复成功");
} else {
  console.error(`员工恢复失败: ${result.msg}`);
}

在职员工流转到待离职

函数签名

csharp

Task<FeishuNullDataApiResult?> ResignedEmployeeAsync(
 [Path] string employee_id,
 [Body] ResignEmployeeRequest resignEmployeeRequest,
 [Query("employee_id_type")] string? employee_id_type = Consts.User_Id_Type,
 [Query("department_id_type")] string? department_id_type = Consts.Department_Id_Type,
 CancellationToken cancellationToken = default);

认证用户令牌

参数

参数名	类型	必填	说明	示例值
employee_id	string	✅	员工ID	"ou_7d8a6e6df7621552ce5d2f3c4d7e2e4d"
resignEmployeeRequest	ResignEmployeeRequest	✅	在职员工流转到待离职请求体	-
employee_id_type	string	⚪	用户ID类型	"open_id"
department_id_type	string	⚪	部门ID类型	"department_id"

请求体参数 (ResignEmployeeRequest)

参数名	类型	必填	说明	示例值
options	ResignEmployeeOption	✅	待离职选项	-

待离职选项参数 (ResignEmployeeOption)

参数名	类型	必填	说明	示例值
resign_date	string	✅	离职日期	"2024-06-21"
resign_reason	string	✅	离职原因	"1"
resign_type	string	✅	离职类型	"1"
resign_remark	string	⚪	离职备注	"个人发展"

响应

json

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

错误码

错误码	错误信息	说明
99991663	employee not found	员工不存在
99991671	cannot resign employee due to permission	无权限设置员工待离职

说明

使用用户令牌时默认为管理员用户，仅「人事管理模式」的管理员可操作
「待离职」员工不会自动离职，需要使用「离职员工」API操作离职和资源转交

代码示例

typescript

import { FeishuUserV1Employees } from 'mud-feishu';

const employeeApi = new FeishuUserV1Employees();

// 设置员工为待离职状态
const result = await employeeApi.resignedEmployee(
  "ou_7d8a6e6df7621552ce5d2f3c4d7e2e4d",
  {
    options: {
      resign_date: "2024-06-21",
      resign_reason: "1", // 1：薪酬不符合预期
      resign_type: "1",   // 1：主动
      resign_remark: "寻求更好的发展机会"
    }
  }
);

if (result.code === 0) {
  console.log("员工已设置为待离职状态");
} else {
  console.error(`设置待离职状态失败: ${result.msg}`);
}

待离职员工取消离职

函数签名

csharp

Task<FeishuNullDataApiResult> RegularEmployeeAsync(
     [Path] string employee_id,
     [Query("employee_id_type")] string? employee_id_type = Consts.User_Id_Type,
     [Query("department_id_type")] string? department_id_type = Consts.Department_Id_Type,
     CancellationToken cancellationToken = default);

认证用户令牌

参数

参数名	类型	必填	说明	示例值
employee_id	string	✅	员工ID	"ou_7d8a6e6df7621552ce5d2f3c4d7e2e4d"
employee_id_type	string	⚪	用户ID类型	"open_id"
department_id_type	string	⚪	部门ID类型	"department_id"

响应

json

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

错误码

错误码	错误信息	说明
99991663	employee not found	员工不存在
99991672	cannot regular employee due to permission	无权限取消员工离职

说明

使用用户令牌时默认为管理员用户，仅「人事管理模式」的管理员可操作
取消离职时会清空离职信息

代码示例

typescript

import { FeishuUserV1Employees } from 'mud-feishu';

const employeeApi = new FeishuUserV1Employees();

// 取消员工离职
const result = await employeeApi.regularEmployee(
  "ou_7d8a6e6df7621552ce5d2f3c4d7e2e4d"
);

if (result.code === 0) {
  console.log("已取消员工离职");
} else {
  console.error(`取消员工离职失败: ${result.msg}`);
}

批量查询员工详情

函数签名

csharp

Task<FeishuApiResult<EmployeeListResult>?> QueryEmployeesAsync(
    [Body] EmployeeQueryRequest employeeQueryRequest,
    [Query("employee_id_type")] string? employee_id_type = Consts.User_Id_Type,
    [Query("department_id_type")] string? department_id_type = Consts.Department_Id_Type,
    CancellationToken cancellationToken = default);

认证用户令牌

参数

参数名	类型	必填	说明	示例值
employeeQueryRequest	EmployeeQueryRequest	✅	员工查询请求体	-
employee_id_type	string	⚪	用户ID类型	"open_id"
department_id_type	string	⚪	部门ID类型	"department_id"

请求体参数 (EmployeeQueryRequest)

参数名	类型	必填	说明	示例值
employee_ids	List<string>	✅	员工ID列表	["ou_xxx", "ou_yyy"]

响应

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "employees": [
      {
        "employee_id": "ou_xxx",
        "name": {
          "zh_cn": "张三"
        },
        "mobile": "13800138000",
        "email": "zhangsan@example.com"
      }
    ]
  }
}

错误码

错误码	错误信息	说明
99991663	employee not found	员工不存在
99991673	too many employee ids	员工ID数量过多

说明

一次最多可查询50个员工
使用用户令牌时，只能查询有权限查看的员工信息

代码示例

typescript

import { FeishuUserV1Employees } from 'mud-feishu';

const employeeApi = new FeishuUserV1Employees();

// 批量查询员工详情
const result = await employeeApi.queryEmployees({
  employee_ids: ["ou_xxx", "ou_yyy", "ou_zzz"]
});

if (result.code === 0) {
  console.log(`查询到 ${result.data.employees.length} 个员工`);
  result.data.employees.forEach(emp => {
    console.log(`姓名: ${emp.name.zh_cn}, 手机: ${emp.mobile}`);
  });
} else {
  console.error(`查询员工失败: ${result.msg}`);
}

分页获取员工列表

函数签名

csharp

Task<FeishuApiResult<EmployeePageListResult>?> QueryEmployeePageListAsync(
   [Body] FilterSearchRequest filterSearchRequest,
   [Query("employee_id_type")] string? employee_id_type = Consts.User_Id_Type,
   [Query("department_id_type")] string? department_id_type = Consts.Department_Id_Type,
   CancellationToken cancellationToken = default);

认证用户令牌

参数

参数名	类型	必填	说明	示例值
filterSearchRequest	FilterSearchRequest	✅	字段过滤查询条件请求体	-
employee_id_type	string	⚪	用户ID类型	"open_id"
department_id_type	string	⚪	部门ID类型	"department_id"

请求体参数 (FilterSearchRequest)

参数名	类型	必填	说明	示例值
filters	List<FieldFilter>	⚪	过滤条件	-
order_by	List<string>	⚪	排序字段	["name"]
page_size	int	⚪	页面大小	50
page_token	string	⚪	分页标记	"xxx"

响应

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "employees": [
      {
        "employee_id": "ou_xxx",
        "name": {
          "zh_cn": "张三"
        },
        "mobile": "13800138000",
        "email": "zhangsan@example.com"
      }
    ],
    "page_token": "next_page_token",
    "has_more": true
  }
}

错误码

错误码	错误信息	说明
99991674	invalid filter	无效的过滤条件
99991675	invalid order by	无效的排序字段

说明

使用用户令牌时，只能查询有权限查看的员工信息
支持按多种字段过滤和排序

代码示例

typescript

import { FeishuUserV1Employees } from 'mud-feishu';

const employeeApi = new FeishuUserV1Employees();

// 分页获取员工列表
let pageToken = "";
do {
  const result = await employeeApi.queryEmployeePageList({
    filters: [
      {
        field: "status",
        operator: "eq",
        value: "active"
      }
    ],
    order_by: ["name"],
    page_size: 50,
    page_token: pageToken
  });

  if (result.code === 0) {
    console.log(`当前页员工数: ${result.data.employees.length}`);
    // 处理员工数据
    result.data.employees.forEach(emp => {
      console.log(`姓名: ${emp.name.zh_cn}, 状态: ${emp.status}`);
    });

    pageToken = result.data.page_token;
  } else {
    console.error(`查询员工列表失败: ${result.msg}`);
    break;
  }
} while (pageToken && result.data.has_more);

搜索员工信息

函数签名

csharp

Task<FeishuApiResult<EmployeePageListResult>?> SearchEmployeePageListAsync(
  [Body] PageSearchRequest pageSearchRequest,
  [Query("employee_id_type")] string? employee_id_type = Consts.User_Id_Type,
  [Query("department_id_type")] string? department_id_type = Consts.Department_Id_Type,
  CancellationToken cancellationToken = default);

认证用户令牌

参数

参数名	类型	必填	说明	示例值
pageSearchRequest	PageSearchRequest	✅	分页查询参数请求体	-
employee_id_type	string	⚪	用户ID类型	"open_id"
department_id_type	string	⚪	部门ID类型	"department_id"

请求体参数 (PageSearchRequest)

参数名	类型	必填	说明	示例值
query	string	✅	搜索关键词	"张"
page_size	int	⚪	页面大小	50
page_token	string	⚪	分页标记	"xxx"

响应

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "employees": [
      {
        "employee_id": "ou_xxx",
        "name": {
          "zh_cn": "张三"
        },
        "mobile": "13800138000",
        "email": "zhangsan@example.com"
      }
    ],
    "page_token": "next_page_token",
    "has_more": true
  }
}

错误码

错误码	错误信息	说明
99991676	invalid query	无效的搜索关键词

说明

搜索关键词可匹配员工姓名、手机号、邮箱等信息
使用用户令牌时，只能搜索有权限查看的员工信息

代码示例

typescript

import { FeishuUserV1Employees } from 'mud-feishu';

const employeeApi = new FeishuUserV1Employees();

// 搜索员工信息
let pageToken = "";
const keyword = "张";
do {
  const result = await employeeApi.searchEmployeePageList({
    query: keyword,
    page_size: 50,
    page_token: pageToken
  });

  if (result.code === 0) {
    console.log(`关键词"${keyword}"当前页结果数: ${result.data.employees.length}`);
    // 处理搜索结果
    result.data.employees.forEach(emp => {
      console.log(`姓名: ${emp.name.zh_cn}, 手机: ${emp.mobile}`);
    });

    pageToken = result.data.page_token;
  } else {
    console.error(`搜索员工失败: ${result.msg}`);
    break;
  }
} while (pageToken && result.data.has_more);

部门管理

员工管理

用户管理

用户组管理

职位管理

角色管理

工作城市管理

接口名称

功能描述

参考文档

函数列表

函数详细内容

创建员工

更新员工信息

离职员工

恢复已离职员工

在职员工流转到待离职

待离职员工取消离职

批量查询员工详情

分页获取员工列表

搜索员工信息

接口名称 ​

功能描述 ​

参考文档 ​

函数列表 ​

函数详细内容 ​

创建员工 ​

更新员工信息 ​

离职员工 ​

恢复已离职员工 ​

在职员工流转到待离职 ​

待离职员工取消离职 ​

批量查询员工详情 ​

分页获取员工列表 ​

搜索员工信息 ​

接口名称

功能描述

参考文档

函数列表

函数详细内容

创建员工

更新员工信息

离职员工

恢复已离职员工

在职员工流转到待离职

待离职员工取消离职

批量查询员工详情

分页获取员工列表

搜索员工信息