Mud Tools

接口名称

单位管理 - (FeishuTenantV3Unit)

功能描述

通讯录的单位用于代表企业中的"子公司"、"分支机构"这类组织实体。例如，你的企业下存在负责不同业务的两家子公司，那么你可以在同一个租户内，为两家子公司分别创建对应的单位资源。目前单位资源的主要作用是在部分用户权限上实现"子公司"级别的权限隔离。当前接口使用租户令牌访问，适应于租户应用场景。

参考文档

飞书官方API文档

函数列表

函数名称	功能描述	认证方式	HTTP 方法
CreateUnitAsync	创建单位	租户令牌	POST
UpdateUnitAsync	更新单位名称	租户令牌	PATCH
BindDepartmentAsync	建立部门与单位的绑定关系	租户令牌	POST
UnBindDepartmentAsync	解除部门与单位的绑定关系	租户令牌	POST
GetDepartmentListAsync	获取单位绑定的部门列表	租户令牌	GET
GetUnitInfoAsync	获取指定单位的信息	租户令牌	GET
GetUnitListAsync	获取当前租户内的单位列表	租户令牌	GET
DeleteUnitByIdAsync	删除指定单位	租户令牌	DELETE

函数详细内容

创建单位

函数签名

csharp

Task<FeishuApiResult<UnitCreateResult>?> CreateUnitAsync(
  [Body] UnitInfoRequest groupInfoRequest,
  CancellationToken cancellationToken = default);

认证租户令牌

参数

参数名	类型	必填	说明	示例值
groupInfoRequest	UnitInfoRequest	✅	单位信息请求体	-

请求体参数 (UnitInfoRequest)

参数名	类型	必填	说明	示例值
unit_id	string	⚪	自定义单位ID，租户内唯一，创建后不可修改	"BU121"
name	string	✅	单位名字	"消费者事业部"
unit_type	string	✅	自定义单位类型，创建后不可修改	"子公司"

响应

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "unit_id": "6991111111111111111"
  }
}

错误码

错误码	错误信息	说明
99991400	unit already exist	单位已存在
99991401	invalid unit name	无效的单位名称
99991402	invalid unit type	无效的单位类型

说明

在租户内，传入的name和unit_type不允许同时重复
自定义单位ID在企业内必须唯一
单位创建后，单位类型不可修改

代码示例

typescript

import { FeishuTenantV3Unit } from 'mud-feishu';

const unitApi = new FeishuTenantV3Unit();

// 创建单位
const result = await unitApi.createUnit({
  unit_id: "BU121",
  name: "消费者事业部",
  unit_type: "子公司"
});

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

更新单位名称

函数签名

csharp

Task<FeishuNullDataApiResult?> UpdateUnitAsync(
     [Path] string unit_id,
     [Body] UnitNameUpdateRequest nameUpdateRequest,
     CancellationToken cancellationToken = default);

认证租户令牌

参数

参数名	类型	必填	说明	示例值
unit_id	string	✅	单位ID	"6991111111111111111"
nameUpdateRequest	UnitNameUpdateRequest	✅	单位名称更新请求体	-

请求体参数 (UnitNameUpdateRequest)

参数名	类型	必填	说明	示例值
name	string	✅	单位名字	"消费者事业部"

响应

json

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

错误码

错误码	错误信息	说明
99991400	unit not found	单位不存在
99991401	invalid unit name	无效的单位名称

说明

只能更新单位名称，不能更新单位类型

代码示例

typescript

import { FeishuTenantV3Unit } from 'mud-feishu';

const unitApi = new FeishuTenantV3Unit();

// 更新单位名称
const result = await unitApi.updateUnit(
  "6991111111111111111", // 单位ID
  {
    name: "消费者事业部" // 新的单位名称
  }
);

if (result.code === 0) {
  console.log("单位名称更新成功");
} else {
  console.error(`单位名称更新失败: ${result.msg}`);
}

建立部门与单位的绑定关系

函数签名

csharp

Task<FeishuApiResult<UnitCreateResult>?> BindDepartmentAsync(
      [Body] UnitBindDepartmentRequest unitBindDepartment,
      CancellationToken cancellationToken = default);

认证租户令牌

参数

参数名	类型	必填	说明	示例值
unitBindDepartment	UnitBindDepartmentRequest	✅	部门与单位的绑定关系请求体	-

请求体参数 (UnitBindDepartmentRequest)

参数名	类型	必填	说明	示例值
unit_id	string	✅	单位ID	"6991111111111111111"
department_id	string	✅	单位关联的部门ID，ID类型与department_id_type的取值保持一致	"od-4e6789c92a3c8e02dbe89d3f9b87c"
department_id_type	string	⚪	此次调用中的部门ID类型	"open_department_id"

