Mud Tools

Appearance

接口名称 ​

用户管理API（租户令牌）- IFeishuTenantV3User

功能描述 ​

飞书用户是飞书通讯录中的基础资源，对应企业组织架构中的成员实体。当前接口使用租户令牌访问，适用于租户应用场景，提供完整的用户管理功能，包括用户创建、更新、查询、删除、恢复等操作。

参考文档 ​

https://open.feishu.cn/document/server-docs/contact-v3/user/field-overview

函数列表 ​

函数名称功能描述认证方式HTTP 方法
CreateUserAsync创建新用户（员工入职）租户令牌POST
UpdateUserIdAsync更新用户ID租户令牌PATCH
GetBatchUsersAsync通过手机号或邮箱批量获取用户ID租户令牌POST
GetUsersByKeywordAsync通过关键词搜索用户信息租户令牌GET
DeleteUserByIdAsync删除指定用户（员工离职）租户令牌DELETE
ResurrectUserByIdAsync恢复已删除用户租户令牌POST
LogoutAsync退出用户登录态租户令牌POST
GetJsTicketAsync获取JSAPI临时调用凭证租户令牌POST
UpdateUserAsync更新用户信息租户令牌PATCH
GetUserInfoByIdAsync获取指定用户信息租户令牌GET
GetUserByIdsAsync批量获取用户信息租户令牌GET
GetUserByDepartmentIdAsync获取指定部门直属用户列表租户令牌GET

函数详细内容 ​

函数名称：创建用户 ​

函数签名：

