Mud Tools

接口名称

人员类型管理API（租户令牌）- IFeishuTenantV3EmployeeType

功能描述

飞书人员类型是通讯录中一种特殊的用户属性字段，用于标记用户的身份类型。当前接口使用租户令牌访问，适用于租户应用场景。使用通讯录API，可以对人员类型资源进行增删改查操作。人员类型可以灵活标记用户的身份，如正式员工、实习生、外包人员、顾问等。

参考文档

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

函数列表

函数名称	功能描述	认证方式	HTTP 方法
CreateEmployeeTypeAsync	创建人员类型	租户令牌	POST
UpdateEmployeeTypeAsync	更新人员类型信息	租户令牌	PUT
GetEmployeeTypesAsync	获取人员类型列表	租户令牌	GET
DeleteEmployeeTypeByIdAsync	删除指定人员类型	租户令牌	DELETE

函数详细内容

函数名称：创建人员类型

函数签名：

csharp

Task<FeishuApiResult<EmployeeTypeEnumResult>?> CreateEmployeeTypeAsync(
    [Body] EmployeeTypeEnumRequest groupInfoRequest,
    CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名	类型	必填	说明
groupInfoRequest	EmployeeTypeEnumRequest	✅ 必填	人员类型创建请求体

响应：

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "enum": {
      "enum_id": "enum_1234567890",
      "content": "远程办公人员",
      "enum_type": 2,
      "enum_status": 1,
      "i18n_content": [
        {
          "locale": "zh_cn",
          "text": "远程办公人员"
        },
        {
          "locale": "en_us",
          "text": "Remote Worker"
        }
      ]
    }
  }
}

说明：

新增一个自定义的人员类型，用于标记用户的身份类型
enum_type固定取值为2，表示自定义类型
enum_status为1表示激活状态，为2表示未激活状态
支持多语言配置，适应国际化需求
系统内置的正式、实习、外包、劳务、顾问五个选项不支持重新创建

代码示例：

javascript

// 创建新的远程办公人员类型
const createEmployeeTypeRequest = {
  content: "远程办公人员",
  enum_type: 2, // 固定为2，表示自定义类型
  enum_status: 1, // 1:激活 2:未激活
  i18n_content: [
    {
      locale: "zh_cn",
      text: "远程办公人员"
    },
    {
      locale: "en_us",
      text: "Remote Worker"
    },
    {
      locale: "ja_jp",
      text: "リモートワーカー"
    }
  ]
};

const result = await feishuTenantV3EmployeeType.createEmployeeTypeAsync(createEmployeeTypeRequest);

if (result.code === 0) {
  const employeeEnum = result.data.enum;
  console.log("人员类型创建成功:");
  console.log(`- 类型ID: ${employeeEnum.enum_id}`);
  console.log(`- 类型名称: ${employeeEnum.content}`);
  console.log(`- 类型状态: ${employeeEnum.enum_status === 1 ? '激活' : '未激活'}`);
  console.log(`- 类型分类: ${employeeEnum.enum_type === 2 ? '自定义类型' : '内置类型'}`);
  
  // 显示多语言配置
  if (employeeEnum.i18n_content && employeeEnum.i18n_content.length > 0) {
    console.log("\n多语言配置:");
    employeeEnum.i18n_content.forEach(item => {
      console.log(`  ${item.locale}: ${item.text}`);
    });
  }
  
  // 存储类型ID供后续使用
  const newEnumId = employeeEnum.enum_id;
  console.log(`\n新创建的人员类型ID: ${newEnumId}，可用于用户管理`);
} else {
  console.error("创建人员类型失败:", result.msg);
  
  // 错误处理
  switch (result.code) {
    case 400:
      console.log("请求参数错误，可能类型名称重复或格式不正确");
      break;
    case 403:
      console.log("权限不足，无法创建人员类型");
      break;
    case 409:
      console.log("类型已存在，请使用不同的名称");
      break;
    default:
      console.log("创建失败，请稍后重试");
  }
}

函数名称：更新人员类型信息

函数签名：

csharp