响应

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "unit_id": "6991111111111111111"
  }
}

错误码

错误码	错误信息	说明
99991400	unit not found	单位不存在
99991403	department not found	部门不存在
99991404	department already bound	部门已绑定其他单位

说明

单个单位可关联的部门数量上限为1,000
同一个部门只能关联一个单位

代码示例

typescript

import { FeishuTenantV3Unit } from 'mud-feishu';

const unitApi = new FeishuTenantV3Unit();

// 绑定部门到单位
const result = await unitApi.bindDepartment({
  unit_id: "6991111111111111111",
  department_id: "od-4e6789c92a3c8e02dbe89d3f9b87c",
  department_id_type: "open_department_id"
});

if (result.code === 0) {
  console.log("部门绑定成功");
} else {
  console.error(`部门绑定失败: ${result.msg}`);
}

解除部门与单位的绑定关系

函数签名

csharp

Task<FeishuApiResult<UnitCreateResult>?> UnBindDepartmentAsync(
      [Body] UnitBindDepartmentRequest unitBindDepartment,
      CancellationToken cancellationToken = default);

认证租户令牌

参数

参数名	类型	必填	说明	示例值
unitBindDepartment	UnitBindDepartmentRequest	✅	部门与单位的绑定关系请求体	-

请求体参数 (UnitBindDepartmentRequest)

参数名	类型	必填	说明	示例值
unit_id	string	✅	单位ID	"6991111111111111111"
department_id	string	✅	单位关联的部门ID，ID类型与department_id_type的取值保持一致	"od-4e6789c92a3c8e02dbe89d3f9b87c"
department_id_type	string	⚪	此次调用中的部门ID类型	"open_department_id"

响应

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "unit_id": "6991111111111111111"
  }
}

错误码

错误码	错误信息	说明
99991400	unit not found	单位不存在
99991403	department not found	部门不存在
99991405	department not bound to unit	部门未绑定到该单位

说明

解除绑定后，部门将不再属于该单位

代码示例

typescript

import { FeishuTenantV3Unit } from 'mud-feishu';

const unitApi = new FeishuTenantV3Unit();

// 解除部门与单位的绑定关系
const result = await unitApi.unBindDepartment({
  unit_id: "6991111111111111111",
  department_id: "od-4e6789c92a3c8e02dbe89d3f9b87c",
  department_id_type: "open_department_id"
});

if (result.code === 0) {
  console.log("部门解绑成功");
} else {
  console.error(`部门解绑失败: ${result.msg}`);
}

获取单位绑定的部门列表

函数签名

csharp

Task<FeishuApiResult<UnitDepartmentListResult>?> GetDepartmentListAsync(
     [Query("unit_id")] string unit_id,
     [Query("page_size")] int? page_size = 10,
     [Query("page_token")] string? page_token = null,
     [Query("department_id_type")] string? department_id_type = Consts.Department_Id_Type,
     CancellationToken cancellationToken = default);

认证租户令牌

参数

参数名	类型	必填	说明	示例值
unit_id	string	✅	单位ID	"6991111111111111111"
page_size	int	⚪	分页大小，即本次请求所返回的用户信息列表内的最大条目数。默认值：10	20
page_token	string	⚪	分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果	"page_token_xxx"
department_id_type	string	⚪	此次调用中使用的部门ID类型	"open_department_id"

响应

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "departmentlist": [
      {
        "unit_id": "6991111111111111111",
        "department_id": "od-4e6789c92a3c8e02dbe89d3f9b87c"
      },
      {
        "unit_id": "6991111111111111111",
        "department_id": "od-5e7899d83b4d9f13ecf9e4g0a98d"
      }
    ],
    "page_token": "page_token_xxx",
    "has_more": true
  }
}

错误码

错误码	错误信息	说明
99991400	unit not found	单位不存在
99991406	invalid page_size	无效的分页大小

说明

page_size最大值为100
返回结果按绑定时间倒序排列

代码示例

typescript

import { FeishuTenantV3Unit } from 'mud-feishu';

const unitApi = new FeishuTenantV3Unit();

// 获取单位绑定的部门列表
let pageToken: string | undefined = undefined;
do {
  const result = await unitApi.getDepartmentList(
    "6991111111111111111", // 单位ID
    20,                      // 每页20条记录
    pageToken,                // 分页标记
    "open_department_id"       // 部门ID类型
  );

  if (result.code === 0) {
    result.data.departmentlist.forEach(item => {
      console.log(`部门ID: ${item.department_id}`);
    });

    pageToken = result.data.has_more ? result.data.page_token : undefined;
  } else {
    console.error(`获取部门列表失败: ${result.msg}`);
    break;
  }
} while (pageToken);