csharp
Task<FeishuApiResult<CreateOrUpdateUserResult>?> CreateUserAsync(
    [Body] CreateUserRequest userModel,
    [Query("user_id_type")] string? user_id_type = "open_id",
    [Query("department_id_type")] string? department_id_type = "open_department_id",
    [Query("client_token")] string? client_token = null,
    CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名类型必填说明
userModelCreateUserRequest✅ 必填创建用户的请求体
user_id_typestring⚪ 可选用户ID类型，默认为"open_id"
department_id_typestring⚪ 可选部门ID类型，默认为"open_department_id"
client_tokenstring⚪ 可选幂等判断令牌，避免重复创建

响应：

json
{
  "code": 0,
  "msg": "success",
  "data": {
    "user": {
      "user_id": "ou_1234567890",
      "open_id": "ou_1234567890",
      "name": "张三",
      "email": "zhangsan@example.com",
      "mobile": "13800138000",
      "department_ids": ["od-1234567890"]
    }
  }
}

说明：

  • 创建成功后系统会自动向用户发送邀请短信或邮件
  • 用户需同意邀请后方可访问企业或团队
  • client_token用于防止重复创建，建议使用UUID
  • 邮箱和手机号至少需要提供一个

代码示例：

javascript
const createUserRequest = {
  name: { zh_cn: "张三", en_us: "Zhang San" },
  email: "zhangsan@example.com",
  mobile: "13800138000",
  department_ids: ["od-1234567890"],
  leader_user_id: "ou_1234567891",
  gender: 1, // 1:男 2:女 0:保密
  mobile_visible: true,
  city: "北京"
};

const result = await feishuTenantV3User.createUserAsync(
  createUserRequest,
  "open_id",
  "open_department_id",
  "uuid-" + Date.now()
);

if (result.code === 0) {
  console.log("用户创建成功:", result.data.user.name);
} else {
  console.error("创建失败:", result.msg);
}

函数名称：更新用户ID ​

函数签名：

csharp
Task<FeishuNullDataApiResult?> UpdateUserIdAsync(
    [Path] string user_id,
    [Body] UpdateUserIdRequest updateUserId,
    [Query("user_id_type")] string? user_id_type = "open_id",
    CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名类型必填说明
user_idstring✅ 必填用户ID
updateUserIdUpdateUserIdRequest✅ 必填更新用户ID的请求体
user_id_typestring⚪ 可选用户ID类型，默认为"open_id"

响应：

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

说明：

  • 自定义用户ID长度不能超过64字符
  • 新的user_id需要符合飞书ID命名规范
  • 更新后旧的user_id将不再有效

代码示例：

javascript
const updateRequest = {
  user_id: "custom_user_001"
};

const result = await feishuTenantV3User.updateUserIdAsync(
  "ou_1234567890",
  updateRequest,
  "open_id"
);

if (result.code === 0) {
  console.log("用户ID更新成功");
} else {
  console.error("更新失败:", result.msg);
}

函数名称：批量获取用户ID ​

函数签名：

csharp
Task<FeishuApiResult<UserQueryListResult>?> GetBatchUsersAsync(
    [Body] UserQueryRequest queryRequest,
    [Query("user_id_type")] string? user_id_type = "open_id",
    CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名类型必填说明
queryRequestUserQueryRequest✅ 必填查询参数请求体
user_id_typestring⚪ 可选用户ID类型，默认为"open_id"

响应：

json
{
  "code": 0,
  "msg": "success",
  "data": {
    "user_list": [
      {
        "user_id": "ou_1234567890",
        "open_id": "ou_1234567890",
        "union_id": "on_1234567890",
        "name": "张三",
        "status": {
          "is_activated": true,
          "is_exited": false
        }
      }
    ]
  }
}

说明：

  • 通过手机号或邮箱获取用户的多个ID标识
  • 返回user_id、open_id、union_id三种ID
  • 包含用户状态信息

代码示例：

javascript
const queryRequest = {
  emails: ["zhangsan@example.com", "lisi@example.com"],
  mobiles: ["13800138000", "13900139000"]
};

const result = await feishuTenantV3User.getBatchUsersAsync(
  queryRequest,
  "open_id"
);

if (result.code === 0) {
  result.data.user_list.forEach(user => {
    console.log(`用户: ${user.name}, 状态: ${user.status.is_activated ? '已激活' : '未激活'}`);
  });
}

函数名称：关键词搜索用户 ​

函数签名：

csharp
Task<FeishuApiResult<UserSearchListResult>?> GetUsersByKeywordAsync(
    [Query("query")] string query,
    [Query("page_size")] int page_size = 10,
    [Query("page_token")] string? page_token = null,
    CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名类型必填说明
querystring✅ 必填搜索关键词
page_sizeint⚪ 可选分页大小，默认10，最大50
page_tokenstring⚪ 可选分页标记，首次请求不填

响应：

json
{
  "code": 0,
  "msg": "success",
  "data": {
    "user_list": [
      {
        "user_id": "ou_1234567890",
        "name": "张三",
        "avatar": {
          "avatar_72": "https://example.com/avatar.jpg"
        },
        "department_ids": ["od-1234567890"]
      }
    ],
    "page_token": "next_page_token",
    "has_more": true
  }
}

说明：

  • 通过用户名关键词进行模糊搜索
  • 返回用户头像、姓名、部门等基本信息
  • 支持分页查询

代码示例：

javascript
async function searchUsers(keyword, pageSize = 10) {
  let hasMore = true;
  let pageToken = null;
  const allUsers = [];

  while (hasMore) {
    const result = await feishuTenantV3User.getUsersByKeywordAsync(
      keyword,
      pageSize,
      pageToken
    );

    if (result.code === 0) {
      allUsers.push(...result.data.user_list);
      hasMore = result.data.has_more;
      pageToken = result.data.page_token;
    } else {
      break;
    }
  }

  return allUsers;
}

const users = await searchUsers("张");
console.log(`找到 ${users.length} 个用户`);

函数名称：删除用户 ​

函数签名：

csharp
Task<FeishuNullDataApiResult?> DeleteUserByIdAsync(
    [Path] string user_id,
    [Body] DeleteSettingsRequest deleteSettingsRequest,
    [Query("user_id_type")] string? user_id_type = "open_id",
    CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名类型必填说明
user_idstring✅ 必填用户ID
deleteSettingsRequestDeleteSettingsRequest✅ 必填删除设置请求体
user_id_typestring⚪ 可选用户ID类型，默认为"open_id"

响应：

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

说明：

  • 删除操作不可恢复，请谨慎操作
  • 可将用户数据转让给其他用户
  • 用户数据包括群组、文档、日程和应用等

代码示例：

javascript
const deleteRequest = {
  transfer_to_user_id: "ou_1234567891", // 数据接收人
  transfer_types: ["chat", "doc", "calendar", "bitable"] // 转让的数据类型
};

const result = await feishuTenantV3User.deleteUserByIdAsync(
  "ou_1234567890",
  deleteRequest,
  "open_id"
);

if (result.code === 0) {
  console.log("用户删除成功，数据已转让");
} else {
  console.error("删除失败:", result.msg);
}

函数名称：恢复已删除用户 ​

函数签名：

csharp
Task<FeishuNullDataApiResult?> ResurrectUserByIdAsync(
    [Path] string user_id,
    [Body] ResurrectUserRequest resurrectUserRequest,
    [Query("user_id_type")] string? user_id_type = "open_id",
    [Query("department_id_type")] string? department_id_type = "open_department_id",
    CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名类型必填说明
user_idstring✅ 必填用户ID
resurrectUserRequestResurrectUserRequest✅ 必填恢复用户请求体
user_id_typestring⚪ 可选用户ID类型，默认为"open_id"
department_id_typestring⚪ 可选部门ID类型，默认为"open_department_id"

响应：

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

说明：

  • 仅可恢复已删除但未超过恢复期限的用户
  • 恢复时需要重新指定部门信息
  • 恢复后用户可重新访问企业资源

代码示例：

javascript
const resurrectRequest = {
  department_ids: ["od-1234567890"],
  name: { zh_cn: "张三" },
  email: "zhangsan@example.com"
};

const result = await feishuTenantV3User.resurrectUserByIdAsync(
  "ou_1234567890",
  resurrectRequest,
  "open_id",
  "open_department_id"
);

if (result.code === 0) {
  console.log("用户恢复成功");
} else {
  console.error("恢复失败:", result.msg);
}

函数名称：退出登录 ​

函数签名：

csharp
Task<FeishuNullDataApiResult?> LogoutAsync(
    [Body] LogoutRequest logoutRequest,
    [Query("user_id_type")] string user_id_type = "open_id",
    CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名类型必填说明
logoutRequestLogoutRequest✅ 必填退出登录请求体
user_id_typestring⚪ 可选用户ID类型，默认为"open_id"

响应：

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

说明：

  • 退出指定用户的登录态
  • 用户需要重新登录才能访问
  • 适用于安全管理场景

代码示例：

javascript
const logoutRequest = {
  user_ids: ["ou_1234567890", "ou_1234567891"]
};

const result = await feishuTenantV3User.logoutAsync(
  logoutRequest,
  "open_id"
);

if (result.code === 0) {
  console.log("用户退出登录成功");
} else {
  console.error("退出失败:", result.msg);
}

函数名称：获取JSAPI票据 ​

函数签名：

csharp
Task<FeishuApiResult<TicketData>?> GetJsTicketAsync(CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名类型必填说明
无--该函数无需参数

响应：

json
{
  "code": 0,
  "msg": "success",
  "data": {
    "ticket": "ticket_string",
    "expires_in": 7200
  }
}

说明：

  • 获取JSAPI临时调用凭证
  • 使用该凭证调用JSAPI不会被拦截
  • 票据有效期为2小时

代码示例：

javascript
const result = await feishuTenantV3User.getJsTicketAsync();

if (result.code === 0) {
  const ticket = result.data.ticket;
  console.log("获取JSAPI票据成功:", ticket);
  
  // 在前端使用票据调用JSAPI
  // window.tt.config({ ticket: ticket });
} else {
  console.error("获取票据失败:", result.msg);
}

函数名称：更新用户信息 ​

函数签名：

csharp
Task<FeishuApiResult<CreateOrUpdateUserResult>?> UpdateUserAsync(
    [Path] string user_id,
    [Body] UpdateUserRequest userModel,
    [Query("user_id_type")] string? user_id_type = "open_id",
    [Query("department_id_type")] string? department_id_type = "open_department_id",
    CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名类型必填说明
user_idstring✅ 必填用户ID
userModelUpdateUserRequest✅ 必填更新用户的请求体
user_id_typestring⚪ 可选用户ID类型，默认为"open_id"
department_id_typestring⚪ 可选部门ID类型，默认为"open_department_id"

响应：

json
{
  "code": 0,
  "msg": "success",
  "data": {
    "user": {
      "user_id": "ou_1234567890",
      "name": "张三",
      "email": "zhangsan@example.com",
      "department_ids": ["od-1234567890"]
    }
  }
}

说明：

  • 仅更新显式传入的字段
  • 支持更新姓名、邮箱、手机号、部门等信息
  • 可更新自定义字段

代码示例：

javascript
const updateRequest = {
  name: { zh_cn: "张三（更新）" },
  department_ids: ["od-1234567890", "od-1234567891"],
  mobile: "13800138001",
  leader_user_id: "ou_1234567892"
};

const result = await feishuTenantV3User.updateUserAsync(
  "ou_1234567890",
  updateRequest,
  "open_id",
  "open_department_id"
);

if (result.code === 0) {
  console.log("用户信息更新成功");
} else {
  console.error("更新失败:", result.msg);
}

函数名称：获取用户信息 ​

函数签名：

csharp
Task<FeishuApiResult<GetUserInfoResult>> GetUserInfoByIdAsync(
    [Path] string user_id,
    [Query("user_id_type")] string? user_id_type = "open_id",
    [Query("department_id_type")] string? department_id_type = "open_department_id",
    CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名类型必填说明
user_idstring✅ 必填用户ID
user_id_typestring⚪ 可选用户ID类型，默认为"open_id"
department_id_typestring⚪ 可选部门ID类型，默认为"open_department_id"

响应：

json
{
  "code": 0,
  "msg": "success",
  "data": {
    "user": {
      "user_id": "ou_1234567890",
      "open_id": "ou_1234567890",
      "union_id": "on_1234567890",
      "name": "张三",
      "email": "zhangsan@example.com",
      "mobile": "13800138000",
      "avatar": {
        "avatar_72": "https://example.com/avatar.jpg"
      },
      "status": {
        "is_activated": true,
        "is_exited": false
      }
    }
  }
}

说明：

  • 获取用户的详细信息
  • 包含用户ID、姓名、联系方式、头像等
  • 返回用户激活状态

代码示例：

javascript
const result = await feishuTenantV3User.getUserInfoByIdAsync(
  "ou_1234567890",
  "open_id",
  "open_department_id"
);

if (result.code === 0) {
  const user = result.data.user;
  console.log(`用户姓名: ${user.name.zh_cn}`);
  console.log(`邮箱: ${user.email}`);
  console.log(`状态: ${user.status.is_activated ? '已激活' : '未激活'}`);
} else {
  console.error("获取用户信息失败:", result.msg);
}

函数名称：批量获取用户信息 ​

函数签名：

csharp
Task<FeishuApiResult<GetUserInfosResult>?> GetUserByIdsAsync(
   [Query("user_ids")] string[] user_ids,
   [Query("user_id_type")] string? user_id_type = "open_id",
   [Query("department_id_type")] string? department_id_type = "open_department_id",
   CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名类型必填说明
user_idsstring[]✅ 必填用户ID数组
user_id_typestring⚪ 可选用户ID类型，默认为"open_id"
department_id_typestring⚪ 可选部门ID类型，默认为"open_department_id"

响应：

json
{
  "code": 0,
  "msg": "success",
  "data": {
    "user_list": [
      {
        "user_id": "ou_1234567890",
        "name": "张三",
        "department_ids": ["od-1234567890"]
      }
    ]
  }
}

说明：

  • 支持一次查询多个用户信息
  • 最多支持50个用户ID
  • 返回用户的基本信息

代码示例：

javascript
const userIds = ["ou_1234567890", "ou_1234567891", "ou_1234567892"];

const result = await feishuTenantV3User.getUserByIdsAsync(
  userIds,
  "open_id",
  "open_department_id"
);

if (result.code === 0) {
  result.data.user_list.forEach(user => {
    console.log(`用户: ${user.name.zh_cn}, 部门数: ${user.department_ids.length}`);
  });
} else {
  console.error("批量获取失败:", result.msg);
}

函数名称：获取部门用户列表 ​

函数签名：

csharp
Task<FeishuApiResult<GetUserInfosResult>?> GetUserByDepartmentIdAsync(
    [Query("department_id")] string department_id,
    [Query("page_size")] int page_size = 10,
    [Query("page_token")] string? page_token = null,
    [Query("user_id_type")] string? user_id_type = "open_id",
    [Query("department_id_type")] string? department_id_type = "open_department_id",
    CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名类型必填说明
department_idstring✅ 必填部门ID
page_sizeint⚪ 可选分页大小，默认10，最大50
page_tokenstring⚪ 可选分页标记，首次请求不填
user_id_typestring⚪ 可选用户ID类型，默认为"open_id"
department_id_typestring⚪ 可选部门ID类型，默认为"open_department_id"

响应：

json
{
  "code": 0,
  "msg": "success",
  "data": {
    "user_list": [
      {
        "user_id": "ou_1234567890",
        "name": "张三",
        "department_ids": ["od-1234567890"]
      }
    ],
    "page_token": "next_page_token",
    "has_more": true
  }
}

说明：

  • 获取指定部门直属的用户列表
  • 支持分页查询
  • 仅返回直属用户，不包含子部门用户

代码示例：

javascript
async function getDepartmentUsers(deptId, pageSize = 50) {
  let hasMore = true;
  let pageToken = null;
  const allUsers = [];

  while (hasMore) {
    const result = await feishuTenantV3User.getUserByDepartmentIdAsync(
      deptId,
      pageSize,
      pageToken,
      "open_id",
      "open_department_id"
    );

    if (result.code === 0) {
      allUsers.push(...result.data.user_list);
      hasMore = result.data.has_more;
      pageToken = result.data.page_token;
    } else {
      break;
    }
  }

  return allUsers;
}

const users = await getDepartmentUsers("od-1234567890");
console.log(`部门共有 ${users.length} 个直属员工`);