Task<FeishuApiResult<EmployeeTypeEnumResult>?> UpdateEmployeeTypeAsync(
    [Path] string enum_id,
    [Body] EmployeeTypeEnumRequest groupInfoRequest,
    CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名	类型	必填	说明
enum_id	string	✅ 必填	人员类型的选项ID
groupInfoRequest	EmployeeTypeEnumRequest	✅ 必填	人员类型更新请求体

响应：

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "enum": {
      "enum_id": "enum_1234567890",
      "content": "混合办公人员",
      "enum_type": 2,
      "enum_status": 1,
      "i18n_content": [
        {
          "locale": "zh_cn",
          "text": "混合办公人员"
        },
        {
          "locale": "en_us",
          "text": "Hybrid Worker"
        }
      ]
    }
  }
}

说明：

更新指定的自定义人员类型信息
enum_id可以通过创建接口返回值获取，也可以通过查询接口获取
只能更新自定义类型，系统内置类型不允许修改
更新后的类型信息会立即生效，影响相关用户的属性显示

代码示例：

javascript

// 更新人员类型，修改名称和多语言配置
const updateEmployeeTypeRequest = {
  content: "混合办公人员",
  enum_type: 2, // 保持为自定义类型
  enum_status: 1, // 保持激活状态
  i18n_content: [
    {
      locale: "zh_cn",
      text: "混合办公人员"
    },
    {
      locale: "en_us",
      text: "Hybrid Worker"
    },
    {
      locale: "ja_jp",
      text: "ハイブリッドワーカー"
    }
  ]
};

const result = await feishuTenantV3EmployeeType.updateEmployeeTypeAsync(
  "enum_1234567890", // 要更新的人员类型ID
  updateEmployeeTypeRequest
);

if (result.code === 0) {
  const employeeEnum = result.data.enum;
  console.log("人员类型更新成功:");
  console.log(`- 类型ID: ${employeeEnum.enum_id}`);
  console.log(`- 新名称: ${employeeEnum.content}`);
  console.log(`- 状态: ${employeeEnum.enum_status === 1 ? '激活' : '未激活'}`);
  
  // 显示更新后的多语言配置
  if (employeeEnum.i18n_content && employeeEnum.i18n_content.length > 0) {
    console.log("\n更新后的多语言配置:");
    employeeEnum.i18n_content.forEach(item => {
      console.log(`  ${item.locale}: ${item.text}`);
    });
  }
  
  console.log("✓ 类型信息已更新，相关用户的属性显示将同步更新");
} else {
  console.error("更新人员类型失败:", result.msg);
  
  // 错误处理
  switch (result.code) {
    case 400:
      console.log("请求参数错误，可能是类型名称重复或格式不正确");
      break;
    case 403:
      console.log("权限不足，无法更新人员类型");
      break;
    case 404:
      console.log("人员类型不存在或已被删除");
      break;
    case 409:
      console.log("尝试更新内置类型或名称冲突");
      break;
    default:
      console.log("更新失败，请稍后重试");
  }
}

// 临时禁用人员类型（不删除，只是停用）
async function temporarilyDisableEmployeeType(enumId) {
  console.log(`准备临时禁用人员类型 ${enumId}...`);
  
  const disableRequest = {
    content: "（已禁用）类型名称", // 保留原内容供参考
    enum_type: 2,
    enum_status: 2, // 设置为未激活状态
    i18n_content: [
      {
        locale: "zh_cn",
        text: "（已禁用）类型名称"
      }
    ]
  };
  
  const result = await feishuTenantV3EmployeeType.updateEmployeeTypeAsync(enumId, disableRequest);
  
  if (result.code === 0) {
    console.log("✓ 人员类型已临时禁用");
    console.log("类型不再可用于新用户配置，但现有用户的属性保持不变");
  } else {
    console.error("禁用人员类型失败:", result.msg);
  }
}

函数名称：获取人员类型列表

函数签名：

csharp

Task<FeishuApiPageListResult<EmployeeTypeEnum>?> GetEmployeeTypesAsync(
    [Query("page_size")] int? page_size = 10,
    [Query("page_token")] string? page_token = null,
    CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名	类型	必填	说明
page_size	int?	⚪ 可选	分页大小，默认10，最大50
page_token	string	⚪ 可选	分页标记，首次请求不填

响应：

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "items": [
      {
        "enum_id": "enum_1001",
        "content": "正式",
        "enum_type": 1,
        "enum_status": 1
      },
      {
        "enum_id": "enum_1002", 
        "content": "实习",
        "enum_type": 1,
        "enum_status": 1
      },
      {
        "enum_id": "enum_1234567890",
        "content": "远程办公人员",
        "enum_type": 2,
        "enum_status": 1
      }
    ],
    "page_token": "next_page_token",
    "has_more": false
  }
}