获取指定单位的信息

函数签名

csharp

Task<FeishuApiResult<UnitInfo>?> GetUnitInfoAsync(
    [Path] string unit_id,
    CancellationToken cancellationToken = default);

认证租户令牌

参数

参数名	类型	必填	说明	示例值
unit_id	string	✅	单位ID	"6991111111111111111"

响应

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "unit_id": "6991111111111111111",
    "name": "消费者事业部",
    "unit_type": "子公司"
  }
}

错误码

错误码	错误信息	说明
99991400	unit not found	单位不存在

说明

返回指定单位的详细信息，包括ID、名称和类型

代码示例

typescript

import { FeishuTenantV3Unit } from 'mud-feishu';

const unitApi = new FeishuTenantV3Unit();

// 获取单位信息
const result = await unitApi.getUnitInfo("6991111111111111111");

if (result.code === 0) {
  const unit = result.data;
  console.log(`单位名称: ${unit.name}`);
  console.log(`单位类型: ${unit.unit_type}`);
} else {
  console.error(`获取单位信息失败: ${result.msg}`);
}

获取当前租户内的单位列表

函数签名

csharp

Task<FeishuApiResult<UnitListDataResult>> GetUnitListAsync(
   [Query("page_size")] int? page_size = 10,
   [Query("page_token")] string? page_token = null,
   CancellationToken cancellationToken = default);

认证租户令牌

参数

参数名	类型	必填	说明	示例值
page_size	int	⚪	分页大小，即本次请求所返回的用户信息列表内的最大条目数。默认值：10	20
page_token	string	⚪	分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果	"page_token_xxx"

响应

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "unitlist": [
      {
        "unit_id": "6991111111111111111",
        "name": "消费者事业部",
        "unit_type": "子公司"
      },
      {
        "unit_id": "6991222222222222222",
        "name": "企业服务事业部",
        "unit_type": "分公司"
      }
    ],
    "page_token": "page_token_xxx",
    "has_more": true
  }
}

错误码

错误码	错误信息	说明
99991406	invalid page_size	无效的分页大小

说明

page_size最大值为100
返回结果按创建时间倒序排列

代码示例

typescript

import { FeishuTenantV3Unit } from 'mud-feishu';

const unitApi = new FeishuTenantV3Unit();

// 获取单位列表
let pageToken: string | undefined = undefined;
do {
  const result = await unitApi.getUnitList(
    20,       // 每页20条记录
    pageToken  // 分页标记
  );

  if (result.code === 0) {
    result.data.unitlist.forEach(item => {
      console.log(`单位ID: ${item.unit_id}, 名称: ${item.name}`);
    });

    pageToken = result.data.has_more ? result.data.page_token : undefined;
  } else {
    console.error(`获取单位列表失败: ${result.msg}`);
    break;
  }
} while (pageToken);

删除指定单位

函数签名

csharp

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

认证租户令牌

参数

参数名	类型	必填	说明	示例值
unit_id	string	✅	需删除的单位ID	"6991111111111111111"

响应

json

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

错误码

错误码	错误信息	说明
99991400	unit not found	单位不存在
99991407	cannot delete unit with departments	无法删除有部门的单位

说明

删除单位前需要先解除所有部门的绑定关系
删除单位后，无法恢复

代码示例

typescript

import { FeishuTenantV3Unit } from 'mud-feishu';

const unitApi = new FeishuTenantV3Unit();

// 删除单位
const result = await unitApi.deleteUnitById("6991111111111111111");

if (result.code === 0) {
  console.log("单位删除成功");
} else {
  console.error(`单位删除失败: ${result.msg}`);
}

部门管理

员工管理

用户管理

用户组管理

职位管理

角色管理

工作城市管理

接口名称

功能描述

参考文档

函数列表

函数详细内容

创建单位

更新单位名称

建立部门与单位的绑定关系

解除部门与单位的绑定关系

获取单位绑定的部门列表

获取指定单位的信息

获取当前租户内的单位列表

删除指定单位

接口名称 ​

功能描述 ​

参考文档 ​

函数列表 ​

函数详细内容 ​

创建单位 ​

更新单位名称 ​

建立部门与单位的绑定关系 ​

解除部门与单位的绑定关系 ​

获取单位绑定的部门列表 ​

获取指定单位的信息 ​

获取当前租户内的单位列表 ​

删除指定单位 ​

接口名称

功能描述

参考文档

函数列表

函数详细内容

创建单位

更新单位名称

建立部门与单位的绑定关系

解除部门与单位的绑定关系

获取单位绑定的部门列表

获取指定单位的信息

获取当前租户内的单位列表

删除指定单位