Mud Tools

接口名称

员工管理 - (FeishuTenantV1Employees)

功能描述

本接口提供了飞书企业内员工管理的完整功能，包括创建、更新、查询、离职、恢复员工等操作。员工指飞书企业内身份为「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 { FeishuTenantV1Employees } from 'mud-feishu';

const employeeApi = new FeishuTenantV1Employees();

// 创建员工
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 { FeishuTenantV1Employees } from 'mud-feishu';

const employeeApi = new FeishuTenantV1Employees();

// 更新员工信息
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 { FeishuTenantV1Employees } from 'mud-feishu';

const employeeApi = new FeishuTenantV1Employees();

// 离职员工
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 { FeishuTenantV1Employees } from 'mud-feishu';

const employeeApi = new FeishuTenantV1Employees();

// 恢复离职员工
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 { FeishuTenantV1Employees } from 'mud-feishu';

const employeeApi = new FeishuTenantV1Employees();

// 设置员工为待离职状态
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 { FeishuTenantV1Employees } from 'mud-feishu';

const employeeApi = new FeishuTenantV1Employees();

// 取消员工离职
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",
        "department_ids": ["od_xxx"]
      }
    ]
  }
}

错误码

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

说明

一次最多可查询50个员工
返回员工的详细信息，包括基本信息、部门信息等

代码示例

typescript

import { FeishuTenantV1Employees } from 'mud-feishu';

const employeeApi = new FeishuTenantV1Employees();

// 批量查询员工信息
const result = await employeeApi.queryEmployees({
  employee_ids: ["ou_7d8a6e6df7621552ce5d2f3c4d7e2e4d", "ou_7d8a6e6df7621552ce5d2f3c4d7e2e4e"]
});

if (result.code === 0) {
  console.log("查询到员工信息:");
  result.data.employees.forEach(emp => {
    console.log(`${emp.name.zh_cn} - ${emp.email}`);
  });
} 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)

参数名	类型	必填	说明	示例值
page_size	number	⚪	分页大小	20
page_token	string	⚪	分页标记	"xxx"
user_id_type	string	⚪	用户ID类型	"open_id"
department_id_type	string	⚪	部门ID类型	"department_id"
filter_conditions	List<FieldCondition>	⚪	过滤条件	-

响应

json

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

错误码

错误码	错误信息	说明
99991673	page size too large	分页大小过大

说明

支持按多种条件过滤员工，如部门、状态、职位等
使用page_token实现分页查询

代码示例

typescript

import { FeishuTenantV1Employees } from 'mud-feishu';

const employeeApi = new FeishuTenantV1Employees();

// 分页获取员工列表
let pageToken = "";
do {
  const result = await employeeApi.queryEmployeePageList({
    page_size: 20,
    page_token: pageToken,
    filter_conditions: [
      {
        field: "department_ids",
        operator: "contains",
        value: ["od_xxx"]
      }
    ]
  });

  if (result.code === 0) {
    console.log("获取到员工列表:");
    result.data.employees.forEach(emp => {
      console.log(`${emp.name.zh_cn} - ${emp.email}`);
    });

    pageToken = result.data.page_token || "";
  } else {
    console.error(`获取员工列表失败: ${result.msg}`);
    break;
  }
} while (pageToken);

搜索员工信息

函数签名

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	number	⚪	分页大小	20
page_token	string	⚪	分页标记	"xxx"
user_id_type	string	⚪	用户ID类型	"open_id"
department_id_type	string	⚪	部门ID类型	"department_id"

响应

json

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

错误码

错误码	错误信息	说明
99991673	page size too large	分页大小过大

说明

支持通过关键词搜索员工的名称、手机号、邮箱等信息
使用page_token实现分页查询

代码示例

typescript

import { FeishuTenantV1Employees } from 'mud-feishu';

const employeeApi = new FeishuTenantV1Employees();

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

  if (result.code === 0) {
    console.log("搜索到员工:");
    result.data.employees.forEach(emp => {
      console.log(`${emp.name.zh_cn} - ${emp.email}`);
    });

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

部门管理

员工管理

用户管理

用户组管理

职位管理

角色管理

工作城市管理

接口名称

功能描述

参考文档

函数列表

函数详细内容

创建员工

更新员工信息

离职员工

恢复已离职员工

在职员工流转到待离职

待离职员工取消离职

批量查询员工详情

分页获取员工列表

搜索员工信息

接口名称 ​

功能描述 ​

参考文档 ​

函数列表 ​

函数详细内容 ​

创建员工 ​

更新员工信息 ​

离职员工 ​

恢复已离职员工 ​

在职员工流转到待离职 ​

待离职员工取消离职 ​

批量查询员工详情 ​

分页获取员工列表 ​

搜索员工信息 ​

接口名称

功能描述

参考文档

函数列表

函数详细内容

创建员工

更新员工信息

离职员工

恢复已离职员工

在职员工流转到待离职

待离职员工取消离职

批量查询员工详情

分页获取员工列表

搜索员工信息