说明：

查询当前租户下所有的人员类型信息
包括系统内置类型和自定义类型
返回选项ID、类型、编号以及内容等基本信息
支持分页查询，适合获取大量人员类型

代码示例：

javascript

// 获取所有人员类型
async function getAllEmployeeTypes() {
  let hasMore = true;
  let pageToken = null;
  const allTypes = [];
  let pageCount = 0;

  while (hasMore) {
    pageCount++;
    console.log(`正在获取第 ${pageCount} 页人员类型数据...`);
    
    const result = await feishuTenantV3EmployeeType.getEmployeeTypesAsync(
      50, // 每页获取更多数据
      pageToken
    );

    if (result.code === 0) {
      const types = result.data.items;
      allTypes.push(...types);
      hasMore = result.data.has_more;
      pageToken = result.data.page_token;
      
      console.log(`第 ${pageCount} 页获取到 ${types.length} 个人员类型`);
    } else {
      console.error(`第 ${pageCount} 页获取失败:`, result.msg);
      break;
    }
  }

  return allTypes;
}

// 分析人员类型结构
async function analyzeEmployeeTypes() {
  console.log("正在分析人员类型结构...");
  
  const types = await getAllEmployeeTypes();
  
  if (types.length === 0) {
    console.log("未找到任何人员类型");
    return;
  }

  console.log(`\n=== 人员类型概览 ===`);
  console.log(`总类型数: ${types.length}`);
  
  // 按类型分类统计
  const builtinTypes = types.filter(t => t.enum_type === 1);
  const customTypes = types.filter(t => t.enum_type === 2);
  
  console.log(`内置类型: ${builtinTypes.length}`);
  console.log(`自定义类型: ${customTypes.length}`);
  
  // 按状态分类统计
  const activeTypes = types.filter(t => t.enum_status === 1);
  const inactiveTypes = types.filter(t => t.enum_status === 2);
  
  console.log(`激活类型: ${activeTypes.length}`);
  console.log(`未激活类型: ${inactiveTypes.length}`);
  
  // 显示所有类型
  console.log(`\n=== 人员类型详细列表 ===`);
  
  console.log("\n【内置类型】（系统预置，不可删除）:");
  builtinTypes.forEach(type => {
    const status = type.enum_status === 1 ? '✓ 激活' : '✗ 未激活';
    console.log(`├─ ${type.content} (${type.enum_id}) [${status}]`);
  });
  
  if (customTypes.length > 0) {
    console.log("\n【自定义类型】（用户创建，可管理）:");
    customTypes.forEach(type => {
      const status = type.enum_status === 1 ? '✓ 激活' : '✗ 未激活';
      console.log(`├─ ${type.content} (${type.enum_id}) [${status}]`);
    });
  }
  
  // 统计分析
  console.log(`\n=== 使用建议 ===`);
  
  if (customTypes.length === 0) {
    console.log("📝 建议：当前没有自定义人员类型，可以根据企业需要创建专门的类型");
    console.log("   例如：远程办公人员、兼职人员、合作伙伴等");
  } else {
    const activeCustomTypes = customTypes.filter(t => t.enum_status === 1);
    console.log(`📊 当前有 ${activeCustomTypes.length} 个激活的自定义类型可用`);
  }
  
  if (inactiveTypes.length > 0) {
    console.log(`⚠️  注意：有 ${inactiveTypes.length} 个未激活的类型，考虑是否需要激活或删除`);
  }
  
  return types;
}

// 查找特定的人员类型
async function findEmployeeType(searchText) {
  console.log(`正在搜索包含 "${searchText}" 的人员类型...`);
  
  const types = await getAllEmployeeTypes();
  
  const matchedTypes = types.filter(type => 
    type.content.toLowerCase().includes(searchText.toLowerCase())
  );
  
  if (matchedTypes.length === 0) {
    console.log(`未找到包含 "${searchText}" 的人员类型`);
    return [];
  }
  
  console.log(`\n找到 ${matchedTypes.length} 个匹配的人员类型:`);
  matchedTypes.forEach((type, index) => {
    const typeCategory = type.enum_type === 1 ? "内置" : "自定义";
    const status = type.enum_status === 1 ? "激活" : "未激活";
    const editable = type.enum_type === 2 ? "可编辑" : "只读";
    
    console.log(`${index + 1}. ${type.content}`);
    console.log(`   ID: ${type.enum_id}`);
    console.log(`   类型: ${typeCategory} | 状态: ${status} | 权限: ${editable}`);
  });
  
  return matchedTypes;
}

// 检查类型是否存在
async function checkEmployeeTypeExists(content) {
  const types = await getAllEmployeeTypes();
  const exists = types.some(type => type.content === content);
  
  if (exists) {
    console.log(`人员类型 "${content}" 已存在`);
    const existingType = types.find(type => type.content === content);
    console.log(`ID: ${existingType.enum_id}`);
    console.log(`类型: ${existingType.enum_type === 1 ? '内置' : '自定义'}`);
    console.log(`状态: ${existingType.enum_status === 1 ? '激活' : '未激活'}`);
  } else {
    console.log(`人员类型 "${content}" 不存在，可以创建`);
  }
  
  return exists;
}

// 使用示例
analyzeEmployeeTypes();
findEmployeeType("实习");
checkEmployeeTypeExists("远程办公人员");

函数名称：删除指定人员类型

函数签名：

csharp

Task<FeishuNullDataApiResult?> DeleteEmployeeTypeByIdAsync(
    [Path] string enum_id,
    CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名	类型	必填	说明
enum_id	string	✅ 必填	自定义人员类型的选项ID

响应：

json

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

说明：

删除指定的自定义人员类型
仅支持删除自定义的人员类型（enum_type = 2）
默认包含的正式、实习、外包、劳务、顾问五个内置选项不支持删除
删除前请确认没有用户正在使用该人员类型
删除操作不可恢复，请谨慎操作

代码示例：

javascript

// 安全删除人员类型（包含前置检查）
async function safeDeleteEmployeeType(enumId) {
  console.log(`准备删除人员类型 ${enumId}...`);
  
  // 第一步：获取人员类型信息
  const types = await getAllEmployeeTypes();
  const targetTypes = types.filter(t => t.enum_id === enumId);
  
  if (targetTypes.length === 0) {
    console.log("错误：人员类型不存在");
    return false;
  }
  
  const targetType = targetTypes[0];
  console.log(`类型名称: ${targetType.content}`);
  console.log(`类型分类: ${targetType.enum_type === 1 ? '内置类型' : '自定义类型'}`);
  console.log(`类型状态: ${targetType.enum_status === 1 ? '激活' : '未激活'}`);
  
  // 第二步：检查是否为内置类型
  if (targetType.enum_type === 1) {
    console.log("删除失败：内置类型不支持删除");
    console.log("受保护的内置类型：正式、实习、外包、劳务、顾问");
    return false;
  }
  
  // 第三步：确认删除信息
  console.log("删除确认:");
  console.log(`- 类型名称: ${targetType.content}`);
  console.log(`- 类型ID: ${targetType.enum_id}`);
  console.log(`- 类型分类: 自定义类型 ✓`);
  console.log(`- 可删除: ✓`);
  
  // 第四步：检查使用情况（模拟检查，实际需要查询用户使用情况）
  console.log("⚠️  重要提醒：删除前请确认没有用户正在使用此人员类型");
  console.log("如果已有用户使用此类型，建议先修改用户的类型，再删除此类型定义");
  
  // 第五步：执行删除
  console.log("正在执行删除操作...");
  
  const deleteResult = await feishuTenantV3EmployeeType.deleteEmployeeTypeByIdAsync(enumId);
  
  if (deleteResult.code === 0) {
    console.log("✓ 人员类型删除成功");
    console.log(`已删除类型: ${targetType.content} (${enumId})`);
    
    // 验证删除结果
    const verifyTypes = await getAllEmployeeTypes();
    const stillExists = verifyTypes.some(t => t.enum_id === enumId);
    
    if (!stillExists) {
      console.log("✓ 验证成功：类型已不存在");
    } else {
      console.log("⚠ 警告：删除成功但验证异常");
    }
    
    return true;
  } else {
    console.error("删除人员类型失败:", deleteResult.msg);
    
    // 错误处理
    switch (deleteResult.code) {
      case 400:
        console.log("请求参数错误，可能是类型ID不正确");
        break;
      case 403:
        console.log("权限不足，无法删除人员类型");
        break;
      case 404:
        console.log("人员类型不存在或已被删除");
        break;
      case 409:
        console.log("类型正在被使用或有依赖关系，无法删除");
        break;
      default:
        console.log("未知错误，请稍后重试");
    }
    
    return false;
  }
}

// 批量清理未使用的自定义人员类型
async function cleanupUnusedCustomTypes() {
  console.log("开始清理未使用的自定义人员类型...");
  
  const types = await getAllEmployeeTypes();
  const customTypes = types.filter(t => t.enum_type === 2);
  
  if (customTypes.length === 0) {
    console.log("没有找到自定义人员类型");
    return;
  }
  
  console.log(`找到 ${customTypes.length} 个自定义人员类型:`);
  customTypes.forEach(type => {
    const status = type.enum_status === 1 ? '激活' : '未激活';
    console.log(`- ${type.content} (${type.enum_id}) [${status}]`);
  });
  
  // 显示未激活的自定义类型
  const inactiveCustomTypes = customTypes.filter(t => t.enum_status === 2);
  
  if (inactiveCustomTypes.length > 0) {
    console.log(`\n发现 ${inactiveCustomTypes.length} 个未激活的自定义类型，建议删除:`);
    
    for (const inactiveType of inactiveCustomTypes) {
      console.log(`\n正在处理未激活类型: ${inactiveType.content}`);
      console.log(`ID: ${inactiveType.enum_id}`);
      
      // 确认删除
      const success = await safeDeleteEmployeeType(inactiveType.enum_id);
      if (success) {
        console.log(`✓ 已删除: ${inactiveType.content}`);
      } else {
        console.log(`✗ 删除失败: ${inactiveType.content}`);
      }
    }
  } else {
    console.log("没有未激活的自定义类型");
  }
  
  console.log("\n清理完成");
}

// 删除测试类型（演示用）
async function deleteTestTypes() {
  console.log("查找并删除测试用的人员类型...");
  
  const types = await getAllEmployeeTypes();
  const testTypes = types.filter(t => 
    t.enum_type === 2 && // 自定义类型
    (t.content.includes('测试') || t.content.includes('test') || t.content.includes('Test'))
  );
  
  if (testTypes.length === 0) {
    console.log("没有找到测试用的人员类型");
    return;
  }
  
  console.log(`找到 ${testTypes.length} 个测试类型:`);
  testTypes.forEach(type => {
    console.log(`- ${type.content} (${type.enum_id})`);
  });
  
  // 删除所有测试类型
  for (const testType of testTypes) {
    console.log(`\n正在删除测试类型: ${testType.content}`);
    await safeDeleteEmployeeType(testType.enum_id);
  }
  
  console.log("\n测试类型清理完成");
}

// 使用示例
// safeDeleteEmployeeType("enum_1234567890");
// cleanupUnusedCustomTypes();
// deleteTestTypes();

部门管理

员工管理

用户管理

用户组管理

职位管理

角色管理

工作城市管理

接口名称

功能描述

参考文档

函数列表

函数详细内容

函数名称：创建人员类型

函数名称：更新人员类型信息

函数名称：获取人员类型列表

函数名称：删除指定人员类型

接口名称 ​

功能描述 ​

参考文档 ​

函数列表 ​

函数详细内容 ​

函数名称：创建人员类型 ​

函数名称：更新人员类型信息 ​

函数名称：获取人员类型列表 ​

函数名称：删除指定人员类型 ​

接口名称

功能描述

参考文档

函数列表

函数详细内容

函数名称：创建人员类型

函数名称：更新人员类型信息

函数名称：获取人员类型列表

函数名称：删除指定人员类型