Skill: lentiancn/skill-feishu (version 1.0.0)

# skill-feishu - 飞书相关技能 这个技能包用于处理飞书相关操作，**收集飞书 API 到 open-apis/ 目录**。 ## API 文档格式 API 文档严格遵循 `open-apis/TEMPLATE.md` 模板格式，示例参考 `open-apis/contact-v3-users-find_by_department.md`。 ## 重要规则（必读） ### 🚫 严格禁止的操作 以下操作在任何情况下都**绝对禁止**，否则视为严重 BUG 和错误： | 禁止操作 | 说明 | |---------|------| | **简化内容** | 任何文档、API 说明、字段描述、权限要求等**必须完整版**，禁止省略、缩写、合并 | | **数据推算** | 禁止根据已有数据推算出不存在的信息，必须**真实记录**，没有就写"无此信息" | | **省略示例** | 请求示例、响应示例、错误码示例等**必须完整**，禁止省略部分行 | | **偷懒操作** | 不得跳过必填字段说明、参数说明等文档内容 | | **模糊处理** | 所有字段说明、权限要求、参数说明必须清晰完整，不可模糊 | ### 违反规则的严重性 违反上述任何一条规则，均视为： - ❌ **严重 BUG** - ❌ **错误** - ❌ **过错** - ❌ **偷懒** - ❌ **失误** 这些操作在任何情况下都不允许发生。 ## 使用说明 ### 目录结构 - **open-apis/** - 飞书 API 文档集合 - README.md - TEMPLATE.md - auth-v3-tenant_access_token-internal.md - 自建应用获取 tenant_access_token - authen-v1-user_info.md - 获取用户信息 - contact-v3-*.md - 通讯录 v3 API（用户、部门） - im-v1-*.md - 消息 API - passport-v1-sessions-query.md - 获取用户登录信息 ## App 配置 ⚠️ **安全提示**：应用凭证应存储在环境变量或配置文件中，不要硬编码在代码中。 ## 权限链接规范 ⚠️ **重要**：所有 API 文档中涉及权限相关的描述，必须包含以下链接： | 权限类型 | 链接 | |---------|------| | 应用权限配置 | [https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN](https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN) | | 用户相关的 ID 概念 | [https://open.feishu.cn/document/home/user-identity-introduction/introduction](https://open.feishu.cn/document/home/user-identity-introduction/introduction) | | 部门 ID 说明 | [https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview) | | 权限范围校验 | [https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority](https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority) | | 通用错误码 | [https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN) | ## 记录规则 1. **API 文档** - 每个 API 文件必须包含权限要求小节 2. **字段权限** - 涉及敏感字段时，必须标注所需权限及链接 3. **错误码** - 权限错误（如 40004, 41050）必须包含权限排查链接 4. **配置说明** - 权限配置步骤必须包含飞书后台操作指引 **使用规范** - 所有文档必须保持飞书官方文档的完整性，禁止简化、省略、合并 - 所有示例必须完整展示，禁止省略部分行 - 所有字段必须完整说明权限要求，禁止推算或猜测 - 所有内容必须真实记录，禁止偷懒、失误或简化 - **禁止擅自发挥**：不允许对原始内容进行任何未明确要求的修改、改名、结构调整 - **禁止理解偏差**：如有不明确之处，必须向用户确认后再操作 - **必须认真仔细**：每一步操作都要核对原始文档，确保准确无误

path: open-apis/auth-v3-tenant_access_token-internal.md
content: # 自建应用获取 tenant_access_token

## 注意事项

`tenant_access_token` 的最大有效期是 2 小时。

- 剩余有效期小于 30 分钟时，调用本接口会返回一个新的 `tenant_access_token`，这会同时存在两个有效的 `tenant_access_token`。
- 剩余有效期大于等于 30 分钟时，调用本接口会返回原有的 `tenant_access_token`。

## 权限要求

### 必要权限

无需权限

### 可选权限

无需权限

## 接口信息

| API 路径 | `https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal` |
|----------|--------------------------------------------------------------------------|
| 请求方法 | POST |
| 调用频率限制 | - |
| 支持的应用类型 | Custom App |
| 文档地址 | [飞书开放平台](https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/reference/auth-v3/tenant_access_token/internal) |

## 接口请求

### 请求头

| 名称 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `Content-Type` | string | 是 | 固定值："application/json; charset=utf-8" |

### 请求参数

无查询参数

### 请求体

| 字段 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `app_id` | string | 是 | 应用唯一标识，创建应用后获得。有关 `app_id` 的详细介绍，请参考[通用参数](https://open.feishu.cn/document/ukTMukTMukTM/uYTM5UjL2ETO14iNxkTN/terminology)介绍 |
| `app_secret` | string | 是 | 应用秘钥，创建应用后获得。有关 `app_secret` 的详细介绍，请参考[通用参数](https://open.feishu.cn/document/ukTMukTMukTM/uYTM5UjL2ETO14iNxkTN/terminology)介绍 |

### 请求示例

#### cURL 请求示例

```bash
curl -X POST 'https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "app_id": "cli_slkdjalasdkjasd",
    "app_secret": "dskLLdkasdjlasdKK"
  }'
```

#### Python 请求示例

```python
import requests
import json

def main():
    url = "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal"
    headers = {
        "Content-Type": "application/json; charset=utf-8"
    }
    data = {
        "app_id": "cli_slkdjalasdkjasd",
        "app_secret": "dskLLdkasdjlasdKK"
    }
    
    response = requests.post(url, headers=headers, json=data)
    print(json.dumps(response.json(), indent=2, ensure_ascii=False))

if __name__ == "__main__":
    main()
```

#### Go 请求示例

```go
import (
	"context"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	url := "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal"
	
	data := map[string]string{
		"app_id":     "cli_slkdjalasdkjasd",
		"app_secret": "dskLLdkasdjlasdKK",
	}
	
	jsonData, _ := json.Marshal(data)
	
	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
	req.Header.Set("Content-Type", "application/json; charset=utf-8")
	
	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		fmt.Println("Error:", err)
		return
	}
	defer resp.Body.Close()
	
	fmt.Println("Response status:", resp.Status)
}
```

## 接口响应

### 响应头

| 名称 | 类型 | 描述 |
|------|------|------|
| - | - | 无额外响应头字段 |

### 响应体

| 字段 | 类型 | 描述 |
|------|------|------|
| `code` | int | 错误码，非 0 取值表示失败 |
| `msg` | string | 错误描述 |
| `tenant_access_token` | string | 租户访问凭证 |
| `expire` | int | `tenant_access_token` 的过期时间，单位为秒 |

### 响应示例

```json
{
    "code": 0,
    "msg": "ok",
    "tenant_access_token": "t-caecc734c2e3328a62489fe0648c4b98779515d3",
    "expire": 7200
}
```

## 响应码定义

### 成功码

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 200 | 0 | 请求成功 |

### 客户端错误码 (4xx)

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| - | - | 暂无（具体错误码请参考[通用错误码](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN)） |

### 服务端错误码 (5xx)

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| - | - | 暂无 |

## 附录

### 相关链接

| 链接类型 | 链接 |
|----------|------|
| 通用参数 | [https://open.feishu.cn/document/ukTMukTMukTM/uYTM5UjL2ETO14iNxkTN/terminology](https://open.feishu.cn/document/ukTMukTMukTM/uYTM5UjL2ETO14iNxkTN/terminology) |
| 通用错误码 | [https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN) |

path: open-apis/authen-v1-user_info.md
content: # 获取用户信息

## 注意事项

手机号和邮箱信息为管理员导入的用户联系方式，未经过用户本人实时验证，不建议开发者直接将其作为业务系统的登录凭证。如使用，务必自行认证。

## 权限要求

### 必要权限

无需权限

### 可选权限

| 类型 | 名称 |
|------|------|
| 字段权限（敏感字段） | 获取用户受雇信息 (contact:user.employee:readonly) |
| 字段权限（敏感字段） | 获取用户 user ID (contact:user.employee_id:readonly) |
| 字段权限（敏感字段） | 获取用户手机号 (contact:user.phone:readonly) |
| 字段权限（敏感字段） | 获取用户邮箱信息 (contact:user.email:readonly) |
| 字段权限（敏感字段） | 以应用身份访问通讯录 (contact:contact:access_as_app) |
| 字段权限（敏感字段） | 读取通讯录 (contact:contact:readonly) |
| 字段权限（敏感字段） | 以应用身份读取通讯录 (contact:contact:readonly_as_app) |

> **说明**：敏感字段仅在开启对应权限后才会返回；如无需获取这些字段，不建议申请。

## 接口信息

| API 路径 | `https://open.feishu.cn/open-apis/authen/v1/user_info` |
|----------|--------------------------------------------------------|
| 请求方法 | GET |
| 调用频率限制 | 特殊频控 |
| 支持的应用类型 | Custom App、Store App |
| 文档地址 | [飞书开放平台](https://open.feishu.cn/document/ukTMukTMukTM/ugjNz4SO2UjL5jDN/authen-v1/user_info) |

## 接口请求

### 请求头

| 名称 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `Authorization` | string | 是 | `user_access_token`<br>值格式："Bearer `access_token`"<br>示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560"<br>**了解更多**：[如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use) |
| `Content-Type` | string | 是 | 固定值："application/json; charset=utf-8" |

### 请求参数

无查询参数

### 请求体

无请求体（GET 请求）

### 请求示例

#### cURL 请求示例

```bash
curl -X GET 'https://open.feishu.cn/open-apis/authen/v1/user_info' \
  -H '[REDACTED_SECRET]' \
  -H 'Content-Type: application/json; charset=utf-8'
```

#### Python 请求示例

```python
import requests
import json

def main():
    url = "https://open.feishu.cn/open-apis/authen/v1/user_info"
    headers = {
        "Authorization": "Bearer user_access_token",
        "Content-Type": "application/json; charset=utf-8"
    }
    
    response = requests.get(url, headers=headers)
    print(json.dumps(response.json(), indent=2, ensure_ascii=False))

if __name__ == "__main__":
    main()
```

#### Go 请求示例

```go
import (
	"context"
	"fmt"
	"net/http"
)

func main() {
	url := "https://open.feishu.cn/open-apis/authen/v1/user_info"
	
	req, _ := http.NewRequest("GET", url, nil)
	req.Header.Set("Authorization", "Bearer user_access_token")
	req.Header.Set("Content-Type", "application/json; charset=utf-8")
	
	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		fmt.Println("Error:", err)
		return
	}
	defer resp.Body.Close()
	
	fmt.Println("Response status:", resp.Status)
}
```

#### Java 请求示例

```java
import com.lark.oapi.Client;
import com.lark.oapi.core.request.RequestOptions;

public class Main {
    public static void main(String arg[]) throws Exception {
        // 构建client
        Client client = Client.newBuilder("appId", "appSecret").build();

        // 发起请求
        // 注意：该接口使用 user_access_token，无需应用凭证
    }
}
```

## 接口响应

### 响应头

| 名称 | 类型 | 描述 |
|------|------|------|
| - | - | 无额外响应头字段 |

### 响应体

| 字段 | 类型 | 描述 |
|------|------|------|
| `code` | int | 错误码，非 0 表示失败 |
| `msg` | string | 错误描述 |
| `data` | object | 用户信息对象 |
| `name` | string | 用户姓名 |
| `en_name` | string | 用户英文名称 |
| `avatar_url` | string | 用户头像 |
| `avatar_thumb` | string | 用户头像 72x72 |
| `avatar_middle` | string | 用户头像 240x240 |
| `avatar_big` | string | 用户头像 640x640 |
| `open_id` | string | 用户在应用内的唯一标识 |
| `union_id` | string | 用户对ISV的唯一标识，对于同一个ISV，用户在其名下所有应用的union_id相同 |
| `email` | string | 用户邮箱。邮箱信息为管理员导入的用户联系方式，未经过用户本人实时验证，不建议开发者直接将其作为业务系统的登录凭证。如使用，务必自行认证。 |
| `enterprise_email` | string | 企业邮箱，请先确保已在管理后台启用飞书邮箱服务 |
| `user_id` | string | 用户 user_id |
| `mobile` | string | 用户手机号。手机号信息为管理员导入的用户联系方式，未经过用户本人实时验证，不建议开发者直接将其作为业务系统的登录凭证。如使用，务必自行认证。 |
| `tenant_key` | string | 当前企业标识 |
| `employee_no` | string | 用户工号 |

### 响应示例

```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "name": "zhangsan",
        "en_name": "zhangsan",
        "avatar_url": "www.feishu.cn/avatar/icon",
        "avatar_thumb": "www.feishu.cn/avatar/icon_thumb",
        "avatar_middle": "www.feishu.cn/avatar/icon_middle",
        "avatar_big": "www.feishu.cn/avatar/icon_big",
        "open_id": "ou-caecc734c2e3328a62489fe0648c4b98779515d3",
        "union_id": "on-d89jhsdhjsajkda7828enjdj328ydhhw3u43yjhdj",
        "email": "[REDACTED_SECRET]",
        "enterprise_email": "[REDACTED_SECRET]",
        "user_id": "5d9bdxxx",
        "mobile": "+86130002883xx",
        "tenant_key": "736588c92lxf175d",
        "employee_no": "111222333"
    }
}
```

## 响应码定义

### 成功码

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 200 | 0 | 请求成功 |

### 客户端错误码 (4xx)

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 200 | 20001 | Invalid request. Please check request param |
| 200 | 20005 | The user access token passed is invalid. Please check the value |
| 200 | 20008 | User not exist |
| 200 | 20021 | User resigned |
| 200 | 20022 | User frozen |
| 200 | 20023 | User not registered |

### 服务端错误码 (5xx)

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 500 | 20050 | System error |

## 附录

### 相关链接

| 链接类型 | 链接 |
|----------|------|
| 获取 user_access_token | [获取用户访问凭证](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/authentication-management/access-token/get-user-access-token) |
| 应用权限配置 | [https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN](https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN) |
| 用户相关的 ID 概念 | [https://open.feishu.cn/document/home/user-identity-introduction/introduction](https://open.feishu.cn/document/home/user-identity-introduction/introduction) |
| 通用错误码 | [https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN) |

path: open-apis/contact-v3-departments-batch.md
content: # 批量获取部门信息

## 注意事项

使用不同身份调用本接口时，需要注意不同身份所需的不同权限范围。具体说明如下：

- 当你使用应用身份（tenant_access_token）调用本接口时，应用的通讯录权限范围内需要包含当前被查询的部门。如果需要查询根部门信息，则应用的通讯录权限范围需设置为 **全部成员**。了解权限范围参见[权限范围资源介绍](https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority)。
- 当你使用用户身份（user_access_token）调用本接口时，需要确保该用户身份拥有待查询部门的可见性。如果需要查询根部门信息，则用户需要可见所有人。用户的组织架构可见范围需要由企业管理员在[管理后台](https://feishu.cn/admin/index) > **安全** > **成员权限** > **组织架构可见范围** 内调整。

## 权限要求

### 必要权限

| 类型 | 名称 |
|------|------|
| 应用权限（开启任一即可） | 获取通讯录基本信息 (contact:contact.base:readonly) |

### 可选权限

| 类型 | 名称 |
|------|------|
| 字段权限（敏感字段） | 获取通讯录部门组织架构信息 (contact:department.organize:readonly) |
| 字段权限（敏感字段） | 获取部门基础信息 (contact:department.base:readonly) |
| 字段权限（敏感字段） | 获取用户 user ID (contact:user.employee_id:readonly) |
| 字段权限（敏感字段） | 查询部门 HRBP 信息 (contact:department.hrbp:readonly) |
| 字段权限（敏感字段） | 以应用身份访问通讯录 (contact:contact:access_as_app) |
| 字段权限（敏感字段） | 读取通讯录 (contact:contact:readonly) |
| 字段权限（敏感字段） | 以应用身份读取通讯录 (contact:contact:readonly_as_app) |

> **说明**：敏感字段仅在开启对应权限后才会返回；如无需获取这些字段，不建议申请。

## 接口信息

| API 路径 | `https://open.feishu.cn/open-apis/contact/v3/departments/batch` |
|----------|------------------------------------------------------------------|
| 请求方法 | GET |
| 调用频率限制 | 1000 次/分钟、50 次/秒 |
| 支持的应用类型 | Custom App、Store App |
| 文档地址 | [飞书开放平台](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/batch_get) |

## 接口请求

### 请求头

| 名称 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `Authorization` | string | 是 | `tenant_access_token` 或 `user_access_token`<br>值格式："Bearer `access_token`"<br>示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560"<br>**了解更多**：[如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use) |
| `Content-Type` | string | 是 | 固定值："application/json; charset=utf-8" |

### 请求参数

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `department_ids` | array | 是 | 部门 ID，ID 类型需要与查询参数 `department_id_type` 的取值保持一致。<br>说明：<br>- 调用创建部门接口后，可从返回结果中获取到部门 ID 信息<br>- 部门 API 提供了多种获取其他部门 ID 的方式，如获取子部门列表、获取父部门信息、搜索部门<br>注意：<br>- 单次最大请求的 ID 数量为 50<br>- 如需一次查询多个部门，可将同一参数名多次传递，并且每次传递不同的部门 ID 进行查询 |
| `department_id_type` | string | 否 | 此次调用中的部门 ID 类型<br>可选值：<br>- `open_department_id`：由系统自动生成的部门 ID<br>- `department_id`：支持用户自定义配置的部门 ID<br>默认值：`open_department_id` |
| `user_id_type` | string | 否 | 用户 ID 类型<br>可选值：<br>- `open_id`：标识一个用户在某个应用中的身份<br>- `union_id`：标识一个用户在某个应用开发商下的身份<br>- `user_id`：标识一个用户在某个租户内的身份<br>默认值：`open_id`<br>**权限要求**：当值为 `user_id` 时，需要获取用户 user ID (contact:user.employee_id:readonly) |

### 请求体

无请求体（GET 请求）

### 请求示例

#### cURL 请求示例

```bash
curl -X GET 'https://open.feishu.cn/open-apis/contact/v3/departments/batch?department_ids=D096&department_ids=D097&department_id_type=open_department_id&user_id_type=open_id' \
  -H '[REDACTED_SECRET]' \
  -H 'Content-Type: application/json; charset=utf-8'
```

#### Go 请求示例

```go
import (
	"context"

	"github.com/larksuite/oapi-sdk-go/v3"
	"github.com/larksuite/oapi-sdk-go/v3/service/contact/v3"
)

func main() {
	// 创建 Client
	client := lark.NewClient("appID", "appSecret")

	// 创建请求对象
	req := larkcontact.NewBatchGetDepartmentReqBuilder().
		DepartmentIdList([]string{`D096`, `D097`}). // 多次传递 department_ids 参数
		DepartmentIdType(`open_department_id`).
		UserIdType(`open_id`).
		Build()

	// 发起请求
	resp, err := client.Contact.Department.BatchGet(context.Background(), req)
}
```

#### Java 请求示例

```java
import com.lark.oapi.Client;
import com.lark.oapi.service.contact.v3.model.*;
import com.lark.oapi.core.request.RequestOptions;

public class Main {
    public static void main(String arg[]) throws Exception {
        // 构建client
        Client client = Client.newBuilder("appId", "appSecret").build();

        // 创建请求对象
        BatchGetDepartmentReq req = BatchGetDepartmentReq.newBuilder()
                .departmentIdList(java.util.Arrays.asList("D096", "D097"))
                .departmentIdType("open_department_id")
                .userIdType("open_id")
                .build();

        // 发起请求
        BatchGetDepartmentResp resp = client.contact().department().batchGet(req, RequestOptions.newBuilder().build());
    }
}
```

#### Python 请求示例

```python
import requests
import json

def main():
    url = "https://open.feishu.cn/open-apis/contact/v3/departments/batch"
    headers = {
        "Authorization": "Bearer tenant_access_token",
        "Content-Type": "application/json; charset=utf-8"
    }
    params = [
        ("department_ids", "D096"),
        ("department_ids", "D097"),
        ("department_id_type", "open_department_id"),
        ("user_id_type", "open_id")
    ]
    
    response = requests.get(url, headers=headers, params=params)
    print(json.dumps(response.json(), indent=2, ensure_ascii=False))

if __name__ == "__main__":
    main()
```

## 接口响应

### 响应头

| 名称 | 类型 | 描述 |
|------|------|------|
| - | - | 无额外响应头字段 |

### 响应体

| 字段 | 类型 | 描述 |
|------|------|------|
| `code` | int | 错误码，非 0 表示失败 |
| `msg` | string | 错误描述 |
| `data` | object | 响应数据 |
| `items` | array | 查询到的部门信息列表 |

#### department 对象

| 字段 | 类型 | 描述 |
|------|------|------|
| `name` | string | 部门名称 |
| `i18n_name` | object | 部门名称的国际化配置 |
| `parent_department_id` | string | 父部门的部门 ID |
| `department_id` | string | 自定义部门 ID |
| `open_department_id` | string | 部门的 open_department_id |
| `leader_user_id` | string | 部门主管的用户 ID |
| `chat_id` | string | 部门群的群 ID |
| `order` | string | 部门的排序 |
| `unit_ids` | array | 部门绑定的单位自定义 ID 列表 |
| `member_count` | int | 当前部门及其下属部门的用户（包含部门负责人）个数 |
| `status` | object | 部门状态 |
| `leaders` | array | 部门负责人信息列表 |
| `group_chat_employee_types` | array | 部门群的人员类型限制 |
| `department_hrbps` | array | 部门 HRBP 的用户 ID 列表 |
| `primary_member_count` | int | 当前部门及其下属部门的主属成员数量 |

### 响应示例

```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "items": [
            {
                "name": "DemoName",
                "i18n_name": {
                    "zh_cn": "Demo名称",
                    "ja_jp": "デモ名",
                    "en_us": "Demo Name"
                },
                "parent_department_id": "D067",
                "department_id": "D096",
                "open_department_id": "od-4e6ac4d14bcd5071a37a39de902c7141",
                "leader_user_id": "ou_7dab8a3d3cdcc9da365777c7ad535d62",
                "chat_id": "oc_5ad11d72b830411d72b836c20",
                "order": "100",
                "unit_ids": [
                    "custom_unit_id"
                ],
                "member_count": 100,
                "status": {
                    "is_deleted": false
                },
                "leaders": [
                    {
                        "leaderType": 1,
                        "leaderID": "ou_7dab8a3d3cdcc9da365777c7ad535d62"
                    }
                ],
                "group_chat_employee_types": [
                    1
                ],
                "department_hrbps": [
                    "ou_7dab8a3d3cdcc9da365777c7ad535d62"
                ],
                "primary_member_count": 100
            }
        ]
    }
}
```

## 响应码定义

### 成功码

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 200 | 0 | 请求成功 |

### 客户端错误码 (4xx)

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 400 | 40001 | param is invalid |
| 400 | 43010 | big dept forbid recursion error |
| 400 | 40003 | internal error |
| 400 | 40008 | dept Info is null error |
| 400 | 40011 | page size is more than 50 error |
| 400 | 40012 | page token is invalid error |
| 400 | 43007 | duplicated department unit custom id error |
| 401 | 42008 | tenant id is invalid error |
| 403 | 40014 | no parent dept authority error |
| 403 | 40004 | no dept authority error |

### 服务端错误码 (5xx)

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| - | - | 暂无 |

## 附录

### 相关链接

| 链接类型 | 链接 |
|----------|------|
| 应用权限配置 | [https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN](https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN) |
| 部门 ID 说明 | [https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview) |
| 权限范围校验 | [https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority](https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority) |
| 通用错误码 | [https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN) |

path: open-apis/contact-v3-departments-department_id-children.md
content: # 获取子部门列表

## 注意事项

- 当你使用应用身份（tenant_access_token）调用本接口时，应用的通讯录权限范围内需要包含当前被查询的部门。如果需要查询根部门（部门 ID 为 0）下的子部门列表，则应用的通讯录权限范围需设置为 **全部成员**。了解权限范围参见[权限范围资源介绍](https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority)。

- 当你使用用户身份（user_access_token）调用本接口时需要注意：
  - 确保该用户身份拥有待查询部门的可见性，用户的组织架构可见范围需要由企业管理员在[管理后台](https://feishu.cn/admin/index) > **安全** > **成员权限** > **组织架构可见范围** 内调整。
  - 请求时如果开启了递归获取子部门（fetch_child 取值为 true），则用户可查询到的部门数量上限为 1000 个。

## 权限要求

### 必要权限

| 类型 | 名称 |
|------|------|
| 应用权限（开启任一即可） | 获取通讯录基本信息 (contact:contact.base:readonly) |
| 应用权限（开启任一即可） | 获取通讯录部门组织架构信息 (contact:department.organize:readonly) |
| 应用权限（开启任一即可） | 以应用身份访问通讯录 (contact:contact:access_as_app) |
| 应用权限（开启任一即可） | 读取通讯录 (contact:contact:readonly) |
| 应用权限（开启任一即可） | 以应用身份读取通讯录 (contact:contact:readonly_as_app) |

### 可选权限

| 类型 | 名称 |
|------|------|
| 字段权限（敏感字段） | 获取通讯录部门组织架构信息 (contact:department.organize:readonly) |
| 字段权限（敏感字段） | 获取部门基础信息 (contact:department.base:readonly) |
| 字段权限（敏感字段） | 获取用户 user ID (contact:user.employee_id:readonly) |
| 字段权限（敏感字段） | 查询部门 HRBP 信息 (contact:department.hrbp:readonly) |
| 字段权限（敏感字段） | 以应用身份访问通讯录 (contact:contact:access_as_app) |
| 字段权限（敏感字段） | 读取通讯录 (contact:contact:readonly) |
| 字段权限（敏感字段） | 以应用身份读取通讯录 (contact:contact:readonly_as_app) |

> **说明**：敏感字段仅在开启对应权限后才会返回；如无需获取这些字段，不建议申请。

## 接口信息

| API 路径 | `https://open.feishu.cn/open-apis/contact/v3/departments/:department_id/children` |
|----------|-----------------------------------------------------------------------------------|
| 请求方法 | GET |
| 调用频率限制 | 1000 次/分钟、50 次/秒 |
| 支持的应用类型 | Custom App、Store App |
| 文档地址 | [飞书开放平台](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/children) |

## 接口请求

### 请求头

| 名称 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `Authorization` | string | 是 | `tenant_access_token` 或 `user_access_token`<br>值格式："Bearer `access_token`"<br>示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560"<br>**了解更多**：[如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use) |
| `Content-Type` | string | 是 | 固定值："application/json; charset=utf-8" |

### 请求参数

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `department_id` | string | 是 | 部门 ID。<br>说明：<br>- ID 类型需要与查询参数 `department_id_type` 的取值保持一致<br>- 根部门的部门 ID 为 0<br>最大长度：`64` 字符<br>正则校验：`^[a-zA-Z0-9][a-zA-Z0-9_\-@.]{0,63}$` |
| `user_id_type` | string | 否 | 用户 ID 类型<br>可选值：<br>- `open_id`：标识一个用户在某个应用中的身份<br>- `union_id`：标识一个用户在某个应用开发商下的身份<br>- `user_id`：标识一个用户在某个租户内的身份<br>默认值：`open_id`<br>**权限要求**：当值为 `user_id` 时，需要获取用户 user ID (contact:user.employee_id:readonly) |
| `department_id_type` | string | 否 | 此次调用中的部门 ID 类型<br>可选值：<br>- `department_id`：支持用户自定义配置的部门 ID<br>- `open_department_id`：由系统自动生成的部门 ID<br>默认值：`open_department_id` |
| `fetch_child` | boolean | 否 | 是否递归获取子部门<br>可选值：<br>- `true`：是<br>- `false`（默认值）：否 |
| `page_size` | int | 否 | 分页大小，用于限制一次请求所返回的数据条目数<br>默认值：`10`<br>最大值：`50` |
| `page_token` | string | 否 | 分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果 |

### 请求体

无请求体（GET 请求）

### 请求示例

#### cURL 请求示例

```bash
curl -X GET 'https://open.feishu.cn/open-apis/contact/v3/departments/D096/children?fetch_child=false&page_size=10&page_token=AQD9/...' \
  -H '[REDACTED_SECRET]' \
  -H 'Content-Type: application/json; charset=utf-8'
```

#### Go 请求示例

```go
import (
	"context"

	"github.com/larksuite/oapi-sdk-go/v3"
	"github.com/larksuite/oapi-sdk-go/v3/service/contact/v3"
)

func main() {
	// 创建 Client
	client := lark.NewClient("appID", "appSecret")

	// 创建请求对象
	req := larkcontact.NewChildrenDepartmentReqBuilder().
		DepartmentId(`D096`).
		PageSize(10).
		Build()

	// 发起请求
	resp, err := client.Contact.Department.Children(context.Background(), req)
}
```

#### Java 请求示例

```java
import com.lark.oapi.Client;
import com.lark.oapi.core.request.RequestOptions;
import com.lark.oapi.service.contact.v3.model.ChildrenDepartmentReq;
import com.lark.oapi.service.contact.v3.model.ChildrenDepartmentResp;

public class Main {
    public static void main(String arg[]) throws Exception {
        // 构建client
        Client client = Client.newBuilder("appId", "appSecret").build();

        // 创建请求对象
        ChildrenDepartmentReq req = ChildrenDepartmentReq.newBuilder()
                .departmentId("D096")
                .pageSize(10)
                .build();

        // 发起请求
        ChildrenDepartmentResp resp = client.contact().department().children(req, RequestOptions.newBuilder().build());
    }
}
```

#### Python 请求示例

```python
import requests
import json

def main():
    url = "https://open.feishu.cn/open-apis/contact/v3/departments/D096/children"
    headers = {
        "Authorization": "Bearer tenant_access_token",
        "Content-Type": "application/json; charset=utf-8"
    }
    params = {
        "fetch_child": False,
        "page_size": 10,
        "page_token": "AQD9/..."
    }
    
    response = requests.get(url, headers=headers, params=params)
    print(json.dumps(response.json(), indent=2, ensure_ascii=False))

if __name__ == "__main__":
    main()
```

## 接口响应

### 响应头

| 名称 | 类型 | 描述 |
|------|------|------|
| - | - | 无额外响应头字段 |

### 响应体

| 字段 | 类型 | 描述 |
|------|------|------|
| `code` | int | 错误码，非 0 表示失败 |
| `msg` | string | 错误描述 |
| `data` | object | 响应数据 |
| `has_more` | boolean | 是否还有更多项 |
| `page_token` | string | 分页标记，当 `has_more` 为 true 时，会同时返回新的 `page_token` |
| `items` | array | 部门列表 |

#### department 对象

| 字段 | 类型 | 描述 |
|------|------|------|
| `name` | string | 部门名称 |
| `i18n_name` | object | 部门名称的国际化配置 |
| `parent_department_id` | string | 父部门的部门 ID |
| `department_id` | string | 自定义部门 ID |
| `open_department_id` | string | 部门的 open_department_id |
| `leader_user_id` | string | 部门主管的用户 ID |
| `chat_id` | string | 部门群的群 ID |
| `order` | string | 部门的排序 |
| `unit_ids` | array | 部门绑定的单位自定义 ID 列表 |
| `member_count` | int | 当前部门及其下属部门的用户（包含部门负责人）个数 |
| `status` | object | 部门状态 |
| `leaders` | array | 部门负责人信息列表 |
| `group_chat_employee_types` | array | 部门群的人员类型限制 |
| `department_hrbps` | array | 部门 HRBP 的用户 ID 列表 |
| `primary_member_count` | int | 当前部门及其下属部门的主属成员数量 |

### 响应示例

```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "has_more": true,
        "page_token": [REDACTED_SECRET],
        "items": [
            {
                "name": "DemoName",
                "i18n_name": {
                    "zh_cn": "Demo名称",
                    "ja_jp": "デモ名",
                    "en_us": "Demo Name"
                },
                "parent_department_id": "D067",
                "department_id": "D096",
                "open_department_id": "od-4e6ac4d14bcd5071a37a39de902c7141",
                "leader_user_id": "ou_7dab8a3d3cdcc9da365777c7ad535d62",
                "chat_id": "oc_5ad11d72b830411d72b836c20",
                "order": "100",
                "unit_ids": [
                    "custom_unit_id"
                ],
                "member_count": 100,
                "status": {
                    "is_deleted": false
                },
                "leaders": [
                    {
                        "leaderType": 1,
                        "leaderID": "ou_7dab8a3d3cdcc9da365777c7ad535d62"
                    }
                ],
                "department_hrbps": [
                    "ou_10430f87894fce18e57891c48995cd7c"
                ]
            }
        ]
    }
}
```

## 响应码定义

### 成功码

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 200 | 0 | 请求成功 |

### 客户端错误码 (4xx)

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 400 | 43010 | big dept forbid recursion error |
| 400 | 40003 | internal error |
| 400 | 40008 | dept Info is null error |
| 400 | 40011 | page size is invalid |
| 400 | 40012 | page token is invalid error |
| 400 | 43007 | duplicated department custom id error |
| 401 | 42008 | tenant id is invalid error |
| 403 | 40014 | no parent dept authority error |
| 403 | 40004 | no dept authority error |

### 服务端错误码 (5xx)

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| - | - | 暂无 |

## 附录

### 相关链接

| 链接类型 | 链接 |
|----------|------|
| 应用权限配置 | [https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN](https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN) |
| 部门 ID 说明 | [https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview) |
| 权限范围校验 | [https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority](https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority) |
| 通用错误码 | [https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN) |

path: open-apis/contact-v3-departments-department_id.md
content: # 获取单个部门信息

## 注意事项

使用不同身份调用本接口时，需要注意不同身份所需的不同权限范围。具体说明如下：

- 当你使用应用身份（tenant_access_token）调用本接口时，应用的通讯录权限范围内需要包含当前被查询的部门。如果需要查询根部门信息，则应用的通讯录权限范围需设置为 **全部成员**。了解权限范围参见[权限范围资源介绍](https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority)。
- 当你使用用户身份（user_access_token）调用本接口时，需要确保该用户身份拥有待查询部门的可见性。如果需要查询根部门信息，则用户需要可见所有人。用户的组织架构可见范围需要由企业管理员在[管理后台](https://feishu.cn/admin/index) > **安全** > **成员权限** > **组织架构可见范围** 内调整。

## 权限要求

### 必要权限

| 类型 | 名称 |
|------|------|
| 应用权限（开启任一即可） | 获取通讯录基本信息 (contact:contact.base:readonly) |
| 应用权限（开启任一即可） | 以应用身份访问通讯录 (contact:contact:access_as_app) |
| 应用权限（开启任一即可） | 读取通讯录 (contact:contact:readonly) |
| 应用权限（开启任一即可） | 以应用身份读取通讯录 (contact:contact:readonly_as_app) |

### 可选权限

| 类型 | 名称 |
|------|------|
| 字段权限（敏感字段） | 获取通讯录部门组织架构信息 (contact:department.organize:readonly) |
| 字段权限（敏感字段） | 获取部门基础信息 (contact:department.base:readonly) |
| 字段权限（敏感字段） | 获取用户 user ID (contact:user.employee_id:readonly) |
| 字段权限（敏感字段） | 查询部门 HRBP 信息 (contact:department.hrbp:readonly) |
| 字段权限（敏感字段） | 以应用身份访问通讯录 (contact:contact:access_as_app) |
| 字段权限（敏感字段） | 读取通讯录 (contact:contact:readonly) |
| 字段权限（敏感字段） | 以应用身份读取通讯录 (contact:contact:readonly_as_app) |

> **说明**：敏感字段仅在开启对应权限后才会返回；如无需获取这些字段，不建议申请。

## 接口信息

| API 路径 | `https://open.feishu.cn/open-apis/contact/v3/departments/:department_id` |
|----------|---------------------------------------------------------------------------|
| 请求方法 | GET |
| 调用频率限制 | 特殊频控 |
| 支持的应用类型 | Custom App、Store App |
| 文档地址 | [飞书开放平台](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/get) |

## 接口请求

### 请求头

| 名称 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `Authorization` | string | 是 | `tenant_access_token` 或 `user_access_token`<br>值格式："Bearer `access_token`"<br>示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560"<br>**了解更多**：[如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use) |
| `Content-Type` | string | 是 | 固定值："application/json; charset=utf-8" |

### 请求参数

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `department_id` | string | 是 | 部门 ID，ID 类型需要与查询参数 `department_id_type` 的取值保持一致。<br>说明：<br>- 调用创建部门接口后，可从返回结果中获取到部门 ID 信息<br>- 部门 API 提供了多种获取-other 部门 ID 的方式，如获取子部门列表、获取父部门信息、搜索部门<br>最大长度：`64` 字符<br>正则校验：`^[a-zA-Z0-9][a-zA-Z0-9_\-@.]{0,63}$` |
| `user_id_type` | string | 否 | 用户 ID 类型<br>可选值：<br>- `open_id`：标识一个用户在某个应用中的身份<br>- `union_id`：标识一个用户在某个应用开发商下的身份<br>- `user_id`：标识一个用户在某个租户内的身份<br>默认值：`open_id`<br>**权限要求**：当值为 `user_id` 时，需要获取用户 user ID (contact:user.employee_id:readonly) |
| `department_id_type` | string | 否 | 此次调用中的部门 ID 类型<br>可选值：<br>- `department_id`：支持用户自定义配置的部门 ID<br>- `open_department_id`：由系统自动生成的部门 ID<br>默认值：`open_department_id` |

### 请求体

无请求体（GET 请求）

### 请求示例

#### cURL 请求示例

```bash
curl -X GET 'https://open.feishu.cn/open-apis/contact/v3/departments/D096?user_id_type=open_id&department_id_type=open_department_id' \
  -H '[REDACTED_SECRET]' \
  -H 'Content-Type: application/json; charset=utf-8'
```

#### Go 请求示例

```go
import (
	"context"

	"github.com/larksuite/oapi-sdk-go/v3"
	"github.com/larksuite/oapi-sdk-go/v3/service/contact/v3"
)

func main() {
	// 创建 Client
	client := lark.NewClient("appID", "appSecret")

	// 创建请求对象
	req := larkcontact.NewGetDepartmentReqBuilder().
		DepartmentId(`D096`).
		Build()

	// 发起请求
	resp, err := client.Contact.Department.Get(context.Background(), req)
}
```

#### Java 请求示例

```java
import com.lark.oapi.Client;
import com.lark.oapi.service.contact.v3.model.*;
import com.lark.oapi.core.request.RequestOptions;

public class Main {
    public static void main(String arg[]) throws Exception {
        // 构建client
        Client client = Client.newBuilder("appId", "appSecret").build();

        // 创建请求对象
        GetDepartmentReq req = GetDepartmentReq.newBuilder()
                .departmentId("D096")
                .userIdType("open_id")
                .departmentIdType("open_department_id")
                .build();

        // 发起请求
        GetDepartmentResp resp = client.contact().department().get(req, RequestOptions.newBuilder().build());
    }
}
```

#### Python 请求示例

```python
import requests
import json

def main():
    url = "https://open.feishu.cn/open-apis/contact/v3/departments/D096"
    headers = {
        "Authorization": "Bearer tenant_access_token",
        "Content-Type": "application/json; charset=utf-8"
    }
    params = {
        "user_id_type": "open_id",
        "department_id_type": "open_department_id"
    }
    
    response = requests.get(url, headers=headers, params=params)
    print(json.dumps(response.json(), indent=2, ensure_ascii=False))

if __name__ == "__main__":
    main()
```

## 接口响应

### 响应头

| 名称 | 类型 | 描述 |
|------|------|------|
| - | - | 无额外响应头字段 |

### 响应体

| 字段 | 类型 | 描述 |
|------|------|------|
| `code` | int | 错误码，非 0 表示失败 |
| `msg` | string | 错误描述 |
| `data` | object | 响应数据 |
| `department` | object | 部门信息 |

#### department 对象

| 字段 | 类型 | 描述 |
|------|------|------|
| `name` | string | 部门名称 |
| `i18n_name` | object | 部门名称的国际化配置 |
| `parent_department_id` | string | 父部门的部门 ID |
| `department_id` | string | 自定义部门 ID |
| `open_department_id` | string | 部门的 open_department_id |
| `leader_user_id` | string | 部门主管的用户 ID |
| `chat_id` | string | 部门群的群 ID |
| `order` | string | 部门的排序 |
| `unit_ids` | array | 部门绑定的单位自定义 ID 列表 |
| `member_count` | int | 当前部门及其下属部门的用户（包含部门负责人）个数 |
| `status` | object | 部门状态 |
| `leaders` | array | 部门负责人信息列表 |
| `group_chat_employee_types` | array | 部门群的人员类型限制 |
| `department_hrbps` | array | 部门 HRBP 的用户 ID 列表 |
| `primary_member_count` | int | 当前部门及其下属部门的主属成员数量 |

### 响应示例

```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "department": {
            "name": "DemoName",
            "i18n_name": {
                "zh_cn": "Demo名称",
                "ja_jp": "デモ名",
                "en_us": "Demo Name"
            },
            "parent_department_id": "D067",
            "department_id": "D096",
            "open_department_id": "od-4e6ac4d14bcd5071a37a39de902c7141",
            "leader_user_id": "ou_7dab8a3d3cdcc9da365777c7ad535d62",
            "chat_id": "oc_5ad11d72b830411d72b836c20",
            "order": "100",
            "unit_ids": [
                "custom_unit_id"
            ],
            "member_count": 100,
            "status": {
                "is_deleted": false
            },
            "leaders": [
                {
                    "leaderType": 1,
                    "leaderID": "ou_7dab8a3d3cdcc9da365777c7ad535d62"
                }
            ],
            "group_chat_employee_types": [
                1
            ],
            "department_hrbps": [
                "ou_7dab8a3d3cdcc9da365777c7ad535d62"
            ],
            "primary_member_count": 100
        }
    }
}
```

## 响应码定义

### 成功码

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 200 | 0 | 请求成功 |

### 客户端错误码 (4xx)

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 400 | 40001 | param error |
| 400 | 43010 | big dept forbid recursion error |
| 400 | 40003 | internal error |
| 400 | 40008 | dept Info is null error |
| 400 | 40015 | department not exist |
| 401 | 42008 | tenant id is invalid error |
| 403 | 40004 | no dept authority error |

### 服务端错误码 (5xx)

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| - | - | 暂无 |

## 附录

### 相关链接

| 链接类型 | 链接 |
|----------|------|
| 应用权限配置 | [https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN](https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN) |
| 部门 ID 说明 | [https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview) |
| 权限范围校验 | [https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority](https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority) |
| 通用错误码 | [https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN) |

path: open-apis/contact-v3-departments-parent.md
content: # 获取父部门信息

## 注意事项

- 使用应用身份（tenant_access_token）调用本接口时，该接口只返回应用通讯录可见范围内的父部门信息。例如有 A > B > C > D 四层级部门关系，当前应用的通讯录权限内只包含了 B 部门，那么查询 D 部门的父部门信息时，只会返回 B、C 部门信息，不会返回 A 部门信息。了解权限范围参见[权限范围资源介绍](https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority)。

- 使用用户身份（user_access_token）调用本接口时，只返回对当前用户有可见性的部门信息。用户的组织架构可见范围需要由企业管理员在[管理后台](https://feishu.cn/admin/index) > **安全** > **成员权限** > **组织架构可见范围** 内调整。

- 所能查询到的父部门不包括根部门。

- 当返回列表内包含多个部门信息时，会按照由子部门到父部门的顺序进行展示。

## 权限要求

### 必要权限

| 类型 | 名称 |
|------|------|
| 应用权限（开启任一即可） | 获取通讯录基本信息 (contact:contact.base:readonly) |
| 应用权限（开启任一即可） | 获取通讯录部门组织架构信息 (contact:department.organize:readonly) |
| 应用权限（开启任一即可） | 以应用身份访问通讯录 (contact:contact:access_as_app) |
| 应用权限（开启任一即可） | 读取通讯录 (contact:contact:readonly) |
| 应用权限（开启任一即可） | 以应用身份读取通讯录 (contact:contact:readonly_as_app) |

### 可选权限

| 类型 | 名称 |
|------|------|
| 字段权限（敏感字段） | 获取通讯录部门组织架构信息 (contact:department.organize:readonly) |
| 字段权限（敏感字段） | 获取部门基础信息 (contact:department.base:readonly) |
| 字段权限（敏感字段） | 获取用户 user ID (contact:user.employee_id:readonly) |
| 字段权限（敏感字段） | 查询部门 HRBP 信息 (contact:department.hrbp:readonly) |
| 字段权限（敏感字段） | 以应用身份访问通讯录 (contact:contact:access_as_app) |
| 字段权限（敏感字段） | 读取通讯录 (contact:contact:readonly) |
| 字段权限（敏感字段） | 以应用身份读取通讯录 (contact:contact:readonly_as_app) |

> **说明**：敏感字段仅在开启对应权限后才会返回；如无需获取这些字段，不建议申请。

## 接口信息

| API 路径 | `https://open.feishu.cn/open-apis/contact/v3/departments/parent` |
|----------|-------------------------------------------------------------------|
| 请求方法 | GET |
| 调用频率限制 | 特殊频控 |
| 支持的应用类型 | Custom App、Store App |
| 文档地址 | [飞书开放平台](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/parent) |

## 接口请求

### 请求头

| 名称 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `Authorization` | string | 是 | `tenant_access_token` 或 `user_access_token`<br>值格式："Bearer `access_token`"<br>示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560"<br>**了解更多**：[如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use) |
| `Content-Type` | string | 是 | 固定值："application/json; charset=utf-8" |

### 请求参数

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `user_id_type` | string | 否 | 用户 ID 类型<br>可选值：<br>- `open_id`：标识一个用户在某个应用中的身份<br>- `union_id`：标识一个用户在某个应用开发商下的身份<br>- `user_id`：标识一个用户在某个租户内的身份<br>默认值：`open_id`<br>**权限要求**：当值为 `user_id` 时，需要获取用户 user ID (contact:user.employee_id:readonly) |
| `department_id_type` | string | 否 | 此次调用中的部门 ID 类型<br>可选值：<br>- `department_id`：支持用户自定义配置的部门 ID<br>- `open_department_id`：由系统自动生成的部门 ID<br>默认值：`open_department_id` |
| `department_id` | string | 是 | 部门 ID。ID 类型需要与查询参数 `department_id_type` 的取值保持一致。<br>当你在创建部门时，可从返回结果中获取到部门 ID 信息，你也可以调用搜索部门接口，获取所需的部门 ID |
| `page_token` | string | 否 | 分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果 |
| `page_size` | int | 否 | 分页大小，用于限制一次请求所返回的数据条目数<br>默认值：`20`<br>最大值：`50` |

### 请求体

无请求体（GET 请求）

### 请求示例

#### cURL 请求示例

```bash
curl -X GET 'https://open.feishu.cn/open-apis/contact/v3/departments/parent?department_id=od-4e6ac4d14bcd5071a37a39de902c7141&department_id_type=open_department_id&user_id_type=open_id&page_size=20' \
  -H '[REDACTED_SECRET]' \
  -H 'Content-Type: application/json; charset=utf-8'
```

#### Go 请求示例

```go
import (
	"context"

	"github.com/larksuite/oapi-sdk-go/v3"
	"github.com/larksuite/oapi-sdk-go/v3/service/contact/v3"
)

func main() {
	// 创建 Client
	client := lark.NewClient("appID", "appSecret")

	// 创建请求对象
	req := larkcontact.NewParentDepartmentReqBuilder().
		DepartmentId(`od-4e6ac4d14bcd5071a37a39de902c7141`).
		PageSize(20).
		Build()

	// 发起请求
	resp, err := client.Contact.Department.Parent(context.Background(), req)
}
```

#### Java 请求示例

```java
import com.lark.oapi.Client;
import com.lark.oapi.core.request.RequestOptions;
import com.lark.oapi.service.contact.v3.model.ParentDepartmentReq;
import com.lark.oapi.service.contact.v3.model.ParentDepartmentResp;

public class Main {
    public static void main(String arg[]) throws Exception {
        // 构建client
        Client client = Client.newBuilder("appId", "appSecret").build();

        // 创建请求对象
        ParentDepartmentReq req = ParentDepartmentReq.newBuilder()
                .departmentId("od-4e6ac4d14bcd5071a37a39de902c7141")
                .pageSize(20)
                .build();

        // 发起请求
        ParentDepartmentResp resp = client.contact().department().parent(req, RequestOptions.newBuilder().build());
    }
}
```

#### Python 请求示例

```python
import requests
import json

def main():
    url = "https://open.feishu.cn/open-apis/contact/v3/departments/parent"
    headers = {
        "Authorization": "Bearer tenant_access_token",
        "Content-Type": "application/json; charset=utf-8"
    }
    params = {
        "department_id": "od-4e6ac4d14bcd5071a37a39de902c7141",
        "department_id_type": "open_department_id",
        "user_id_type": "open_id",
        "page_size": 20
    }
    
    response = requests.get(url, headers=headers, params=params)
    print(json.dumps(response.json(), indent=2, ensure_ascii=False))

if __name__ == "__main__":
    main()
```

## 接口响应

### 响应头

| 名称 | 类型 | 描述 |
|------|------|------|
| - | - | 无额外响应头字段 |

### 响应体

| 字段 | 类型 | 描述 |
|------|------|------|
| `code` | int | 错误码，非 0 表示失败 |
| `msg` | string | 错误描述 |
| `data` | object | 响应数据 |
| `has_more` | boolean | 是否还有更多项 |
| `page_token` | string | 分页标记，当 `has_more` 为 true 时，会同时返回新的 `page_token` |
| `items` | array | 部门列表 |

#### department 对象

| 字段 | 类型 | 描述 |
|------|------|------|
| `name` | string | 部门名称 |
| `i18n_name` | object | 部门名称的国际化配置 |
| `parent_department_id` | string | 父部门的部门 ID |
| `department_id` | string | 自定义部门 ID |
| `open_department_id` | string | 部门的 open_department_id |
| `leader_user_id` | string | 部门主管的用户 ID |
| `chat_id` | string | 部门群的群 ID |
| `order` | string | 部门的排序 |
| `unit_ids` | array | 部门绑定的单位自定义 ID 列表 |
| `member_count` | int | 当前部门及其下属部门的用户（包含部门负责人）个数 |
| `status` | object | 部门状态 |
| `leaders` | array | 部门负责人信息列表 |
| `group_chat_employee_types` | array | 部门群的人员类型限制 |
| `department_hrbps` | array | 部门 HRBP 的用户 ID 列表 |
| `primary_member_count` | int | 当前部门及其下属部门的主属成员数量 |

### 响应示例

```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "has_more": true,
        "page_token": "AQD9/Rn9eij9Pm39ED40/RD/cIFmu77WxpxPB/2oHfQLZ%2BG8JG6tK7%2BZnHiT7COhD2hMSICh/eBl7cpzU6JEC3J7COKNe4jrQ8ExwBCR",
        "items": [
            {
                "name": "DemoName",
                "i18n_name": {
                    "zh_cn": "Demo名称",
                    "ja_jp": "デモ名",
                    "en_us": "Demo Name"
                },
                "parent_department_id": "D067",
                "department_id": "D096",
                "open_department_id": "od-4e6ac4d14bcd5071a37a39de902c7141",
                "leader_user_id": "ou_7dab8a3d3cdcc9da365777c7ad535d62",
                "chat_id": "oc_5ad11d72b830411d72b836c20",
                "order": "100",
                "unit_ids": [
                    "custom_unit_id"
                ],
                "member_count": 100,
                "status": {
                    "is_deleted": false
                },
                "leaders": [
                    {
                        "leaderType": 1,
                        "leaderID": "ou_7dab8a3d3cdcc9da365777c7ad535d62"
                    }
                ],
                "group_chat_employee_types": [
                    1
                ],
                "department_hrbps": [
                    "ou_7dab8a3d3cdcc9da365777c7ad535d62"
                ],
                "primary_member_count": 100
            }
        ]
    }
}
```

## 响应码定义

### 成功码

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 200 | 0 | 请求成功 |

### 客户端错误码 (4xx)

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 400 | 40001 | param error |
| 400 | 40002 | process root dept error |
| 400 | 40003 | internal error |
| 400 | 40008 | dept Info is null error |
| 400 | 40010 | chat id is invalid error |
| 400 | 40011 | page size is invalid |
| 400 | 40012 | page token is invalid error |
| 400 | 43001 | dept unit repeat error |
| 400 | 43002 | dept unit is still using error |
| 400 | 43003 | multi dept unit error |
| 400 | 43004 | illegal unit error |
| 400 | 43005 | duplicate order error |
| 400 | 43007 | duplicated department custom id error |
| 400 | 43008 | custom dept id invalid error |
| 400 | 43009 | exceed update custom dept limit error |
| 400 | 43010 | big dept forbid recursion error |
| 400 | 43011 | delete has member dept error |
| 400 | 43012 | delete has sub dept department error |
| 400 | 43013 | dept too many children error |
| 400 | 44102 | miss department_id error |
| 401 | 42008 | tenant id is invalid error |
| 403 | 40004 | no dept authority error |
| 403 | 40014 | no parent dept authority error |

### 服务端错误码 (5xx)

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| - | - | 暂无 |

## 附录

### 相关链接

| 链接类型 | 链接 |
|----------|------|
| 应用权限配置 | [https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN](https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN) |
| 部门 ID 说明 | [https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview) |
| 权限范围校验 | [https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority](https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority) |
| 通用错误码 | [https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN) |

path: open-apis/contact-v3-scopes.md
content: # 获取通讯录授权范围

## 注意事项

- 当应用通讯录权限范围为全部成员时，该接口将返回根部门下的一级部门列表和直属用户列表，以及租户下所有用户组列表。

- 当应用通讯录权限范围不为全部成员时，则只返回在通讯录权限范围内的部门列表（不包含部门内的子部门以及用户）、用户列表或用户组列表。

## 权限要求

### 必要权限

| 类型 | 名称 |
|------|------|
| 应用权限（开启任一即可） | 获取通讯录基本信息 (contact:contact.base:readonly) |
| 应用权限（开启任一即可） | 以应用身份访问通讯录 (contact:contact:access_as_app) |
| 应用权限（开启任一即可） | 以应用身份读取通讯录 (contact:contact:readonly_as_app) |

### 可选权限

| 类型 | 名称 |
|------|------|
| 字段权限（敏感字段） | 获取用户 user ID (contact:user.employee_id:readonly) |

> **说明**：敏感字段仅在开启对应权限后才会返回；如无需获取这些字段，不建议申请。

## 接口信息

| API 路径 | `https://open.feishu.cn/open-apis/contact/v3/scopes` |
|----------|-----------------------------------------------------|
| 请求方法 | GET |
| 调用频率限制 | 1000 次/分钟、50 次/秒 |
| 支持的应用类型 | Custom App、Store App |
| 文档地址 | [飞书开放平台](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/scope/list) |

## 接口请求

### 请求头

| 名称 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `Authorization` | string | 是 | `tenant_access_token`<br>值格式："Bearer `access_token`"<br>示例值："Bearer t-7f1bcd13fc57d46bac21793a18e560"<br>**了解更多**：[如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use) |
| `Content-Type` | string | 是 | 固定值："application/json; charset=utf-8" |

### 请求参数

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `user_id_type` | string | 否 | 用户 ID 类型<br>可选值：<br>- `open_id`：标识一个用户在某个应用中的身份<br>- `union_id`：标识一个用户在某个应用开发商下的身份<br>- `user_id`：标识一个用户在某个租户内的身份<br>默认值：`open_id`<br>**权限要求**：当值为 `user_id` 时，需要获取用户 user ID (contact:user.employee_id:readonly) |
| `department_id_type` | string | 否 | 指定查询结果中的部门 ID 类型<br>可选值：<br>- `department_id`：支持用户自定义配置的部门 ID<br>- `open_department_id`：由系统自动生成的部门 ID<br>默认值：`open_department_id` |
| `page_token` | string | 否 | 分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果 |
| `page_size` | int | 否 | 分页大小，用于设置一次调用的返回值列表长度。<br>取值范围：`1` ～ `100`<br>默认值：`50` |

### 请求体

无请求体（GET 请求）

### 请求示例

#### cURL 请求示例

```bash
curl -X GET 'https://open.feishu.cn/open-apis/contact/v3/scopes?page_size=50&page_token=AQD9/...' \
  -H '[REDACTED_SECRET]' \
  -H 'Content-Type: application/json; charset=utf-8'
```

#### Go 请求示例

```go
import (
	"context"

	"github.com/larksuite/oapi-sdk-go/v3"
	"github.com/larksuite/oapi-sdk-go/v3/service/contact/v3"
)

func main() {
	// 创建 Client
	client := lark.NewClient("appID", "appSecret")

	// 创建请求对象
	req := larkcontact.NewListScopeReqBuilder().
		UserIdType(`open_id`).
		DepartmentIdType(`open_department_id`).
		PageSize(50).
		PageToken(`AQD9/...`).
		Build()

	// 发起请求
	resp, err := client.Contact.Scope.List(context.Background(), req)
}
```

#### Java 请求示例

```java
import com.lark.oapi.Client;
import com.lark.oapi.service.contact.v3.model.*;
import com.lark.oapi.core.request.RequestOptions;

public class Main {
    public static void main(String arg[]) throws Exception {
        // 构建client
        Client client = Client.newBuilder("appId", "appSecret").build();

        // 创建请求对象
        ListScopeReq req = ListScopeReq.newBuilder()
                .userIdType("open_id")
                .departmentIdType("open_department_id")
                .pageSize(50)
                .pageToken("AQD9/...")
                .build();

        // 发起请求
        ListScopeResp resp = client.contact().scope().list(req, RequestOptions.newBuilder().build());
    }
}
```

#### Python 请求示例

```python
import requests
import json

def main():
    url = "https://open.feishu.cn/open-apis/contact/v3/scopes"
    headers = {
        "Authorization": "Bearer tenant_access_token",
        "Content-Type": "application/json; charset=utf-8"
    }
    params = {
        "page_size": 50,
        "page_token": "AQD9/..."
    }
    
    response = requests.get(url, headers=headers, params=params)
    print(json.dumps(response.json(), indent=2, ensure_ascii=False))

if __name__ == "__main__":
    main()
```

## 接口响应

### 响应头

| 名称 | 类型 | 描述 |
|------|------|------|
| - | - | 无额外响应头字段 |

### 响应体

| 字段 | 类型 | 描述 |
|------|------|------|
| `code` | int | 错误码，非 0 表示失败 |
| `msg` | string | 错误描述 |
| `data` | object | 响应数据 |
| `department_ids` | array | 已授权的部门列表。列表内的部门 ID 类型与查询参数 `department_id_type` 的取值一致 |
| `user_ids` | array | 已授权的用户列表。列表内的用户 ID 类型与查询参数 `user_id_type` 的取值一致 |
| `group_ids` | array | 已授权的用户组 |
| `has_more` | boolean | 是否还有更多项 |
| `page_token` | string | 分页标记，当 `has_more` 为 true 时，会同时返回新的 `page_token` |

### 响应示例

```json
{
    "code": 0,
    "data": {
        "department_ids": [
            "75217143312g9842"
        ],
        "group_ids": [
            "4bgga762"
        ],
        "has_more": true,
        "page_token": "AQD9/Rn9eij9Pm39ED40/e4EuQbBea/ybCE7/PQ1yzQXAVoq7bxTVC%2BI1oJqeoRY",
        "user_ids": [
            "9b2fabg6"
        ]
    },
    "msg": "success"
}
```

## 响应码定义

### 成功码

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 200 | 0 | 请求成功 |

### 客户端错误码 (4xx)

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 400 | 40011 | page size is invalid |
| 400 | 40012 | page token is invalid error |

### 服务端错误码 (5xx)

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| - | - | 暂无 |

## 附录

### 相关链接

| 链接类型 | 链接 |
|----------|------|
| 应用权限配置 | [https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN](https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN) |
| 部门 ID 说明 | [https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview) |
| 权限范围校验 | [https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority](https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority) |
| 通用错误码 | [https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN) |

path: open-apis/contact-v3-users-basic_batch.md
content: # 获取用户姓名

## 注意事项

本接口不校验[通讯录授权范围](https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority)，将直接根据传入的用户 ID 返回对应基础信息（姓名），不受数据权限范围限制。

## 权限要求

### 必要权限

| 类型 | 名称 |
|------|------|
| 应用权限（开启任一即可） | 获取用户的基本信息 (contact:user.basic_profile:readonly) |

### 可选权限

| 类型 | 名称 |
|------|------|
| 字段权限（敏感字段） | 获取用户 user ID (contact:user.employee_id:readonly) |

> **说明**：敏感字段仅在开启对应权限后才会返回；如无需获取这些字段，不建议申请。

## 接口信息

| API 路径 | `https://open.feishu.cn/open-apis/contact/v3/users/basic_batch` |
|----------|----------------------------------------------------------------|
| 请求方法 | POST |
| 调用频率限制 | 5 次/秒 |
| 支持的应用类型 | Custom App、Store App |
| 文档地址 | [飞书开放平台](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/user/batch_get_name) |

## 接口请求

### 请求头

| 名称 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `Authorization` | string | 是 | `tenant_access_token` 或 `user_access_token`<br>值格式："Bearer `access_token`"<br>示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560"<br>**了解更多**：[如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use) |
| `Content-Type` | string | 是 | 固定值："application/json; charset=utf-8" |

### 请求参数

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `user_id_type` | string | 否 | 用户 ID 类型<br>可选值：<br>- `open_id`：标识一个用户在某个应用中的身份<br>- `union_id`：标识一个用户在某个应用开发商下的身份<br>- `user_id`：标识一个用户在某个租户内的身份<br>默认值：`open_id`<br>**权限要求**：当值为 `user_id` 时，需要获取用户 user ID (contact:user.employee_id:readonly) |

### 请求体

| 字段 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `user_ids` | array | 是 | 用户 ID。ID 类型与查询参数 `user_id_type` 保持一致。<br>长度范围：`1` ～ `10` |

### 请求示例

#### cURL 请求示例

```bash
curl -X POST 'https://open.feishu.cn/open-apis/contact/v3/users/basic_batch' \
  -H '[REDACTED_SECRET]' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "user_ids": ["ou_b3b46653c99f1f6177a478974bdabb72"]
  }'
```

#### Go 请求示例

```go
import (
	"context"

	"github.com/larksuite/oapi-sdk-go/v3"
	"github.com/larksuite/oapi-sdk-go/v3/service/contact/v3"
)

func main() {
	// 创建 Client
	client := lark.NewClient("appID", "appSecret")

	// 创建请求对象
	req := larkcontact.NewBatchGetNameUserReqBuilder().
		UserIdType(`open_id`).
		UserIdList([]string{
			"ou_b3b46653c99f1f6177a478974bdabb72",
		}).
		Build()

	// 发起请求
	resp, err := client.Contact.User.BatchGetName(context.Background(), req)
}
```

#### Java 请求示例

```java
import com.lark.oapi.Client;
import com.lark.oapi.service.contact.v3.model.*;
import com.lark.oapi.core.request.RequestOptions;

public class Main {
    public static void main(String arg[]) throws Exception {
        // 构建client
        Client client = Client.newBuilder("appId", "appSecret").build();

        // 创建请求对象
        BatchGetNameUserReq req = BatchGetNameUserReq.newBuilder()
                .userIdType("open_id")
                .userIdList(java.util.Arrays.asList("ou_b3b46653c99f1f6177a478974bdabb72"))
                .build();

        // 发起请求
        BatchGetNameUserResp resp = client.contact().user().batchGetName(req, RequestOptions.newBuilder().build());
    }
}
```

#### Python 请求示例

```python
import requests
import json

def main():
    url = "https://open.feishu.cn/open-apis/contact/v3/users/basic_batch"
    headers = {
        "Authorization": "Bearer tenant_access_token",
        "Content-Type": "application/json; charset=utf-8"
    }
    data = {
        "user_ids": ["ou_b3b46653c99f1f6177a478974bdabb72"]
    }
    
    response = requests.post(url, headers=headers, json=data)
    print(json.dumps(response.json(), indent=2, ensure_ascii=False))

if __name__ == "__main__":
    main()
```

## 接口响应

### 响应头

| 名称 | 类型 | 描述 |
|------|------|------|
| - | - | 无额外响应头字段 |

### 响应体

| 字段 | 类型 | 描述 |
|------|------|------|
| `code` | int | 错误码，非 0 表示失败 |
| `msg` | string | 错误描述 |
| `data` | object | 响应数据 |
| `users` | array | 用户信息列表 |

### 响应示例

```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "users": [
            {
                "user_id": "ou_b3b46653c99f1f6177a478974bdabb72",
                "name": "张三",
                "i18n_name": {
                    "zh_cn": "张三",
                    "ja_jp": "佐藤はるか",
                    "en_us": "Jason Zhang"
                }
            }
        ]
    }
}
```

## 响应码定义

### 成功码

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 200 | 0 | 请求成功 |

### 客户端错误码 (4xx)

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 400 | 40001 | param is invalid |

### 服务端错误码 (5xx)

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| - | - | 暂无 |

## 附录

### 相关链接

| 链接类型 | 链接 |
|----------|------|
| 应用权限配置 | [https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN](https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN) |
| 用户相关的 ID 概念 | [https://open.feishu.cn/document/home/user-identity-introduction/introduction](https://open.feishu.cn/document/home/user-identity-introduction/introduction) |
| 权限范围校验 | [https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority](https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority) |
| 通用错误码 | [https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN) |

path: open-apis/contact-v3-users-batch.md
content: # 批量获取用户信息

## 注意事项

该查询接口目前不返回用户的席位（assign_info）和部门路径信息（department_path）。

## 权限要求

### 必要权限

| 类型 | 名称 |
|------|------|
| 应用权限（开启任一即可） | 获取通讯录基本信息 (contact:contact.base:readonly) |

### 可选权限

| 类型 | 名称 |
|------|------|
| 字段权限（敏感字段） | 查询用户席位信息 (contact:user.assign_info:read) |
| 字段权限（敏感字段） | 获取用户基本信息 (contact:user.base:readonly) |
| 字段权限（敏感字段） | 获取用户组织架构信息 (contact:user.department:readonly) |
| 字段权限（敏感字段） | 获取成员所在部门路径 (contact:user.department_path:readonly) |
| 字段权限（敏感字段） | 查看成员的虚线上级 ID (contact:user.dotted_line_leader_info.read) |
| 字段权限（敏感字段） | 获取用户受雇信息 (contact:user.employee:readonly) |
| 字段权限（敏感字段） | 获取用户 user ID (contact:user.employee_id:readonly) |
| 字段权限（敏感字段） | 查看成员工号 (contact:user.employee_number:read) |
| 字段权限（敏感字段） | 获取用户性别 (contact:user.gender:readonly) |
| 字段权限（敏感字段） | 查看成员数据驻留地 (contact:user.user_geo) |
| 字段权限（敏感字段） | 获取用户手机号 (contact:user.phone:readonly) |
| 字段权限（敏感字段） | 分配用户席位 (contact:user.subscription_ids:write) |
| 字段权限（敏感字段） | 获取用户邮箱信息 (contact:user.email:readonly) |
| 字段权限（敏感字段） | 查询用户所属的工作序列 (contact:user.job_family:readonly) |
| 字段权限（敏感字段） | 查询用户职级 (contact:user.job_level:readonly) |
| 字段权限（敏感字段） | 以应用身份访问通讯录 (contact:contact:access_as_app) |
| 字段权限（敏感字段） | 读取通讯录 (contact:contact:readonly) |
| 字段权限（敏感字段） | 以应用身份读取通讯录 (contact:contact:readonly_as_app) |

> **说明**：敏感字段仅在开启对应权限后才会返回；如无需获取这些字段，不建议申请。

## 接口信息

| API 路径 | `https://open.feishu.cn/open-apis/contact/v3/users/batch` |
|----------|----------------------------------------------------------|
| 请求方法 | GET |
| 调用频率限制 | 1000 次/分钟、50 次/秒 |
| 支持的应用类型 | Custom App、Store App |
| 文档地址 | [飞书开放平台](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/user/batch_get) |

## 接口请求

### 请求头

| 名称 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `Authorization` | string | 是 | `tenant_access_token` 或 `user_access_token`<br>值格式："Bearer `access_token`"<br>示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560"<br>**了解更多**：[如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use) |
| `Content-Type` | string | 是 | 固定值："application/json; charset=utf-8" |

### 请求参数

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `user_ids` | array | 是 | 用户ID。ID 类型与查询参数 `user_id_type` 保持一致。<br>如需一次查询多个用户ID，可多次传递同一参数名，并且每次传递不同的参数值。例如：`https://{url}?user_ids={user_id1}&user_ids={user_id2}`。<br>单次最大请求可设置的用户 ID 数量上限为 50 |
| `user_id_type` | string | 否 | 用户 ID 类型<br>可选值：<br>- `open_id`：标识一个用户在某个应用中的身份<br>- `union_id`：标识一个用户在某个应用开发商下的身份<br>- `user_id`：标识一个用户在某个租户内的身份<br>默认值：`open_id`<br>**权限要求**：当值为 `user_id` 时，需要获取用户 user ID (contact:user.employee_id:readonly) |
| `department_id_type` | string | 否 | 指定查询结果中的部门 ID 类型<br>可选值：<br>- `open_department_id`：由系统自动生成的部门 ID<br>- `department_id`：支持用户自定义配置的部门 ID<br>默认值：`open_department_id` |

### 请求体

无请求体（GET 请求）

### 请求示例

#### cURL 请求示例

```bash
curl -X GET 'https://open.feishu.cn/open-apis/contact/v3/users/batch?user_ids=ou_xxx&user_ids=ou_yyy&user_id_type=open_id&department_id_type=open_department_id' \
  -H '[REDACTED_SECRET]' \
  -H 'Content-Type: application/json; charset=utf-8'
```

#### Go 请求示例

```go
import (
	"context"

	"github.com/larksuite/oapi-sdk-go/v3"
	"github.com/larksuite/oapi-sdk-go/v3/service/contact/v3"
)

func main() {
	// 创建 Client
	client := lark.NewClient("appID", "appSecret")

	// 创建请求对象
	req := larkcontact.NewBatchGetUserReqBuilder().
		UserIdList([]string{
			"7be5fg",
		}).
		UserIdType(`open_id`).
		DepartmentIdType(`open_department_id`).
		Build()

	// 发起请求
	resp, err := client.Contact.User.BatchGet(context.Background(), req)
}
```

#### Java 请求示例

```java
import com.lark.oapi.Client;
import com.lark.oapi.service.contact.v3.model.*;
import com.lark.oapi.core.request.RequestOptions;

public class Main {
    public static void main(String arg[]) throws Exception {
        // 构建client
        Client client = Client.newBuilder("appId", "appSecret").build();

        // 创建请求对象
        BatchGetUserReq req = BatchGetUserReq.newBuilder()
                .userIdList(java.util.Arrays.asList("7be5fg"))
                .userIdType("open_id")
                .departmentIdType("open_department_id")
                .build();

        // 发起请求
        BatchGetUserResp resp = client.contact().user().batchGet(req, RequestOptions.newBuilder().build());
    }
}
```

#### Python 请求示例

```python
import requests
import json

def main():
    url = "https://open.feishu.cn/open-apis/contact/v3/users/batch"
    headers = {
        "Authorization": "Bearer tenant_access_token",
        "Content-Type": "application/json; charset=utf-8"
    }
    params = {
        "user_ids": ["ou_xxx", "ou_yyy"],
        "user_id_type": "open_id",
        "department_id_type": "open_department_id"
    }
    
    response = requests.get(url, headers=headers, params=params)
    print(json.dumps(response.json(), indent=2, ensure_ascii=False))

if __name__ == "__main__":
    main()
```

## 接口响应

### 响应头

| 名称 | 类型 | 描述 |
|------|------|------|
| - | - | 无额外响应头字段 |

### 响应体

| 字段 | 类型 | 描述 |
|------|------|------|
| `code` | int | 错误码，非 0 表示失败 |
| `msg` | string | 错误描述 |
| `data` | object | 响应数据 |
| `items` | array | 查询到的用户信息列表 |

### 响应示例

```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "items": [
            {
                "union_id": "on_94a1ee5551019f18cd73d9f111898cf2",
                "user_id": "3e3cf96b",
                "open_id": "ou_7dab8a3d3cdcc9da365777c7ad535d62",
                "name": "张三",
                "en_name": "San Zhang",
                "nickname": "Alex Zhang",
                "email": "[REDACTED_SECRET]",
                "mobile": "13011111111",
                "mobile_visible": false,
                "gender": 1,
                "avatar_key": "2500c7a9-5fff-4d9a-a2de-3d59614ae28g",
                "avatar": {
                    "avatar_72": "https://foo.icon.com/xxxx",
                    "avatar_240": "https://foo.icon.com/xxxx",
                    "avatar_640": "https://foo.icon.com/xxxx",
                    "avatar_origin": "https://foo.icon.com/xxxx"
                },
                "status": {
                    "is_frozen": false,
                    "is_resigned": false,
                    "is_activated": true,
                    "is_exited": false,
                    "is_unjoin": false
                },
                "department_ids": [
                    "od-4e6ac4d14bcd5071a37a39de902c7141"
                ],
                "leader_user_id": "ou_7dab8a3d3cdcc9da365777c7ad535d62",
                "city": "杭州",
                "country": "CN",
                "work_station": "北楼-H34",
                "join_time": 2147483647,
                "is_tenant_manager": false,
                "employee_no": "1",
                "employee_type": 1,
                "orders": [
                    {
                        "department_id": "od-4e6ac4d14bcd5071a37a39de902c7141",
                        "user_order": 100,
                        "department_order": 100,
                        "is_primary_dept": true
                    }
                ],
                "custom_attrs": [
                    {
                        "type": "TEXT",
                        "id": "DemoId",
                        "value": {
                            "text": "DemoText",
                            "url": "http://www.fs.cn",
                            "pc_url": "http://www.fs.cn",
                            "option_id": "option",
                            "option_value": "option",
                            "name": "name",
                            "picture_url": "https://xxxxxxxxxxxxxxxxxx",
                            "generic_user": {
                                "id": "9b2fabg5",
                                "type": 1
                            }
                        }
                    }
                ],
                "enterprise_email": "[REDACTED_SECRET]",
                "job_title": "xxxxx",
                "is_frozen": false,
                "geo": "cn",
                "job_level_id": "mga5oa8ayjlp9rb",
                "job_family_id": "mga5oa8ayjlp9rb",
                "subscription_ids": [
                    "23213213213123123"
                ],
                "assign_info": [
                    {
                        "subscription_id": "7079609167680782300",
                        "license_plan_key": "suite_enterprise_e5",
                        "product_name": "旗舰版 E5",
                        "i18n_name": {
                            "zh_cn": "zh_cn_name",
                            "ja_jp": "ja_jp_name",
                            "en_us": "en_name"
                        },
                        "start_time": "1674981000",
                        "end_time": "1674991000"
                    }
                ],
                "department_path": [
                    {
                        "department_id": "od-4e6ac4d14bcd5071a37a39de902c7141",
                        "department_name": {
                            "name": "测试部门名1",
                            "i18n_name": {
                                "zh_cn": "测试部门名1",
                                "ja_jp": "試験部署名 1",
                                "en_us": "Testing department name 1"
                            }
                        },
                        "department_path": {
                            "department_ids": [
                                "od-4e6ac4d14bcd5071a37a39de902c7141"
                            ],
                            "department_path_name": {
                                "name": "测试部门名1",
                                "i18n_name": {
                                    "zh_cn": "测试部门名1",
                                    "ja_jp": "試験部署名 1",
                                    "en_us": "Testing department name 1"
                                }
                            }
                        }
                    }
                ],
                "dotted_line_leader_user_ids": [
                    "ou_7dab8a3d3cdcc9da365777c7ad535d62"
                ]
            }
        ]
    }
}
```

## 响应码定义

### 成功码

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 200 | 0 | 请求成功 |

### 客户端错误码 (4xx)

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 400 | 40001 | invalid parameter |
| 400 | 41050 | no user authority |
| 403 | 40004 | no dept. authority |

### 服务端错误码 (5xx)

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| - | - | 暂无 |

## 附录

### 相关链接

| 链接类型 | 链接 |
|----------|------|
| 应用权限配置 | [https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN](https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN) |
| 用户相关的 ID 概念 | [https://open.feishu.cn/document/home/user-identity-introduction/introduction](https://open.feishu.cn/document/home/user-identity-introduction/introduction) |
| 部门 ID 说明 | [https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview) |
| 权限范围校验 | [https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority](https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority) |
| 通用错误码 | [https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN) |

path: open-apis/contact-v3-users-batch_get_id.md
content: # 通过手机号或邮箱获取用户 ID

## 注意事项

请求后不返回用户 ID 的可能原因：

- 请求头 Authorization 传入的 tenant_access_token 有误。例如，tenant_access_token 对应的应用与实际所需应用不一致。
- 输入的手机号或者邮箱不存在。
- 应用未开通 **获取用户 user ID** API 权限。
- 应用无权限查看用户信息。你需要在应用详情页为应用配置数据权限，具体说明参见[配置应用数据权限](https://open.feishu.cn/document/home/introduction-to-scope-and-authorization/configure-app-data-permissions)。
- 使用企业邮箱查询将无法返回用户 ID，必须使用用户的邮箱地址。
- 所查询的用户已离职，如果请求参数 include_resigned 取值为 false，则不会返回离职用户 ID。

## 权限要求

### 必要权限

| 类型 | 名称 |
|------|------|
| 应用权限（开启任一即可） | 通过手机号或邮箱获取用户 ID (contact:user.id:readonly) |

### 可选权限

| 类型 | 名称 |
|------|------|
| 字段权限（敏感字段） | 获取用户受雇信息 (contact:user.employee:readonly) |
| 字段权限（敏感字段） | 获取用户 user ID (contact:user.employee_id:readonly) |
| 字段权限（敏感字段） | 以应用身份访问通讯录 (contact:contact:access_as_app) |
| 字段权限（敏感字段） | 读取通讯录 (contact:contact:readonly) |
| 字段权限（敏感字段） | 以应用身份读取通讯录 (contact:contact:readonly_as_app) |

> **说明**：敏感字段仅在开启对应权限后才会返回；如无需获取这些字段，不建议申请。

## 接口信息

| API 路径 | `https://open.feishu.cn/open-apis/contact/v3/users/batch_get_id` |
|----------|-------------------------------------------------------------------|
| 请求方法 | POST |
| 调用频率限制 | 1000 次/分钟、50 次/秒 |
| 支持的应用类型 | Custom App、Store App |
| 文档地址 | [飞书开放平台](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/user/batch_get_id) |

## 接口请求

### 请求头

| 名称 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `Authorization` | string | 是 | `tenant_access_token`<br>值格式："Bearer `access_token`"<br>示例值："Bearer t-7f1bcd13fc57d46bac21793a18e560"<br>**了解更多**：[如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use) |
| `Content-Type` | string | 是 | 固定值："application/json; charset=utf-8" |

### 请求参数

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `user_id_type` | string | 否 | 用户 ID 类型<br>可选值：<br>- `open_id`：标识一个用户在某个应用中的身份<br>- `union_id`：标识一个用户在某个应用开发商下的身份<br>- `user_id`：标识一个用户在某个租户内的身份<br>默认值：`open_id`<br>**权限要求**：当值为 `user_id` 时，需要获取用户 user ID (contact:user.employee_id:readonly) |

### 请求体

| 字段 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `emails` | array | 否 | 要查询的用户邮箱，最多可传入 50 条。<br>注意：<br>- 不支持企业邮箱<br>- emails 与 mobiles 两个参数相互独立<br>- 本接口返回的用户 ID 数量为 emails 数量与 mobiles 数量之和<br>最大长度：`50` |
| `mobiles` | array | 否 | 要查询的用户手机号，最多可传入 50 条。<br>注意：<br>- 非中国大陆地区的手机号需要添加以 "+" 开头的国家或地区代码<br>- emails 与 mobiles 两个参数相互独立<br>- 本接口返回的用户 ID 数量为 emails 数量与 mobiles 数量之和<br>最大长度：`50` |
| `include_resigned` | boolean | 否 | 查询结果是否包含离职员工的用户信息<br>可选值：<br>- `true`：包含<br>- `false`：不包含<br>默认值：`false` |

### 请求示例

#### cURL 请求示例

```bash
curl -X POST 'https://open.feishu.cn/open-apis/contact/v3/users/batch_get_id?user_id_type=open_id' \
  -H '[REDACTED_SECRET]' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "emails": ["[REDACTED_SECRET]", "[REDACTED_SECRET]"],
    "mobiles": ["13011111111", "13022222222"],
    "include_resigned": true
  }'
```

#### Go 请求示例

```go
import (
	"context"

	"github.com/larksuite/oapi-sdk-go/v3"
	"github.com/larksuite/oapi-sdk-go/v3/service/contact/v3"
)

func main() {
	// 创建 Client
	client := lark.NewClient("appID", "appSecret")

	// 创建请求对象
	req := larkcontact.NewBatchGetIdUserReqBuilder().
		UserIdType(`open_id`).
		Body(larkcontact.NewBatchGetIdUserReqBodyBuilder().
			Emails([]string{`[REDACTED_SECRET]`, `[REDACTED_SECRET]`}.
			Mobiles([]string{`13812345678`, `13812345679`}.
			Build()).
		Build()

	// 发起请求
	resp, err := client.Contact.User.BatchGetId(context.Background(), req)
}
```

#### Java 请求示例

```java
import com.lark.oapi.Client;
import com.lark.oapi.core.request.RequestOptions;
import com.lark.oapi.service.contact.v3.model.BatchGetIdUserReq;
import com.lark.oapi.service.contact.v3.model.BatchGetIdUserReqBody;
import com.lark.oapi.service.contact.v3.model.BatchGetIdUserResp;

public class Main {
    public static void main(String arg[]) throws Exception {
        // 构建client
        Client client = Client.newBuilder("appId", "appSecret").build();

        // 创建请求对象
        BatchGetIdUserReq req = BatchGetIdUserReq.newBuilder()
                .userIdType("open_id")
                .batchGetIdUserReqBody(BatchGetIdUserReqBody.newBuilder()
                        .emails(new String[]{"[REDACTED_SECRET]", "[REDACTED_SECRET]"})
                        .mobiles(new String[]{"13812345678", "13812345679"})
                        .build())
                .build();

        // 发起请求
        BatchGetIdUserResp resp = client.contact().user().batchGetId(req, RequestOptions.newBuilder().build());
    }
}
```

#### Python 请求示例

```python
import requests
import json

def main():
    url = "https://open.feishu.cn/open-apis/contact/v3/users/batch_get_id"
    headers = {
        "Authorization": "Bearer tenant_access_token",
        "Content-Type": "application/json; charset=utf-8"
    }
    params = {
        "user_id_type": "open_id"
    }
    data = {
        "emails": ["[REDACTED_SECRET]", "[REDACTED_SECRET]"],
        "mobiles": ["13011111111", "13022222222"],
        "include_resigned": True
    }
    
    response = requests.post(url, headers=headers, params=params, json=data)
    print(json.dumps(response.json(), indent=2, ensure_ascii=False))

if __name__ == "__main__":
    main()
```

## 接口响应

### 响应头

| 名称 | 类型 | 描述 |
|------|------|------|
| - | - | 无额外响应头字段 |

### 响应体

| 字段 | 类型 | 描述 |
|------|------|------|
| `code` | int | 错误码，非 0 表示失败 |
| `msg` | string | 错误描述 |
| `data` | object | 响应数据 |
| `user_list` | array | 手机号或者邮箱对应的用户 ID 信息列表 |

### 响应示例

```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "user_list": [
            {
                "user_id": "ou_979112345678741d29069abcdef01234",
                "email": "[REDACTED_SECRET]",
                "status": {
                    "is_frozen": false,
                    "is_resigned": false,
                    "is_activated": true,
                    "is_exited": false,
                    "is_unjoin": false
                }
            },
            {
                "user_id": "ou_919112245678741d29069abcdef02345",
                "email": "[REDACTED_SECRET]",
                "status": {
                    "is_frozen": false,
                    "is_resigned": false,
                    "is_activated": true,
                    "is_exited": false,
                    "is_unjoin": false
                }
            },
            {
                "user_id": "ou_46a087654321a1dc920ffab8fedc3456",
                "mobile": "130xxxx1111",
                "status": {
                    "is_frozen": false,
                    "is_resigned": false,
                    "is_activated": true,
                    "is_exited": false,
                    "is_unjoin": false
                }
            },
            {
                "user_id": "ou_01b081675121a1dc920ffab97cdc4567",
                "mobile": "130xxxx2222",
                "status": {
                    "is_frozen": false,
                    "is_resigned": false,
                    "is_activated": true,
                    "is_exited": false,
                    "is_unjoin": false
                }
            }
        ]
    }
}
```

## 响应码定义

### 成功码

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 200 | 0 | 请求成功 |

### 客户端错误码 (4xx)

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| - | - | 暂无（具体错误码请参考[通用错误码](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN)） |

### 服务端错误码 (5xx)

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| - | - | 暂无 |

## 附录

### 相关链接

| 链接类型 | 链接 |
|----------|------|
| 应用权限配置 | [https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN](https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN) |
| 用户相关的 ID 概念 | [https://open.feishu.cn/document/home/user-identity-introduction/introduction](https://open.feishu.cn/document/home/user-identity-introduction/introduction) |
| 配置应用数据权限 | [https://open.feishu.cn/document/home/introduction-to-scope-and-authorization/configure-app-data-permissions](https://open.feishu.cn/document/home/introduction-to-scope-and-authorization/configure-app-data-permissions) |
| 通用错误码 | [https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN) |

path: open-apis/contact-v3-users-find_by_department.md
content: # 获取部门直属用户列表

## 注意事项

- 使用用户身份（user_access_token）调用该接口时，接口将根据该用户的组织架构可见范围进行过滤，仅返回组织架构可见范围内的用户数据。
- 使用应用身份（tenant_access_token）调用该接口时，接口将根据应用的通讯录权限范围进行过滤。如果请求的部门 ID 为 0（即根部门），则接口会校验应用是否具有全员的通讯录权限；如果请求的是非 0 的部门 ID，则会校验应用是否具有该部门的通讯录权限。无权限时，接口会返回无权限的报错信息；有权限则返回对应部门下的直属用户列表。
- 使用应用身份（tenant_access_token）调用本接口时，响应结果中不会返回部门路径字段（department_path）。如需获取部门路径字段值，请为应用申请 **获取成员所在部门路径（contact:user.department_path:readonly）** API 权限，并使用用户身份（user_access_token）调用接口。

关于用户组织架构可见范围和通讯录权限范围的更多信息，可参见[权限范围资源介绍](https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority)。

## 权限要求

### 必要权限

| 类型 | 名称 |
|------|------|
| 应用权限（开启任一即可） | 获取通讯录基本信息 (contact:contact.base:readonly) |
| 应用权限（开启任一即可） | 获取通讯录部门组织架构信息 (contact:department.organize:readonly) |
| 应用权限（开启任一即可） | 以应用身份访问通讯录 (contact:contact:access_as_app) |
| 应用权限（开启任一即可） | 读取通讯录 (contact:contact:readonly) |
| 应用权限（开启任一即可） | 以应用身份读取通讯录 (contact:contact:readonly_as_app) |

### 可选权限

| 类型 | 名称 |
|------|------|
| 字段权限（敏感字段） | 获取用户基本信息 (contact:user.base:readonly) |
| 字段权限（敏感字段） | 获取用户组织架构信息 (contact:user.department:readonly) |
| 字段权限（敏感字段） | 获取成员所在部门路径 (contact:user.department_path:readonly) |
| 字段权限（敏感字段） | 查看成员的虚线上级 ID (contact:user.dotted_line_leader_info.read) |
| 字段权限（敏感字段） | 获取用户受雇信息 (contact:user.employee:readonly) |
| 字段权限（敏感字段） | 查看成员工号 (contact:user.employee_number:read) |
| 字段权限（敏感字段） | 获取用户性别 (contact:user.gender:readonly) |
| 字段权限（敏感字段） | 获取用户邮箱信息 (contact:user.email:readonly) |
| 字段权限（敏感字段） | 获取用户手机号 (contact:user.phone:readonly) |
| 字段权限（敏感字段） | 获取用户 user ID (contact:user.employee_id:readonly) |
| 字段权限（敏感字段） | 查看成员数据驻留地 (contact:user.user_geo) |
| 字段权限（敏感字段） | 查询用户职级 (contact:user.job_level:readonly) |
| 字段权限（敏感字段） | 查询用户所属的工作序列 (contact:user.job_family:readonly) |

> **说明**：敏感字段仅在开启对应权限后才会返回；如无需获取这些字段，不建议申请。

## 接口信息

| API 路径 | `https://open.feishu.cn/open-apis/contact/v3/users/find_by_department` |
|----------|------------------------------------------------------------------------|
| 请求方法 | GET |
| 调用频率限制 | 1000 次/分钟、50 次/秒 |
| 支持的应用类型 | Custom App、Store App |
| 文档地址 | [飞书开放平台](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/user/find_by_department) |

## 接口请求

### 请求头

| 名称 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `Authorization` | string | 是 | `tenant_access_token` 或 `user_access_token`<br>值格式："Bearer `access_token`"<br>示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560"<br>**了解更多**：[如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use) |
| `Content-Type` | string | 是 | 固定值："application/json; charset=utf-8" |

### 请求参数

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `user_id_type` | string | 否 | 用户 ID 类型<br>可选值：<br>- `open_id`：标识一个用户在某个应用中的身份<br>- `union_id`：标识一个用户在某个应用开发商下的身份<br>- `user_id`：标识一个用户在某个租户内的身份<br>默认值：`open_id`<br>**权限要求**：当值为 `user_id` 时，需要获取用户 user ID (contact:user.employee_id:readonly) |
| `department_id_type` | string | 否 | 部门 ID 类型<br>可选值：<br>- `department_id`：支持用户自定义配置的部门 ID<br>- `open_department_id`：由系统自动生成的部门 ID<br>默认值：`open_department_id` |
| `department_id` | string | 是 | 部门 ID，ID 类型与 `department_id_type` 的取值保持一致。<br>说明：<br>- 根部门的部门 ID 为 0<br>- 可调用搜索部门接口获取对应的部门 ID |
| `page_size` | int | 否 | 分页大小<br>默认值：`10`<br>数据校验规则：<br>- 最大值：`50` |
| `page_token` | string | 否 | 分页标记，第一次请求不填，表示从头开始遍历 |

### 请求体

无请求体（GET 请求）

### 请求示例

#### cURL 请求示例

```bash
curl -X GET 'https://open.feishu.cn/open-apis/contact/v3/users?department_id=od_xxx&page_size=10&page_token=AQD9/...' \
  -H '[REDACTED_SECRET]' \
  -H 'Content-Type: application/json; charset=utf-8'
```

#### Go 请求示例

```go
import (
	"context"

	"github.com/larksuite/oapi-sdk-go/v3"
	"github.com/larksuite/oapi-sdk-go/v3/service/contact/v3"
)

func main() {
	// 创建 Client
	client := lark.NewClient("appID", "appSecret")

	// 创建请求对象
	req := larkcontact.NewFindByDepartmentUserReqBuilder().
		UserIdType(`open_id`).
		DepartmentIdType(`open_department_id`).
		DepartmentId(`od-xxxxxxxxxxxxx`).
		PageSize(10).
		Build()

	// 发起请求
	resp, err := client.Contact.User.FindByDepartment(context.Background(), req)
}
```

#### Java 请求示例

```java
import com.lark.oapi.Client;
import com.lark.oapi.service.contact.v3.model.*;
import com.lark.oapi.core.request.RequestOptions;

public class Main {
    public static void main(String arg[]) throws Exception {
        // 构建client
        Client client = Client.newBuilder("appId", "appSecret").build();

        // 创建请求对象
        FindByDepartmentUserReq req = FindByDepartmentUserReq.newBuilder()
                .userIdType("open_id")
                .departmentIdType("open_department_id")
                .departmentId("od-xxxxxxxxxxxxx")
                .pageSize(10)
                .build();

        // 发起请求
        FindByDepartmentUserResp resp = client.contact().user().findByDepartment(req, RequestOptions.newBuilder().build());
    }
}
```

#### Python 请求示例

```python
import requests
import json

def main():
    url = "https://open.feishu.cn/open-apis/contact/v3/users/find_by_department"
    headers = {
        "Authorization": "Bearer tenant_access_token",
        "Content-Type": "application/json; charset=utf-8"
    }
    params = {
        "department_id": "od-xxxxxxxxxxxxx",
        "department_id_type": "open_department_id",
        "user_id_type": "open_id",
        "page_size": 10
    }
    
    response = requests.get(url, headers=headers, params=params)
    print(json.dumps(response.json(), indent=2, ensure_ascii=False))

if __name__ == "__main__":
    main()
```

## 接口响应

### 响应头

| 名称 | 类型 | 描述 |
|------|------|------|
| - | - | 无额外响应头字段 |

### 响应体

| 字段 | 类型 | 描述 |
|------|------|------|
| `code` | int | 错误码，非 0 表示失败 |
| `msg` | string | 错误描述 |
| `data` | object | 响应数据 |
| `has_more` | boolean | 是否还有更多项 |
| `page_token` | string | 分页标记，当 has_more 为 true 时返回 |
| `items` | array | 用户信息列表 |

### 响应示例

```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "has_more": true,
        "page_token": "AQD9/Rn9eij9Pm39ED40/RD/cIFmu77WxpxPB/2oHfQLZ%2BG8JG6tK7%2BZnHiT7COhD2hMSICh/eBl7cpzU6JEC3J7COKNe4jrQ8ExwBCR",
        "items": [
            {
                "union_id": "on_94a1ee5551019f18cd73d9f111898cf2",
                "user_id": "3e3cf96b",
                "open_id": "ou_7dab8a3d3cdcc9da365777c7ad535d62",
                "name": "张三",
                "en_name": "San Zhang",
                "nickname": "Alex Zhang",
                "email": "[REDACTED_SECRET]",
                "mobile": "13011111111",
                "mobile_visible": false,
                "gender": 1,
                "avatar_key": "2500c7a9-5fff-4d9a-a2de-3d59614ae28g",
                "avatar": {
                    "avatar_72": "https://foo.icon.com/xxxx",
                    "avatar_240": "https://foo.icon.com/xxxx",
                    "avatar_640": "https://foo.icon.com/xxxx",
                    "avatar_origin": "https://foo.icon.com/xxxx"
                },
                "status": {
                    "is_frozen": false,
                    "is_resigned": false,
                    "is_activated": true,
                    "is_exited": false,
                    "is_unjoin": false
                },
                "department_ids": [
                    "od-4e6ac4d14bcd5071a37a39de902c7141"
                ],
                "leader_user_id": "ou_7dab8a3d3cdcc9da365777c7ad535d62",
                "city": "杭州",
                "country": "CN",
                "work_station": "北楼-H34",
                "join_time": 2147483647,
                "is_tenant_manager": false,
                "employee_no": "1",
                "employee_type": 1,
                "orders": [
                    {
                        "department_id": "od-4e6ac4d14bcd5071a37a39de902c7141",
                        "user_order": 100,
                        "department_order": 100,
                        "is_primary_dept": true
                    }
                ],
                "custom_attrs": [
                    {
                        "type": "TEXT",
                        "id": "DemoId",
                        "value": {
                            "text": "DemoText",
                            "url": "http://www.fs.cn",
                            "pc_url": "http://www.fs.cn",
                            "option_id": "edcvfrtg",
                            "option_value": "option",
                            "name": "name",
                            "picture_url": "https://xxxxxxxxxxxxxxxxxx",
                            "generic_user": {
                                "id": "9b2fabg5",
                                "type": 1
                            }
                        }
                    }
                ],
                "enterprise_email": "[REDACTED_SECRET]",
                "job_title": "xxxxx",
                "is_frozen": false,
                "geo": "cn",
                "job_level_id": "mga5oa8ayjlp9rb",
                "job_family_id": "mga5oa8ayjlp9rb",
                "department_path": [
                    {
                        "department_id": "od-4e6ac4d14bcd5071a37a39de902c7141",
                        "department_name": {
                            "name": "测试部门名1",
                            "i18n_name": {
                                "zh_cn": "测试部门名1",
                                "ja_jp": "試験部署名 1",
                                "en_us": "Test department name 1"
                            }
                        },
                        "department_path": {
                            "department_ids": [
                                "od-4e6ac4d14bcd5071a37a39de902c7141"
                            ],
                            "department_path_name": {
                                "name": "测试部门名1",
                                "i18n_name": {
                                    "zh_cn": "测试部门名1",
                                    "ja_jp": "試験部署名 1",
                                    "en_us": "Test department name 1"
                                }
                            }
                        }
                    }
                ],
                "dotted_line_leader_user_ids": [
                    "ou_7dab8a3d3cdcc9da365777c7ad535d62"
                ]
            }
        ]
    }
}
```

## 响应码定义

### 成功码

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 200 | 0 | 请求成功 |

### 客户端错误码 (4xx)

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 400 | 41050 | no user authority error |
| 400 | 40011 | page size is invalid |
| 400 | 40012 | page token is invalid error |
| 403 | 40004 | no dept authority error |

### 服务端错误码 (5xx)

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| - | - | 暂无 |

## 附录

### 相关链接

| 链接类型 | 链接 |
|----------|------|
| 应用权限配置 | [https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN](https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN) |
| 用户相关的 ID 概念 | [https://open.feishu.cn/document/home/user-identity-introduction/introduction](https://open.feishu.cn/document/home/user-identity-introduction/introduction) |
| 部门 ID 说明 | [https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview) |
| 权限范围校验 | [https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority](https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority) |
| 通用错误码 | [https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN) |

path: open-apis/contact-v3-users-user_id.md
content: # 获取单个用户信息

## 注意事项

使用应用身份（tenant_access_token）调用本接口时，响应结果中不会返回部门路径字段（department_path）。因此，如需获取部门路径字段值，请为应用申请 **获取成员所在部门路径** API 权限，并使用用户身份（user_access_token）调用接口。

## 权限要求

### 必要权限

| 类型 | 名称 |
|------|------|
| 应用权限（开启任一即可） | 获取通讯录基本信息 (contact:contact.base:readonly) |
| 应用权限（开启任一即可） | 以应用身份访问通讯录 (contact:contact:access_as_app) |
| 应用权限（开启任一即可） | 读取通讯录 (contact:contact:readonly) |
| 应用权限（开启任一即可） | 以应用身份读取通讯录 (contact:contact:readonly_as_app) |

### 可选权限

| 类型 | 名称 |
|------|------|
| 字段权限（敏感字段） | 查询用户席位信息 (contact:user.assign_info:read) |
| 字段权限（敏感字段） | 获取用户基本信息 (contact:user.base:readonly) |
| 字段权限（敏感字段） | 获取用户组织架构信息 (contact:user.department:readonly) |
| 字段权限（敏感字段） | 获取成员所在部门路径 (contact:user.department_path:readonly) |
| 字段权限（敏感字段） | 查看成员的虚线上级 ID (contact:user.dotted_line_leader_info.read) |
| 字段权限（敏感字段） | 获取用户受雇信息 (contact:user.employee:readonly) |
| 字段权限（敏感字段） | 查看成员工号 (contact:user.employee_number:read) |
| 字段权限（敏感字段） | 获取用户性别 (contact:user.gender:readonly) |
| 字段权限（敏感字段） | 获取用户邮箱信息 (contact:user.email:readonly) |
| 字段权限（敏感字段） | 查看成员数据驻留地 (contact:user.user_geo) |
| 字段权限（敏感字段） | 获取用户 user ID (contact:user.employee_id:readonly) |
| 字段权限（敏感字段） | 查询用户职级 (contact:user.job_level:readonly) |
| 字段权限（敏感字段） | 获取用户手机号 (contact:user.phone:readonly) |
| 字段权限（敏感字段） | 查询用户所属的工作序列 (contact:user.job_family:readonly) |

> **说明**：敏感字段仅在开启对应权限后才会返回；如无需获取这些字段，不建议申请。

## 接口信息

| API 路径 | `https://open.feishu.cn/open-apis/contact/v3/users/:user_id` |
|----------|-------------------------------------------------------------|
| 请求方法 | GET |
| 调用频率限制 | 1000 次/分钟、50 次/秒 |
| 支持的应用类型 | Custom App、Store App |
| 文档地址 | [飞书开放平台](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/user/get) |

## 接口请求

### 请求头

| 名称 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `Authorization` | string | 是 | `tenant_access_token` 或 `user_access_token`<br>值格式："Bearer `access_token`"<br>示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560"<br>**了解更多**：[如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use) |
| `Content-Type` | string | 是 | 固定值："application/json; charset=utf-8" |

### 请求参数

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `user_id` | string | 是 | 用户ID。ID 类型与查询参数 `user_id_type` 保持一致。 |
| `user_id_type` | string | 否 | 用户 ID 类型<br>可选值：<br>- `open_id`：标识一个用户在某个应用中的身份<br>- `union_id`：标识一个用户在某个应用开发商下的身份<br>- `user_id`：标识一个用户在某个租户内的身份<br>默认值：`open_id`<br>**权限要求**：当值为 `user_id` 时，需要获取用户 user ID (contact:user.employee_id:readonly) |
| `department_id_type` | string | 否 | 指定查询结果中的部门 ID 类型<br>可选值：<br>- `department_id`：支持用户自定义配置的部门 ID<br>- `open_department_id`：由系统自动生成的部门 ID<br>默认值：`open_department_id` |

### 请求体

无请求体（GET 请求）

### 请求示例

#### cURL 请求示例

```bash
curl -X GET 'https://open.feishu.cn/open-apis/contact/v3/users/ou_xxx?user_id_type=open_id&department_id_type=open_department_id' \
  -H '[REDACTED_SECRET]' \
  -H 'Content-Type: application/json; charset=utf-8'
```

#### Go 请求示例

```go
import (
	"context"

	"github.com/larksuite/oapi-sdk-go/v3"
	"github.com/larksuite/oapi-sdk-go/v3/service/contact/v3"
)

func main() {
	// 创建 Client
	client := lark.NewClient("appID", "appSecret")

	// 创建请求对象
	req := larkcontact.NewGetUserReqBuilder().
		UserId(`7be5fg9a`).
		UserIdType(`open_id`).
		DepartmentIdType(`open_department_id`).
		Build()

	// 发起请求
	resp, err := client.Contact.User.Get(context.Background(), req)
}
```

#### Java 请求示例

```java
import com.lark.oapi.Client;
import com.lark.oapi.service.contact.v3.model.*;
import com.lark.oapi.core.request.RequestOptions;

public class Main {
    public static void main(String arg[]) throws Exception {
        // 构建client
        Client client = Client.newBuilder("appId", "appSecret").build();

        // 创建请求对象
        GetUserReq req = GetUserReq.newBuilder()
                .userId("7be5fg9a")
                .userIdType("open_id")
                .departmentIdType("open_department_id")
                .build();

        // 发起请求
        GetUserResp resp = client.contact().user().get(req, RequestOptions.newBuilder().build());
    }
}
```

#### Python 请求示例

```python
import requests
import json

def main():
    url = "https://open.feishu.cn/open-apis/contact/v3/users/ou_xxx"
    headers = {
        "Authorization": "Bearer tenant_access_token",
        "Content-Type": "application/json; charset=utf-8"
    }
    params = {
        "user_id_type": "open_id",
        "department_id_type": "open_department_id"
    }
    
    response = requests.get(url, headers=headers, params=params)
    print(json.dumps(response.json(), indent=2, ensure_ascii=False))

if __name__ == "__main__":
    main()
```

## 接口响应

### 响应头

| 名称 | 类型 | 描述 |
|------|------|------|
| - | - | 无额外响应头字段 |

### 响应体

| 字段 | 类型 | 描述 |
|------|------|------|
| `code` | int | 错误码，非 0 表示失败 |
| `msg` | string | 错误描述 |
| `data` | object | 响应数据 |
| `user` | object | 用户信息 |

### 响应示例

```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "user": {
            "union_id": "on_94a1ee5551019f18cd73d9f111898cf2",
            "user_id": "3e3cf96b",
            "open_id": "ou_7dab8a3d3cdcc9da365777c7ad535d62",
            "name": "张三",
            "en_name": "San Zhang",
            "nickname": "Alex Zhang",
            "email": "[REDACTED_SECRET]",
            "mobile": "13011111111",
            "mobile_visible": false,
            "gender": 1,
            "avatar": {
                "avatar_72": "https://foo.icon.com/xxxx",
                "avatar_240": "https://foo.icon.com/xxxx",
                "avatar_640": "https://foo.icon.com/xxxx",
                "avatar_origin": "https://foo.icon.com/xxxx"
            },
            "status": {
                "is_frozen": false,
                "is_resigned": false,
                "is_activated": true,
                "is_exited": false,
                "is_unjoin": false
            },
            "department_ids": [
                "od-4e6ac4d14bcd5071a37a39de902c7141"
            ],
            "leader_user_id": "ou_7dab8a3d3cdcc9da365777c7ad535d62",
            "city": "杭州",
            "country": "CN",
            "work_station": "北楼-H34",
            "join_time": 2147483647,
            "is_tenant_manager": false,
            "employee_no": "1",
            "employee_type": 1,
            "orders": [
                {
                    "department_id": "od-4e6ac4d14bcd5071a37a39de902c7141",
                    "user_order": 100,
                    "department_order": 100,
                    "is_primary_dept": true
                }
            ],
            "custom_attrs": [
                {
                    "type": "TEXT",
                    "id": "DemoId",
                    "value": {
                        "text": "DemoText",
                        "url": "http://www.fs.cn",
                        "pc_url": "http://www.fs.cn",
                        "option_value": "option",
                        "name": "name",
                        "picture_url": "https://xxxxxxxxxxxxxxxxxx",
                        "generic_user": {
                            "id": "9b2fabg5",
                            "type": 1
                        }
                    }
                }
            ],
            "enterprise_email": "[REDACTED_SECRET]",
            "job_title": "xxxxx",
            "geo": "cn",
            "job_level_id": "mga5oa8ayjlp9rb",
            "job_family_id": "mga5oa8ayjlp9rb",
            "assign_info": [
                {
                    "subscription_id": "7079609167680782300",
                    "license_plan_key": "suite_enterprise_e5",
                    "product_name": "旗舰版 E5",
                    "i18n_name": {
                        "zh_cn": "zh_cn_name",
                        "ja_jp": "ja_jp_name",
                        "en_us": "en_name"
                    },
                    "start_time": "1674981000",
                    "end_time": "1674991000"
                }
            ],
            "department_path": [
                {
                    "department_id": "od-4e6ac4d14bcd5071a37a39de902c7141",
                    "department_name": {
                        "name": "测试部门名1",
                        "i18n_name": {
                            "zh_cn": "测试部门名1",
                            "ja_jp": "試験部署名 1",
                            "en_us": "Testing department name 1"
                        }
                    },
                    "department_path": {
                        "department_ids": [
                            "od-4e6ac4d14bcd5071a37a39de902c7141"
                        ],
                        "department_path_name": {
                            "name": "测试部门名1",
                            "i18n_name": {
                                "zh_cn": "测试部门名1",
                                "ja_jp": "試験部署名 1",
                                "en_us": "Testing department name 1"
                            }
                        }
                    }
                }
            ],
            "dotted_line_leader_user_ids": [
                "ou_7dab8a3d3cdcc9da365777c7ad535d62"
            ]
        }
    }
}
```

## 响应码定义

### 成功码

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 200 | 0 | 请求成功 |

### 客户端错误码 (4xx)

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 400 | 41050 | no user authority |
| 400 | 40001 | invalid parameter |
| 400 | 41012 | user id invalid error |
| 400 | 40003 | internal error |

### 服务端错误码 (5xx)

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| - | - | 暂无 |

## 附录

### 相关链接

| 链接类型 | 链接 |
|----------|------|
| 应用权限配置 | [https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN](https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN) |
| 用户相关的 ID 概念 | [https://open.feishu.cn/document/home/user-identity-introduction/introduction](https://open.feishu.cn/document/home/user-identity-introduction/introduction) |
| 部门 ID 说明 | [https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview) |
| 权限范围校验 | [https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority](https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority) |
| 通用错误码 | [https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN) |

path: open-apis/contact-v3-users.md
content: # 获取用户列表

## 注意事项

本接口已为历史版本，不再维护更新，不推荐使用。推荐你使用[获取部门直属用户列表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/user/find_by_department)接口。

- 使用 user_access_token 情况下根据个人组织架构的通讯录可见范围进行权限过滤，返回个人组织架构通讯录范围（[登陆企业管理后台进行权限配置](https://www.feishu.cn/admin/security/permission/visibility)）内可见的用户数据。
- tenant_access_token 基于应用通讯录范围进行权限鉴定。由于 department_id 是非必填参数，填与不填存在两种数据权限校验与返回情况：
  1. 请求设置了 department_id（根部门为0），会检验所带部门ID是否具有通讯录权限（如果带上 department_id=0 会校验是否有全员权限），有则返回部门下直属的成员列表，否则提示无部门权限的错误码返回。
  2. 请求未带 department_id 参数，则会返回权限范围内的独立用户（权限范围直接包含了某用户，则该用户视为权限范围内的独立用户）。

## 权限要求

### 必要权限

| 类型 | 名称 |
|------|------|
| 应用权限（开启任一即可） | 获取部门组织架构信息 (contact:department.organize:readonly) |
| 应用权限（开启任一即可） | 以应用身份读取通讯录 (contact:contact:readonly_as_app) |
| 应用权限（开启任一即可） | 读取通讯录 (contact:contact:readonly) |
| 应用权限（开启任一即可） | 以应用身份访问通讯录 (contact:contact:access_as_app) |

### 可选权限

| 类型 | 名称 |
|------|------|
| 字段权限（敏感字段） | 获取用户基本信息 (contact:user.base:readonly) |
| 字段权限（敏感字段） | 以应用身份读取通讯录 (contact:contact:readonly_as_app) |
| 字段权限（敏感字段） | 获取用户雇佣信息 (contact:user.employee:readonly) |
| 字段权限（敏感字段） | 获取用户组织架构信息 (contact:user.department:readonly) |
| 字段权限（敏感字段） | 获取用户性别 (contact:user.gender:readonly) |
| 字段权限（敏感字段） | 获取用户邮箱信息 (contact:user.email:readonly) |
| 字段权限（敏感字段） | 获取用户手机号 (contact:user.phone:readonly) |
| 字段权限（敏感字段） | 获取用户 user ID (contact:user.employee_id:readonly) |
| 字段权限（敏感字段） | 读取通讯录 (contact:contact:readonly) |
| 字段权限（敏感字段） | 以应用身份访问通讯录 (contact:contact:access_as_app) |

> **说明**：敏感字段仅在开启对应权限后才会返回；如无需获取这些字段，不建议申请。

## 接口信息

| API 路径 | `https://open.feishu.cn/open-apis/contact/v3/users` |
|----------|-----------------------------------------------------|
| 请求方法 | GET |
| 调用频率限制 | - |
| 支持的应用类型 | Custom App、Store App |
| 文档地址 | [飞书开放平台](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/user.getList) |

## 接口请求

### 请求头

| 名称 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `Authorization` | string | 是 | `tenant_access_token` 或 `user_access_token`<br>值格式："Bearer `access_token`"<br>示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560"<br>**了解更多**：[如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use) |
| `Content-Type` | string | 是 | 固定值："application/json; charset=utf-8" |

### 请求参数

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `user_id_type` | string | 否 | 用户 ID 类型<br>可选值：<br>- `open_id`：用户的 open id<br>- `union_id`：用户的 union id<br>- `user_id`：用户的 user id<br>默认值：`open_id`<br>**权限要求**：当值为 `user_id` 时，需要获取用户 user ID (contact:user.employee_id:readonly) |
| `department_id_type` | string | 否 | 此次调用中使用的部门ID的类型<br>可选值：<br>- `department_id`：以自定义department_id来标识部门<br>- `open_department_id`：以open_department_id来标识部门<br>默认值：`open_department_id` |
| `department_id` | string | 否 | 填写该字段表示获取部门下所有用户，选填。<br>说明：根部门为 0 |
| `page_token` | string | 否 | 分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果 |
| `page_size` | int | 否 | 分页大小<br>数据校验规则：<br>- 最大值：`100` |

### 请求体

无请求体（GET 请求）

### 请求示例

#### cURL 请求示例

```bash
curl -X GET 'https://open.feishu.cn/open-apis/contact/v3/users?department_id=od_xxx&page_size=10&page_token=AQD9/...' \
  -H '[REDACTED_SECRET]' \
  -H 'Content-Type: application/json; charset=utf-8'
```

#### Go 请求示例

```go
import (
	"context"
	"net/url"

	"github.com/larksuite/oapi-sdk-go/v3"
	"github.com/larksuite/oapi-sdk-go/v3/service/contact/v3"
)

func main() {
	// 创建 Client
	client := lark.NewClient("appID", "appSecret")

	// 创建请求对象
	req := larkcontact.NewListUserReqBuilder().
		UserIdType(`open_id`).
		DepartmentIdType(`open_department_id`).
		DepartmentId(`od-xxxxxxxxxxxxx`).
		PageSize(10).
		PageToken(`AQD9/...`).
		Build()

	// 发起请求
	resp, err := client.Contact.User.List(context.Background(), req)
}
```

#### Java 请求示例

```java
import com.lark.oapi.Client;
import com.lark.oapi.service.contact.v3.model.*;
import com.lark.oapi.core.request.RequestOptions;

public class Main {
    public static void main(String arg[]) throws Exception {
        // 构建client
        Client client = Client.newBuilder("appId", "appSecret").build();

        // 创建请求对象
        ListUserReq req = ListUserReq.newBuilder()
                .userIdType("open_id")
                .departmentIdType("open_department_id")
                .departmentId("od-xxxxxxxxxxxxx")
                .pageSize(10)
                .pageToken("AQD9/...")
                .build();

        // 发起请求
        ListUserResp resp = client.contact().user().list(req, RequestOptions.newBuilder().build());
    }
}
```

#### Python 请求示例

```python
import requests
import json

def main():
    url = "https://open.feishu.cn/open-apis/contact/v3/users"
    headers = {
        "Authorization": "Bearer tenant_access_token",
        "Content-Type": "application/json; charset=utf-8"
    }
    params = {
        "department_id": "od-xxxxxxxxxxxxx",
        "department_id_type": "open_department_id",
        "user_id_type": "open_id",
        "page_size": 10
    }
    
    response = requests.get(url, headers=headers, params=params)
    print(json.dumps(response.json(), indent=2, ensure_ascii=False))

if __name__ == "__main__":
    main()
```

## 接口响应

### 响应头

| 名称 | 类型 | 描述 |
|------|------|------|
| - | - | 无额外响应头字段 |

### 响应体

| 字段 | 类型 | 描述 |
|------|------|------|
| `code` | int | 错误码，非 0 表示失败 |
| `msg` | string | 错误描述 |
| `data` | object | 响应数据 |
| `has_more` | boolean | 是否还有更多项 |
| `page_token` | string | 分页标记，当 has_more 为 true 时返回 |
| `items` | array | 用户信息列表 |

### 响应示例

```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "has_more": false,
        "page_token": "AQD9/Rn9eij9Pm39ED40/RD/cIFmu77WxpxPB/2oHfQLZ%2BG8JG6tK7%2BZnHiT7COhD2hMSICh/eBl7cpzU6JEC3J7COKNe4jrQ8ExwBCR",
        "items": [
            {
                "union_id": "on_94a1ee5551019f18cd73d9f111898cf2",
                "user_id": "3e3cf96b",
                "open_id": "ou_7dab8a3d3cdcc9da365777c7ad535d62",
                "name": "张三",
                "en_name": "San Zhang",
                "email": "[REDACTED_SECRET]",
                "mobile": "130xxxx1111",
                "mobile_visible": false,
                "gender": 1,
                "avatar": {
                    "avatar_72": "https://foo.icon.com/xxxx",
                    "avatar_240": "https://foo.icon.com/xxxx",
                    "avatar_640": "https://foo.icon.com/xxxx",
                    "avatar_origin": "https://foo.icon.com/xxxx"
                },
                "status": {
                    "is_frozen": false,
                    "is_resigned": false,
                    "is_activated": true
                },
                "department_ids": [
                    "od-4e6ac4d14bcd5071a37a39de902c7141"
                ],
                "leader_user_id": "ou_7dab8a3d3cdcc9da365777c7ad535d62",
                "city": "杭州",
                "country": "CN",
                "work_station": "北楼-H34",
                "join_time": 2147483647,
                "is_tenant_manager": false,
                "employee_no": "1",
                "employee_type": 1,
                "orders": [
                    {
                        "department_id": "od-4e6ac4d14bcd5071a37a39de902c7141",
                        "user_order": 100,
                        "department_order": 100
                    }
                ],
                "custom_attrs": [
                    {
                        "type": "TEXT",
                        "id": "DemoId",
                        "value": {
                            "text": "DemoText",
                            "url": "http://www.fs.cn",
                            "pc_url": "http://www.fs.cn",
                            "option_value": "option",
                            "name": "name",
                            "picture_url": "https://xxxxxxxxxxxxxxxxxx",
                            "generic_user": {
                                "id": "9b2fabg5",
                                "type": 1
                            }
                        }
                    }
                ],
                "enterprise_email": "[REDACTED_SECRET]",
                "job_title": "xxxxx"
            }
        ]
    }
}
```

## 响应码定义

### 成功码

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 200 | 0 | 请求成功 |

### 客户端错误码 (4xx)

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 400 | 41050 | no user authority error |
| 400 | 40011 | page size is invalid |
| 400 | 40012 | page token is invalid error |
| 403 | 40004 | no dept authority error |

### 服务端错误码 (5xx)

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| - | - | 暂无 |

## 附录

### 相关链接

| 链接类型 | 链接 |
|----------|------|
| 应用权限配置 | [https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN](https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN) |
| 用户相关的 ID 概念 | [https://open.feishu.cn/document/home/user-identity-introduction/introduction](https://open.feishu.cn/document/home/user-identity-introduction/introduction) |
| 部门 ID 说明 | [https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview) |
| 权限范围校验 | [https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority](https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority) |
| 通用错误码 | [https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN) |

path: open-apis/im-v1-messages-message_id-reply.md
content: # 回复消息

## 注意事项

### 前提条件

- 应用需要开启[机器人能力](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-enable-bot-ability)。
- 回复用户消息（即单聊消息）时，用户需要在机器人的[可用范围](https://open.feishu.cn/document/home/introduction-to-scope-and-authorization/availability)内。
- 回复群消息时，机器人需要在群中，且拥有发言权限。

### 使用限制

为避免消息发送频繁对用户造成打扰，向同一用户发送消息的限频为 **5 QPS**、向同一群组发送消息的限频为群内机器人共享 **5 QPS**。

## 权限要求

### 必要权限

| 类型 | 名称 |
|------|------|
| 应用权限（开启任一即可） | 获取与发送单聊、群组消息 (im:message) |
| 应用权限（开启任一即可） | 以应用的身份发消息 (im:message:send_as_bot) |
| 应用权限（开启任一即可） | 发送消息V2 (im:message:send) |

#### 注意事项

1. **应用身份**发消息需申请下面三个权限之一：
   - 获取与发送单聊、群组消息（im:message）
   - 以应用的身份发消息（im:message:send_as_bot）
   - 发送消息V2【历史版本】（im:message:send）

2. **用户身份**发消息需同时申请以下两个权限：
   - 获取与发送单聊、群组消息（im:message）
   - 以用户身份发送消息（im:message.send_as_user）

### 可选权限

| 类型 | 名称 |
|------|------|
| - | - |

> **说明**：本接口无敏感字段权限要求。

## 接口信息

| API 路径 | `https://open.feishu.cn/open-apis/im/v1/messages/:message_id/reply` |
|----------|--------------------------------------------------------------------|
| 请求方法 | POST |
| 调用频率限制 | 1000 次/分钟、50 次/秒 |
| 支持的应用类型 | Custom App、Store App |
| 文档地址 | [飞书开放平台](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/im-v1/message/reply) |

## 接口请求

### 请求头

| 名称 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `Authorization` | string | 是 | `tenant_access_token` 或 `user_access_token`<br>值格式："Bearer `access_token`"<br>示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560"<br>**了解更多**：[如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use) |
| `Content-Type` | string | 是 | 固定值："application/json; charset=utf-8" |

### 请求参数

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `message_id` | string | 是 | 待回复的消息的 ID。ID 获取方式：<br>- 调用发送消息接口后，从响应结果的 `message_id` 参数获取<br>- 监听接收消息事件，当触发该事件后可以从事件体内获取消息的 `message_id`<br>- 调用获取会话历史消息接口，从响应结果的 `message_id` 参数获取 |

### 请求体

| 字段 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `content` | string | 是 | 消息内容，JSON 结构序列化后的字符串。该参数的取值与 `msg_type` 对应。<br>注意：<br>- JSON 字符串需进行转义<br>- 文本消息请求体最大不能超过 150 KB<br>- 卡片消息、富文本消息请求体最大不能超过 30 KB<br>- 如果使用卡片模板（template_id）发送消息，实际大小也包含模板对应的卡片数据大小 |
| `msg_type` | string | 是 | 消息类型。可选值：<br>- `text`：文本<br>- `post`：富文本<br>- `image`：图片<br>- `file`：文件<br>- `audio`：语音<br>- `media`：视频<br>- `sticker`：表情包<br>- `interactive`：卡片<br>- `share_chat`：分享群名片<br>- `share_user`：分享个人名片 |
| `reply_in_thread` | boolean | 否 | 是否以话题形式回复。取值为 true 时将以话题形式回复。<br>默认值：`false`<br>注意：如果要回复的消息已经是话题形式的消息，则默认以话题形式进行回复 |
| `uuid` | string | 否 | 自定义设置的唯一字符串序列，用于在回复消息时请求去重。不填则表示不去重。持有相同 uuid 的请求，在 1 小时内至多成功回复一条消息。<br>最大长度：50 字符 |

### 请求示例

#### cURL 请求示例

```bash
curl --location --request POST 'https://open.feishu.cn/open-apis/im/v1/messages/om_xxxxxx/reply' \
--header 'Authorization: Bearer t-xxxxxx' \
--header 'Content-Type: application/json; charset=utf-8' \
--data-raw '{
    "content": "{\"text\":\"test content\"}",
    "msg_type": "text",
    "uuid": "a0d69e20-1dd1-458b-k525-dfeca4015204"
}'
```

#### Python 请求示例

```python
import json
import requests

def reply(message_id):
    url = f"https://open.feishu.cn/open-apis/im/v1/messages/{message_id}/reply"
    msg = "test content"
    msgContent = {
        "text": msg,
    }
    req = {
        "content": json.dumps(msgContent),
        "msg_type": "text",
        "uuid": "a0d69e20-1dd1-458b-k525-dfeca4015204"
    }
    payload = json.dumps(req)
    headers = {
        'Authorization': 'Bearer xxx',  # your access token
        'Content-Type': 'application/json'
    }
    response = requests.request("POST", url, headers=headers, data=payload)
    print(response.headers['X-Tt-Logid'])  # for debug or oncall
    print(response.content)  # Print Response

if __name__ == '__main__':
    reply("om_xxxxxx")
```

#### Go 请求示例

```go
import (
	"context"

	"github.com/larksuite/oapi-sdk-go/v3"
	"github.com/larksuite/oapi-sdk-go/v3/service/im/v1"
)

func main() {
	// 创建 Client
	client := lark.NewClient("appID", "appSecret")

	// 创建请求对象
	req := larkim.NewReplyMessageReqBuilder().
		MessageId(`om_xxxxxx`).
		Content(`{"text":"test content"}`).
		MsgType(`text`).
		Uuid(`a0d69e20-1dd1-458b-k525-dfeca4015204`).
		Build()

	// 发起请求
	resp, err := client.Im.Message.Reply(context.Background(), req)
}
```

## 接口响应

### 响应头

| 名称 | 类型 | 描述 |
|------|------|------|
| - | - | 无额外响应头字段 |

### 响应体

| 字段 | 类型 | 描述 |
|------|------|------|
| `code` | int | 错误码，非 0 表示失败 |
| `msg` | string | 错误描述 |
| `data` | object | 响应数据 |
| `message_id` | string | 消息 ID。成功回复消息后，由系统生成的唯一 ID 标识 |
| `root_id` | string | 根消息 ID。在有多个回复的消息树中，`root_id` 为根消息的 `message_id` |
| `parent_id` | string | 父消息 ID。在有多个回复的消息树中，`parent_id` 为当前消息上一层的消息 `message_id` |
| `thread_id` | string | 消息所属的话题 ID（不返回说明该消息不是话题形式的消息） |
| `msg_type` | string | 消息类型 |
| `create_time` | string | 消息生成的时间戳。单位：毫秒 |
| `update_time` | string | 消息更新的时间戳。单位：毫秒 |
| `deleted` | boolean | 当前消息是否被撤回。回复消息时只会返回 false |
| `updated` | boolean | 当前消息是否被更新。回复消息时只会返回 false |
| `chat_id` | string | 消息所属的群 ID |
| `sender` | object | 当前消息的发送者信息 |
| `body` | object | 通过 `body` 内的 `content` 参数，返回当前的消息内容 |
| `mentions` | array | 发送的消息内，被 @ 的用户列表 |
| `upper_message_id` | string | 合并转发消息中，上一层级的消息 ID |

### 响应示例

```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "message_id": "om_dc13264520392913993dd051dba21dcf",
        "root_id": "om_40eb06e7b84dc71c03e009ad3c754195",
        "parent_id": "om_d4be107c616aed9c1da8ed8068570a9f",
        "thread_id": "omt_d4be107c616a",
        "msg_type": "interactive",
        "create_time": "1615380573411",
        "update_time": "1615380573411",
        "deleted": false,
        "updated": false,
        "chat_id": "oc_5ad11d72b830411d72b836c20",
        "sender": {
            "id": "cli_9f427eec54ae901b",
            "id_type": "app_id",
            "sender_type": "app",
            "tenant_key": "736588c9260f175e"
        },
        "body": {
            "content": "{\"text\":\"@_user_1 test content\"}"
        },
        "mentions": [
            {
                "key": "@_user_1",
                "id": "ou_155184d1e73cbfb8973e5a9e698e74f2",
                "id_type": "open_id",
                "name": "Tom",
                "tenant_key": "736588c9260f175e"
            }
        ],
        "upper_message_id": "om_40eb06e7b84dc71c03e009ad3c754195"
    }
}
```

## 响应码定义

### 成功码

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 200 | 0 | 请求成功 |

### 客户端错误码 (4xx)

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 400 | 230001 | Your request contains an invalid request parameter |
| 400 | 230002 | The bot can not be outside the group |
| 400 | 230006 | Bot ability is not activated |
| 400 | 230011 | The message is recalled |
| 400 | 230013 | Bot has NO availability to this user |
| 400 | 230015 | P2P chat can NOT be shared |
| 400 | 230017 | Bot is NOT the owner of the resource |
| 400 | 230018 | These operations are NOT allowed at current group settings |
| 400 | 230019 | The topic does NOT exist |
| 400 | 230020 | This operation triggers the frequency limit |
| 400 | 230022 | The content of the message contains sensitive information |
| 400 | 230025 | The length of the message content reaches its limit |
| 400 | 230027 | Lack of necessary permissions |
| 400 | 230028 | The messages do NOT pass the audit |
| 400 | 230035 | Send Message Permission deny |
| 400 | 230038 | Cross tenant p2p chat operate forbid |
| 400 | 230049 | The message is being sent |
| 400 | 230050 | The message is invisible to the operator |
| 400 | 230054 | This operation is not supported for this message type |
| 400 | 230055 | The type of file upload does not match the type of message being sent |
| 400 | 230071 | The group to which the message belongs does not support reply in thread |
| 400 | 230072 | Aggregated messages do not support reply in thread |
| 400 | 230075 | Sending encrypted messages is not supported |
| 400 | 230099 | Failed to create card content |
| 400 | 230111 | Action unavailable as the message will self-destruct soon |
| 400 | 232009 | Your request specifies a chat which has already been dissolved |

### 服务端错误码 (5xx)

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| - | - | 暂无 |

### 230099 子错误码

| 错误码 | 描述 |
|--------|------|
| 100290 | Failed to create card content, ext=ErrCode: 100290; ErrMsg: There is an invalid user resource(at/person) in your card |
| 200380 | Failed to create card content, ext=ErrCode: 200380; ErrMsg: template does not exist |
| 200381 | Failed to create card content, ext=ErrCode: 200381; ErrMsg: template is not visible to app |
| 200621 | Failed to create card content, ext=ErrCode: 200621; ErrMsg: parse card json err |
| 200732 | Failed to create card content, ext=ErrCode: 200732; ErrMsg: the actual type of the variable is inconsistent |
| 200550 | Failed to create card content, ext=ErrCode: 200550; ErrMsg: chart spec is invalid |
| 200861 | Failed to create card content, ext=ErrCode: 200861; ErrMsg: cards of schema V2 no longer support this capability |
| 200570 | Failed to create card content, ext=ErrCode: 200570; ErrMsg: card contains invalid image keys |
| 200914 | Failed to create card content, ext=ErrCode: 200914; ErrMsg: table rows is invalid |
| 200915 | Failed to create card content, ext=ErrCode: 200915; ErrMsg: table rows name is invalid |

## 附录

### 相关链接

| 链接类型 | 链接 |
|----------|------|
| 发送消息内容 | [发送消息内容结构](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/im-v1/message/create_json) |
| 机器人权限配置 | [应用权限配置](https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN) |
| 消息管理概述 | [消息管理概述](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/intro) |
| 话题概述 | [话题概述](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/thread-introduction) |
| 通用错误码 | [服务端通用错误码](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN) |

path: open-apis/im-v1-messages.md
content: # 发送消息

## 注意事项

### 前提条件

- 应用需要开启[机器人能力](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-enable-bot-ability)。开启能力后需要发布版本才能生效，参考 [发布应用](https://open.feishu.cn/document/home/introduction-to-custom-app-development/self-built-application-development-process#baf09c7d)。
- 给用户发送消息时，用户需要在机器人的[可用范围](https://open.feishu.cn/document/home/introduction-to-scope-and-authorization/availability)内。
- 给群组发送消息时，机器人需要在该群组中，且在群组内拥有发言权限。

### 使用限制

- 为避免消息发送频繁对用户造成打扰，向同一用户发送消息的限频为 **5 QPS**、向同一群组发送消息的限频为群内机器人共享 **5 QPS**。
- 该接口仅支持在开发者后台创建的应用机器人调用，群自定义机器人无法调用该接口。了解群自定义机器人的使用方式，参见[自定义机器人使用指南](https://open.feishu.cn/document/ukTMukTMukTM/ucTM5YjL3ETO24yNxkjN)。

## 权限要求

### 必要权限

| 类型 | 名称 |
|------|------|
| 应用权限（开启任一即可） | 获取与发送单聊、群组消息 (im:message) |
| 应用权限（开启任一即可） | 以应用的身份发消息 (im:message:send_as_bot) |
| 应用权限（开启任一即可） | 发送消息V2 (im:message:send) |

#### 注意事项

1. **应用身份**发消息需申请下面三个权限之一：
   - 获取与发送单聊、群组消息（im:message）
   - 以应用的身份发消息（im:message:send_as_bot）
   - 发送消息V2【历史版本】（im:message:send）

2. **用户身份**发消息需同时申请以下两个权限：
   - 获取与发送单聊、群组消息（im:message）
   - 以用户身份发送消息（im:message.send_as_user）

### 可选权限

| 类型 | 名称 |
|------|------|
| 字段权限（敏感字段） | 获取用户 user ID (contact:user.employee_id:readonly) |

> **说明**：敏感字段仅在开启对应权限后才会返回；如无需获取这些字段，不建议申请。

## 接口信息

| API 路径 | `https://open.feishu.cn/open-apis/im/v1/messages` |
|----------|---------------------------------------------------|
| 请求方法 | POST |
| 调用频率限制 | 1000 次/分钟、50 次/秒 |
| 支持的应用类型 | Custom App、Store App |
| 文档地址 | [飞书开放平台](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/im-v1/message/create) |

## 接口请求

### 请求头

| 名称 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `Authorization` | string | 是 | `tenant_access_token` 或 `user_access_token`<br>值格式："Bearer `access_token`"<br>示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560"<br>**了解更多**：[如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use) |
| `Content-Type` | string | 是 | 固定值："application/json; charset=utf-8" |

### 请求参数

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `receive_id_type` | string | 是 | 消息接收者 ID 类型。支持 open_id/union_id/user_id/email/chat_id<br>可选值：<br>- `open_id`：标识一个用户在某个应用中的身份<br>- `union_id`：标识一个用户在某个应用开发商下的身份<br>- `user_id`：标识一个用户在某个租户内的身份<br>- `email`：以用户的真实邮箱来标识用户<br>- `chat_id`：以群 ID 来标识群聊<br>**权限要求**：当值为 `user_id` 时，需要获取用户 user ID (contact:user.employee_id:readonly) |

### 请求体

| 字段 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `receive_id` | string | 是 | 消息接收者的 ID，ID 类型与查询参数 `receive_id_type` 的取值一致。<br>说明：<br>- 给用户发送消息时，用户需要在机器人的可用范围内<br>- 给群组发送消息时，机器人需要在该群组中，且在群组内拥有发言权限<br>- 如果消息接收者为用户，推荐使用用户的 `open_id` |
| `msg_type` | string | 是 | 消息类型。可选值：<br>- `text`：文本<br>- `post`：富文本<br>- `image`：图片<br>- `file`：文件<br>- `audio`：语音<br>- `media`：视频<br>- `sticker`：表情包<br>- `interactive`：卡片<br>- `share_chat`：分享群名片（被分享的群名片有效期为 7 天）<br>- `share_user`：分享个人名片<br>- `system`：系统消息 |
| `content` | string | 是 | 消息内容，JSON 结构序列化后的字符串。该参数的取值与 `msg_type` 对应。<br>注意：<br>- JSON 字符串需进行转义<br>- 文本消息请求体最大不能超过 150 KB<br>- 卡片消息、富文本消息请求体最大不能超过 30 KB<br>- 如果使用卡片模板（template_id）发送消息，实际大小也包含模板对应的卡片数据大小 |
| `uuid` | string | 否 | 自定义设置的唯一字符串序列，用于在发送消息时请求去重。持有相同 uuid 的请求，在 1 小时内至多成功发送一条消息。<br>最大长度：50 字符 |

### 请求示例

#### cURL 请求示例

```bash
curl --location --request POST 'https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=chat_id' \
--header 'Authorization: Bearer t-XXX' \
--header 'Content-Type: application/json; charset=utf-8' \
--data-raw '{
    "receive_id": "oc_84983ff6516d731e5b5f68d4ea2e1da5",
    "msg_type": "text",
    "content": "{\"text\":\"test content\"}"
}'
```

#### Python 请求示例

```python
import json
import requests

def send():
    url = "https://open.feishu.cn/open-apis/im/v1/messages"
    params = {"receive_id_type":"chat_id"}
    msg = "text content"
    msgContent = {
        "text": msg,
    }
    req = {
        "receive_id": "oc_xxx",  # chat id
        "msg_type": "text",
        "content": json.dumps(msgContent)
    }
    payload = json.dumps(req)
    headers = {
        'Authorization': 'Bearer xxx',  # your access token
        'Content-Type': 'application/json'
    }
    response = requests.request("POST", url, params=params, headers=headers, data=payload)
    print(response.headers['X-Tt-Logid'])  # for debug or oncall
    print(response.content)  # Print Response

if __name__ == '__main__':
    send()
```

#### Go 请求示例

请参考[机器人自动拉群报警教程（含 Go 示例代码）](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message-development-tutorial/determine-the-api-and-event-to-call)

#### 发送卡片请求示例

```json
{
  "receive_id": "ou_7d8a6e6df7621556ce0d21922b676706ccs",
  "msg_type": "interactive",
  "content": "{\"elements\":[{\"tag\":\"markdown\",\"content\":\"普通文本\\n\\n <at id=\\\"ou_cf986xxxx\\\"></at> <at id=\\\"ou_cf986xxxx\\\"></at> <at email=\\\"[REDACTED_SECRET]\\\"></at> <at id=\\\"all\\\"></at>\"}]}"
}
```

## 接口响应

### 响应头

| 名称 | 类型 | 描述 |
|------|------|------|
| - | - | 无额外响应头字段 |

### 响应体

| 字段 | 类型 | 描述 |
|------|------|------|
| `code` | int | 错误码，非 0 表示失败 |
| `msg` | string | 错误描述 |
| `data` | object | 响应数据 |
| `message_id` | string | 消息 ID。成功发送消息后，由系统生成的唯一 ID 标识 |
| `root_id` | string | 根消息 ID，仅在回复消息场景会有返回值 |
| `parent_id` | string | 父消息 ID，仅在回复消息场景会有返回值 |
| `thread_id` | string | 消息所属的话题 ID，仅在话题场景会有返回值 |
| `msg_type` | string | 消息类型 |
| `create_time` | string | 消息生成的时间戳。单位：毫秒 |
| `update_time` | string | 消息更新的时间戳。单位：毫秒 |
| `deleted` | boolean | 消息是否被撤回。发送消息时只会返回 false |
| `updated` | boolean | 消息是否被更新。发送消息时只会返回 false |
| `chat_id` | string | 消息所属的群 ID |
| `sender` | object | 消息的发送者信息 |
| `body` | object | 消息内容 |
| `mentions` | array | 发送的消息内，被 @ 的用户列表 |
| `upper_message_id` | string | 合并转发消息中，上一层级的消息 ID |

### 响应示例

```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "message_id": "om_dc13264520392913993dd051dba21dcf",
        "root_id": "om_40eb06e7b84dc71c03e009ad3c754195",
        "parent_id": "om_d4be107c616aed9c1da8ed8068570a9f",
        "thread_id": "omt_d4be107c616a",
        "msg_type": "interactive",
        "create_time": "1615380573411",
        "update_time": "1615380573411",
        "deleted": false,
        "updated": false,
        "chat_id": "oc_5ad11d72b830411d72b836c20",
        "sender": {
            "id": "cli_9f427eec54ae901b",
            "id_type": "app_id",
            "sender_type": "app",
            "tenant_key": "736588c9260f175e"
        },
        "body": {
            "content": "{\"text\":\"@_user_1 test content\"}"
        },
        "mentions": [
            {
                "key": "@_user_1",
                "id": "ou_155184d1e73cbfb8973e5a9e698e74f2",
                "id_type": "open_id",
                "name": "Tom",
                "tenant_key": "736588c9260f175e"
            }
        ],
        "upper_message_id": "om_40eb06e7b84dc71c03e009ad3c754195"
    }
}
```

## 响应码定义

### 成功码

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 200 | 0 | 请求成功 |

### 客户端错误码 (4xx)

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 400 | 230001 | Your request contains an invalid request parameter |
| 400 | 230002 | The bot can not be outside the group |
| 400 | 230006 | Bot ability is not activated |
| 400 | 230013 | Bot has NO availability to this user |
| 400 | 230015 | P2P chat can NOT be shared |
| 400 | 230017 | Bot is NOT the owner of the resource |
| 400 | 230018 | These operations are NOT allowed at current group settings |
| 400 | 230019 | The topic does NOT exist |
| 400 | 230020 | This operation triggers the frequency limit |
| 400 | 230022 | The content of the message contains sensitive information |
| 400 | 230025 | The length of the message content reaches its limit |
| 400 | 230027 | Lack of necessary permissions |
| 400 | 230028 | The messages do NOT pass the audit |
| 400 | 230029 | User has resigned |
| 400 | 230034 | The receive_id is invalid |
| 400 | 230035 | Send Message Permission deny |
| 400 | 230036 | Tenant crypt key has been deleted |
| 400 | 230038 | Cross tenant p2p chat operate forbid |
| 400 | 230049 | The message is being sent |
| 400 | 230053 | The user has stopped the bot from sending messages |
| 400 | 230054 | This type of message is unavailable in the connection group |
| 400 | 230055 | The type of file upload does not match the type of message being sent |
| 400 | 230075 | Sending encrypted messages is not supported |
| 400 | 230099 | Failed to create card content |
| 400 | 232009 | Your request specifies a chat which has already been dissolved |

### 服务端错误码 (5xx)

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| - | - | 暂无 |

### 230099 子错误码

| 错误码 | 描述 |
|--------|------|
| 100290 | Failed to create card content, ext=ErrCode: 100290; ErrMsg: There is an invalid user resource(at/person) in your card |
| 11310 | Failed to create card content, ext=ErrCode: 11310; ErrMsg: %v; code:230099 |
| 200380 | Failed to create card content, ext=ErrCode: 200380; ErrMsg: template does not exist |
| 200381 | Failed to create card content, ext=ErrCode: 200381; ErrMsg: template is not visible to app |
| 200621 | Failed to create card content, ext=ErrCode: 200621; ErrMsg: parse card json err |
| 200732 | Failed to create card content, ext=ErrCode: 200732; ErrMsg: the actual type of the variable is inconsistent |
| 200737 | Failed to create card content, ext=ErrCode: 200737; ErrMsg: the format of the variable is incorrect |
| 200550 | Failed to create card content, ext=ErrCode: 200550; ErrMsg: chart spec is invalid |
| 200861 | Failed to create card content, ext=ErrCode: 200861; ErrMsg: cards of schema V2 no longer support this capability |
| 200570 | Failed to create card content, ext=ErrCode: 200570; ErrMsg: card contains invalid image keys |
| 200914 | Failed to create card content, ext=ErrCode: 200914; ErrMsg: table rows is invalid |
| 200915 | Failed to create card content, ext=ErrCode: 200915; ErrMsg: table rows name is invalid |
| 300240 | Failed to create card content, ext=ErrCode: 300240; ErrMsg: This application cannot retrieve audio information |
| 300230 | Failed to create card content, ext=ErrCode: 300230; ErrMsg: duplicate audio id |
| 300220 | Failed to create card content, ext=ErrCode: 300220; ErrMsg: audio elem don't support forward |

## 附录

### 相关链接

| 链接类型 | 链接 |
|----------|------|
| 发送消息内容 | [发送消息内容结构](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/im-v1/message/create_json) |
| 机器人权限配置 | [应用权限配置](https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN) |
| 用户相关的 ID 概念 | [用户身份介绍](https://open.feishu.cn/document/home/user-identity-introduction/introduction) |
| 权限范围校验 | [权限范围资源介绍](https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority) |
| 通用错误码 | [服务端通用错误码](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN) |

path: open-apis/passport-v1-sessions-query.md
content: # 批量获取脱敏的用户登录信息

## 注意事项

该接口用于查询用户的登录信息。

## 权限要求

### 必要权限

| 类型 | 名称 |
|------|------|
| 应用权限（开启任一即可） | 获取用户登录信息（mask）(passport:session_mask:readonly) |

### 可选权限

| 类型 | 名称 |
|------|------|
| 字段权限（敏感字段） | 获取用户 user ID (contact:user.employee_id:readonly) |

> **说明**：敏感字段仅在开启对应权限后才会返回；如无需获取这些字段，不建议申请。

## 接口信息

| API 路径 | `https://open.feishu.cn/open-apis/passport/v1/sessions/query` |
|----------|---------------------------------------------------------------|
| 请求方法 | POST |
| 调用频率限制 | 10 次/分钟 |
| 支持的应用类型 | Custom App |
| 文档地址 | [飞书开放平台](https://open.feishu.cn/document/ukTMukTMukTM/reference/passport-v1/session/query) |

## 接口请求

### 请求头

| 名称 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `Authorization` | string | 是 | `tenant_access_token`<br>值格式："Bearer `access_token`"<br>示例值："Bearer t-7f1bcd13fc57d46bac21793a18e560"<br>**了解更多**：[如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use) |
| `Content-Type` | string | 是 | 固定值："application/json; charset=utf-8" |

### 请求参数

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `user_id_type` | string | 否 | 用户 ID 类型<br>可选值：<br>- `open_id`：标识一个用户在某个应用中的身份<br>- `union_id`：标识一个用户在某个应用开发商下的身份<br>- `user_id`：标识一个用户在某个租户内的身份<br>默认值：`open_id`<br>**权限要求**：当值为 `user_id` 时，需要获取用户 user ID (contact:user.employee_id:readonly) |

### 请求体

| 字段 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `user_ids` | array | 否 | 用户 ID<br>最大长度：`100` |

### 请求示例

#### cURL 请求示例

```bash
curl -X POST 'https://open.feishu.cn/open-apis/passport/v1/sessions/query?user_id_type=open_id' \
  -H '[REDACTED_SECRET]' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "user_ids": ["7aeddb6a1", "7aeddb6a2", "7aeddb6a3"]
  }'
```

#### Go 请求示例

```go
import (
	"context"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	url := "https://open.feishu.cn/open-apis/passport/v1/sessions/query?user_id_type=open_id"
	
	data := map[string]interface{}{
		"user_ids": []string{"7aeddb6a1", "7aeddb6a2", "7aeddb6a3"},
	}
	
	jsonData, _ := json.Marshal(data)
	
	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
	req.Header.Set("Authorization", "Bearer tenant_access_token")
	req.Header.Set("Content-Type", "application/json; charset=utf-8")
	
	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		fmt.Println("Error:", err)
		return
	}
	defer resp.Body.Close()
	
	fmt.Println("Response status:", resp.Status)
}
```

#### Python 请求示例

```python
import requests
import json

def main():
    url = "https://open.feishu.cn/open-apis/passport/v1/sessions/query"
    headers = {
        "Authorization": "Bearer tenant_access_token",
        "Content-Type": "application/json; charset=utf-8"
    }
    params = {
        "user_id_type": "open_id"
    }
    data = {
        "user_ids": ["7aeddb6a1", "7aeddb6a2", "7aeddb6a3"]
    }
    
    response = requests.post(url, headers=headers, params=params, json=data)
    print(json.dumps(response.json(), indent=2, ensure_ascii=False))

if __name__ == "__main__":
    main()
```

#### Java 请求示例

```java
import com.lark.oapi.Client;
import com.lark.oapi.core.request.RequestOptions;

public class Main {
    public static void main(String arg[]) throws Exception {
        // 构建client
        Client client = Client.newBuilder("appId", "appSecret").build();

        // 注意：该接口路径为 passport/v1/sessions/query
        // 飞书 SDK 可能不包含此接口，建议直接使用 HTTP 请求
    }
}
```

## 接口响应

### 响应头

| 名称 | 类型 | 描述 |
|------|------|------|
| - | - | 无额外响应头字段 |

### 响应体

| 字段 | 类型 | 描述 |
|------|------|------|
| `code` | int | 错误码，非 0 表示失败 |
| `msg` | string | 错误描述 |
| `data` | object | 响应数据 |
| `mask_sessions` | array | 用户登录信息列表 |

#### mask_sessions 对象

| 字段 | 类型 | 描述 |
|------|------|------|
| `create_time` | string | 创建时间 |
| `terminal_type` | int | 客户端类型<br>可选值：<br>- `0`：未知<br>- `1`：个人电脑<br>- `2`：浏览器<br>- `3`：安卓手机<br>- `4`：Apple手机<br>- `5`：服务端<br>- `6`：旧版小程序端<br>- `8`：其他移动端 |
| `user_id` | string | 用户ID |
| `sid` | string | 需要登出的 session 标识符 |

### 响应示例

```json
{
    "code": 0,
    "data": {
        "mask_sessions": [
            {
                "create_time": "1644980493",
                "terminal_type": 2,
                "user_id": "47f183f1f1",
                "sid": "ABBAAAAAAANll6nQoIAAFA=="
            },
            {
                "create_time": "1644983127",
                "terminal_type": 2,
                "user_id": "47f183ff1",
                "sid": "ACCAAAAAAANll6nQoIAAFA=="
            },
            {
                "create_time": "1644983127",
                "terminal_type": 2,
                "user_id": "47f183ff2",
                "sid": "BBBAAAAAAANll6nQoIAAFA=="
            }
        ]
    },
    "msg": ""
}
```

## 响应码定义

### 成功码

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 200 | 0 | 请求成功 |

### 客户端错误码 (4xx)

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 400 | 1080001 | param is invalis |

### 服务端错误码 (5xx)

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| - | - | 暂无 |

## 附录

### 相关链接

| 链接类型 | 链接 |
|----------|------|
| 应用权限配置 | [https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN](https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN) |
| 用户相关的 ID 概念 | [https://open.feishu.cn/document/home/user-identity-introduction/introduction](https://open.feishu.cn/document/home/user-identity-introduction/introduction) |
| 通用错误码 | [https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN) |

path: open-apis/README.md
content: # feishu-skill API 文档

这个目录存放飞书开放平台的 API 文档整理。

## API 分类

| 分类 | 说明 |
|------|------|
| `contact-v3-*.md` | 通讯录 v3 API（用户、部门） |
| `im-v1-*.md` | 消息 API |
| `passport-v1-*.md` | 用户登录信息 API |
| `auth-v3-*.md` | 认证 API |
| `authen-v1-*.md` | OAuth 2.0 API |

## 使用方法

每个 API 文档包含：
- API 描述
- 请求方法 (GET/POST)
- 请求 URL
- 请求参数
- 响应格式
- 示例代码

## API 文档地址

- [飞书开放平台](https://open.feishu.cn/)
- [API 文档](https://open.feishu.cn/document/server-docs)

## 已记录 API

| API | 状态 |
|-----|------|
| auth-v3-tenant_access_token-internal | ✅ 已记录 |
| authen-v1-user_info | ✅ 已记录 |
| contact-v3-users-find_by_department | ✅ 已记录 |
| contact-v3-users | ✅ 已记录 |
| contact-v3-users-user_id | ✅ 已记录 |
| contact-v3-users-batch | ✅ 已记录 |
| contact-v3-users-batch_get_id | ✅ 已记录 |
| contact-v3-users-basic_batch | ✅ 已记录 |
| contact-v3-scopes | ✅ 已记录 |
| contact-v3-departments-batch | ✅ 已记录 |
| contact-v3-departments-department_id | ✅ 已记录 |
| contact-v3-departments-department_id-children | ✅ 已记录 |
| contact-v3-departments-parent | ✅ 已记录 |
| im-v1-messages | ✅ 已记录 |
| im-v1-messages-message_id-reply | ✅ 已记录 |
| passport-v1-sessions-query | ✅ 已记录 |


path: open-apis/TEMPLATE.md
content: # API 模板文档

## 限制和要求

这是 API 文档模板。使用此模板创建新的 API 文档时，请严格遵守以下结构和格式。

### 文件命名规范

**API 文件命名和目录结构规则**：

1. **API 路径处理**：
   - 以 `https://open.feishu.cn/open-apis` 开头的接口，文件直接放在 `API/` 目录下
   - 将路径中的 `/` 替换为 `-`，`:` 直接删除
   - 添加 `.md` 后缀

2. **非 standard 路径**：
   - 如果接口路径不是以 `https://open.feishu.cn/open-apis` 开头，**请询问用户**文件名和路径

3. **示例**：
   | API 路径 | 对应文件名 |
   |----------|-------------|
   | `/im/v1/messages` | `im-v1-messages.md` |
   | `/im/v1/messages/:message_id/reply` | `im-v1-messages-message_id-reply.md` |
   | `/auth/v3/tenant_access_token/internal` | `auth-v3-tenant_access_token-internal.md` |
   | `/contact/v3/users` | `contact-v3-users.md` |

### 文档层级结构规范

**API 文档的层级结构必须严格遵循以下格式**：

```
# 接口名称

## 注意事项

## 权限要求

### 必要权限

### 可选权限

## 接口信息

## 接口请求

### 请求头

### 请求参数

### 请求体

### 请求示例

## 接口响应

### 响应头

### 响应体

### 响应示例

## 响应码定义

### 成功码

### 客户端错误码 (4xx)

### 服务端错误码 (5xx)

## 附录

### 按需定义章节标题，例如：相关链接
```

**要求**：
- 一级标题：`#` 接口名称
- 二级标题：`##` 主要章节（注意事项、权限要求、接口信息、接口请求、接口响应、响应码定义、附录）
- 三级标题：`###` 子章节（必要权限、可选权限、请求头、响应头等）
- 禁止使用超出上述级别的标题

### 关于模板说明和模板示例

- **模板说明**：用于说明模板中某些内容的注意事项、强调要点或提供背景信息。这些内容在最终生成文档时，**通常作为提示、说明文字或背景介绍，不会直接作为独立的大节出现**。

- **模板示例**：用于展示实际 API 文档的完整结构和格式。后面根据模板生成文档时，需要按照"模板示例"中的内容和格式来编写实际的文档内容。

### 使用模板生成真实 API 文档的约束

当你根据本模板生成真实的 API 文档时，请严格遵守以下规则：

1. **不要将"关于模板说明和模板示例"的标题及说明文字写入最终文档**。这些内容仅用于指导模板使用者理解如何组织文档。

2. **"关于模板说明和模板示例"的内容**：应作为提示、说明文字嵌入到实际章节的描述中，或作为背景介绍概述，不需要单独作为章节标题。

3. **"关于模板示例"的内容**：直接按示例中的格式和结构编写实际文档内容，使用真实的数据、代码示例和说明。

4. **实际文档_should not_ 包含如下内容**：
   - "关于模板说明和模板示例"的二级标题
   - "参考模板示例中的..."这样的提示语句
   - "请参考..."这类指导性文字

5. **实际文档应该_只有_**：
   - 真实的章节标题（如"注意事项"、"权限要求"、"接口信息"等）
   - 真实的内容（不是模板示例的占位符）
   - 真实的代码示例（不是示例结构）
   - 真实的链接和参考

## 注意事项

### 模板说明

此处说明该接口的使用场景、注意事项等重要信息，特别是：

- 用户身份（user_access_token）调用时的过滤行为
- 应用身份（tenant_access_token）调用时的过滤行为
- 特殊字段的返回条件

### 模板示例

- 使用用户身份（user_access_token）调用该接口时，接口将根据该用户的组织架构可见范围进行过滤，仅返回组织架构可见范围内的用户数据。
- 使用应用身份（tenant_access_token）调用该接口时，接口将根据应用的通讯录权限范围进行过滤。如果请求的部门 ID 为 0（即根部门），则接口会校验应用是否具有全员的通讯录权限；如果请求的是非 0 的部门 ID，则会校验应用是否具有该部门的通讯录权限。无权限时，接口会返回无权限的报错信息；有权限则返回对应部门下的直属用户列表。
- 使用应用身份（tenant_access_token）调用本接口时，响应结果中不会返回部门路径字段（department_path）。如需获取部门路径字段值，请为应用申请 **获取成员所在部门路径（contact:user.department_path:readonly）** API 权限，并使用用户身份（user_access_token）调用接口。

关于用户组织架构可见范围和通讯录权限范围的更多信息，可参见[权限范围资源介绍](https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority)。

## 权限要求

### 必要权限

#### 模板说明

调用该 API **必须开启**的权限。开启其中任意一项权限即可调用该接口。

权限类型通常为：
- `应用权限（开启任一即可）` - 应用需要配置的权限

#### 模板示例

| 类型 | 名称 |
|----------|----------|
| 应用权限（开启任一即可） | 获取通讯录基本信息 (contact:contact.base:readonly) |
| 应用权限（开启任一即可） | 获取通讯录部门组织架构信息 (contact:department.organize:readonly) |
| 应用权限（开启任一即可） | 以应用身份访问通讯录 (contact:contact:access_as_app) |
| 应用权限（开启任一即可） | 读取通讯录 (contact:contact:readonly) |
| 应用权限（开启任一即可） | 以应用身份读取通讯录 (contact:contact:readonly_as_app) |

### 可选权限

#### 模板说明

敏感字段的权限要求。如果无需获取这些敏感字段，则不需要申请这些权限。

权限类型通常为：
- `字段权限（敏感字段）` - 敏感字段需要的权限

#### 模板示例

| 类型 | 名称 |
|----------|----------|
| 字段权限（敏感字段） | 统一用户标识 (contact:user.base:readonly) |
| 字段权限（敏感字段） | 获取用户 user ID (contact:user.employee_id:readonly) |
| 字段权限（敏感字段） | 应用内用户标识 (contact:user.base:readonly) |
| 字段权限（敏感字段） | 获取用户基本信息 (contact:user.base:readonly) |
| 字段权限（敏感字段） | 获取用户邮箱信息 (contact:user.email:readonly) |
| 字段权限（敏感字段） | 获取用户手机号 (contact:user.phone:readonly) |
| 字段权限（敏感字段） | 获取用户性别 (contact:user.gender:readonly) |
| 字段权限（敏感字段） | 获取用户受雇信息 (contact:user.employee:readonly) |
| 字段权限（敏感字段） | 获取用户组织架构信息 (contact:user.department:readonly) |
| 字段权限（敏感字段） | 查看成员工号 (contact:user.employee_number:read) |
| 字段权限（敏感字段） | 查看成员数据驻留地 (contact:user.user_geo) |
| 字段权限（敏感字段） | 查询用户职级 (contact:user.job_level:readonly) |
| 字段权限（敏感字段） | 查询用户所属的工作序列 (contact:user.job_family:readonly) |
| 字段权限（敏感字段） | 获取成员所在部门路径 (contact:user.department_path:readonly) |
| 字段权限（敏感字段） | 查看成员的虚线上级 ID (contact:user.dotted_line_leader_info.read) |

> **说明**：敏感字段仅在开启对应权限后才会返回；如无需获取这些字段，不建议申请。

## 接口信息

### 模板说明

接口信息表格展示接口的基本信息，包括：

- **API 路径**：接口的完整 URL
- **请求方法**：GET/POST/PUT/DELETE 等
- **调用频率限制**：每分钟/每秒的调用次数限制
- **支持的应用类型**：Custom App 或 Store App
- **文档地址**：飞书开放平台的文档链接

### 模板示例

| API 路径 | `https://open.feishu.cn/open-apis/contact/v3/users/find_by_department` |
|----------|------------------------------------------------------------------------|
| 请求方法 | GET |
| 调用频率限制 | 1000 次/分钟、50 次/秒 |
| 支持的应用类型 | Custom App、Store App |
| 文档地址 | [飞书开放平台](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/user/find_by_department) |

## 接口请求

### 请求头

#### 模板说明

HTTP 请求头字段，用于身份认证和内容类型声明。

**即使请求头无额外字段，也要保留该章节结构**。

**如果某个字段有权限要求，要在"描述"字段中注明权限要求**。权限名称的格式为：`获取用户 user ID (contact:user.employee_id:readonly)`。参考请求参数下模板示例中的 `user_id_type` 权限要求写法。

#### 模板示例

| 名称 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `Authorization` | string | 是 | `tenant_access_token` 或 `user_access_token`<br>值格式："Bearer `access_token`"<br>示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560"<br>**了解更多**：[如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use) |
| `Content-Type` | string | 是 | 固定值："application/json; charset=utf-8" |

### 请求参数

#### 模板说明

URL 查询参数或路径参数，用于传递请求所需的数据。

**参数根据接口提供内容动态生成，不固定在模板里**。

**如果某个参数有权限要求，要在"描述"字段中注明权限要求**。权限名称的格式为：`获取用户 user ID (contact:user.employee_id:readonly)`。参考请求参数下模板示例中的 `user_id_type` 权限要求写法。

#### 模板示例

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `user_id_type` | string | 否 | 用户 ID 类型<br>可选值：<br>- `open_id`：标识一个用户在某个应用中的身份<br>- `union_id`：标识一个用户在某个应用开发商下的身份<br>- `user_id`：标识一个用户在某个租户内的身份<br>默认值：`open_id`<br>**权限要求**：当值为 `user_id` 时，需要获取用户 user ID (contact:user.employee_id:readonly) |
| `department_id_type` | string | 否 | 部门 ID 类型<br>可选值：<br>- `department_id`：支持用户自定义配置的部门 ID<br>- `open_department_id`：由系统自动生成的部门 ID<br>默认值：`open_department_id` |
| `department_id` | string | 是 | 部门 ID，ID 类型与 `department_id_type` 的取值保持一致。<br>说明：<br>- 根部门的部门 ID 为 0<br>- 可调用搜索部门接口获取对应的部门 ID |
| `page_size` | int | 否 | 分页大小<br>默认值：`10`<br>数据校验规则：<br>- 最大值：`50` |
| `page_token` | string | 否 | 分页标记，第一次请求不填，表示从头开始遍历 |

### 请求体

#### 模板说明

POST/PUT 请求的 JSON body，GET 请求通常无请求体。

**如果请求体中有字段有权限要求，要在"描述"字段中注明权限要求**。权限名称的格式为：`获取用户 user ID (contact:user.employee_id:readonly)`。参考请求参数下模板示例中的 `user_id_type` 权限要求写法。

#### 模板示例

无请求体（GET 请求）

### 请求示例

#### 模板说明

代码示例展示如何调用该接口，支持多种编程语言和工具。根据实际需要选择示例：

- **Go 和 Java 示例**：使用飞书 SDK（推荐）
- **cURL 示例**：适用于快速测试，基于 HTTP 原生请求
- **Python 示例**：适用于自动化脚本
- **Node.js 示例**：适用于 Node.js 环境

如果官方文档提供了其他语言的示例（如 PHP、C# 等），请参考文档格式添加相应代码。

#### 模板示例

##### cURL 请求示例

cURL 是最简单的 HTTP 请求方式，适合快速测试：

```bash
curl -X GET 'https://open.feishu.cn/open-apis/contact/v3/users?department_id=od_xxx&page_size=10&page_token=AQD9/...' \
  -H '[REDACTED_SECRET]' \
  -H 'Content-Type: application/json; charset=utf-8'
```

##### Go 请求示例

```go
import (
	"context"

	"github.com/larksuite/oapi-sdk-go/v3"
	"github.com/larksuite/oapi-sdk-go/v3/service/contact/v3"
)

func main() {
	// 创建 Client
	client := lark.NewClient("appID", "appSecret")

	// 创建请求对象
	req := larkcontact.NewFindByDepartmentUserReqBuilder().
		UserIdType(`open_id`).
		DepartmentIdType(`open_department_id`).
		DepartmentId(`od-xxxxxxxxxxxxx`).
		PageSize(10).
		Build()

	// 发起请求
	resp, err := client.Contact.User.FindByDepartment(context.Background(), req)
}
```

##### Java 请求示例

```java
import com.lark.oapi.Client;
import com.lark.oapi.service.contact.v3.model.*;
import com.lark.oapi.core.request.RequestOptions;

public class Main {
    public static void main(String arg[]) throws Exception {
        // 构建client
        Client client = Client.newBuilder("appId", "appSecret").build();

        // 创建请求对象
        FindByDepartmentUserReq req = FindByDepartmentUserReq.newBuilder()
                .userIdType("open_id")
                .departmentIdType("open_department_id")
                .departmentId("od-xxxxxxxxxxxxx")
                .pageSize(10)
                .build();

        // 发起请求
        FindByDepartmentUserResp resp = client.contact().user().findByDepartment(req, RequestOptions.newBuilder().build());
    }
}
```

##### Python 请求示例

```python
import requests
import json

def main():
    url = "https://open.feishu.cn/open-apis/contact/v3/users/find_by_department"
    headers = {
        "Authorization": "Bearer tenant_access_token",
        "Content-Type": "application/json; charset=utf-8"
    }
    params = {
        "department_id": "od-xxxxxxxxxxxxx",
        "department_id_type": "open_department_id",
        "user_id_type": "open_id",
        "page_size": 10
    }
    
    response = requests.get(url, headers=headers, params=params)
    print(json.dumps(response.json(), indent=2, ensure_ascii=False))

if __name__ == "__main__":
    main()
```

## 接口响应

### 响应头

#### 模板说明

HTTP 响应头字段。

**即使响应头无额外字段，也要保留该章节结构**。

**如果某个字段有权限要求，要在"描述"字段中注明权限要求**。权限名称的格式为：`获取用户 user ID (contact:user.employee_id:readonly)`。参考请求参数下模板示例中的 `user_id_type` 权限要求写法。

#### 模板示例

| 名称 | 类型 | 描述 |
|------|------|------|
| - | - | 无额外响应头字段 |

### 响应体

#### 模板说明

JSON 响应体结构，包含 code、msg 和 data 字段。**响应体具体字段根据接口返回内容动态生成，不固定**。

**如果某个字段有权限要求，要在"描述"字段中注明权限要求**。权限名称的格式为：`获取用户 user ID (contact:user.employee_id:readonly)`。参考请求参数下模板示例中的 `user_id_type` 权限要求写法。

#### 模板示例

| 字段 | 类型 | 描述 |
|------|------|------|
| `code` | int | 错误码，非 0 表示失败 |
| `msg` | string | 错误描述 |
| `data` | object | 响应数据，根据接口类型动态变化 |

### 响应示例

#### 模板说明

完整的响应 JSON 示例。

#### 模板示例

```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "has_more": true,
        "page_token": "AQD9/Rn9eij9Pm39ED40/RD/cIFmu77WxpxPB/2oHfQLZ%2BG8JG6tK7%2BZnHiT7COhD2hMSICh/eBl7cpzU6JEC3J7COKNe4jrQ8ExwBCR",
        "items": [
            {
                "union_id": "on_94a1ee5551019f18cd73d9f111898cf2",
                "user_id": "3e3cf96b",
                "open_id": "ou_7dab8a3d3cdcc9da365777c7ad535d62",
                "name": "张三",
                "en_name": "San Zhang",
                "nickname": "Alex Zhang",
                "email": "[REDACTED_SECRET]",
                "mobile": "13011111111",
                "mobile_visible": false,
                "gender": 1,
                "avatar_key": "2500c7a9-5fff-4d9a-a2de-3d59614ae28g",
                "avatar": {
                    "avatar_72": "https://foo.icon.com/xxxx",
                    "avatar_240": "https://foo.icon.com/xxxx",
                    "avatar_640": "https://foo.icon.com/xxxx",
                    "avatar_origin": "https://foo.icon.com/xxxx"
                },
                "status": {
                    "is_frozen": false,
                    "is_resigned": false,
                    "is_activated": true,
                    "is_exited": false,
                    "is_unjoin": false
                },
                "department_ids": [
                    "od-4e6ac4d14bcd5071a37a39de902c7141"
                ],
                "leader_user_id": "ou_7dab8a3d3cdcc9da365777c7ad535d62",
                "city": "杭州",
                "country": "CN",
                "work_station": "北楼-H34",
                "join_time": 2147483647,
                "is_tenant_manager": false,
                "employee_no": "1",
                "employee_type": 1,
                "orders": [
                    {
                        "department_id": "od-4e6ac4d14bcd5071a37a39de902c7141",
                        "user_order": 100,
                        "department_order": 100,
                        "is_primary_dept": true
                    }
                ],
                "custom_attrs": [
                    {
                        "type": "TEXT",
                        "id": "DemoId",
                        "value": {
                            "text": "DemoText",
                            "url": "http://www.fs.cn",
                            "pc_url": "http://www.fs.cn",
                            "option_id": "edcvfrtg",
                            "option_value": "option",
                            "name": "name",
                            "picture_url": "https://xxxxxxxxxxxxxxxxxx",
                            "generic_user": {
                                "id": "9b2fabg5",
                                "type": 1
                            }
                        }
                    }
                ],
                "enterprise_email": "[REDACTED_SECRET]",
                "job_title": "xxxxx",
                "is_frozen": false,
                "geo": "cn",
                "job_level_id": "mga5oa8ayjlp9rb",
                "job_family_id": "mga5oa8ayjlp9rb",
                "department_path": [
                    {
                        "department_id": "od-4e6ac4d14bcd5071a37a39de902c7141",
                        "department_name": {
                            "name": "测试部门名1",
                            "i18n_name": {
                                "zh_cn": "测试部门名1",
                                "ja_jp": "試験部署名 1",
                                "en_us": "Test department name 1"
                            }
                        },
                        "department_path": {
                            "department_ids": [
                                "od-4e6ac4d14bcd5071a37a39de902c7141"
                            ],
                            "department_path_name": {
                                "name": "测试部门名1",
                                "i18n_name": {
                                    "zh_cn": "测试部门名1",
                                    "ja_jp": "試験部署名 1",
                                    "en_us": "Test department name 1"
                                }
                            }
                        }
                    }
                ],
                "dotted_line_leader_user_ids": [
                    "ou_7dab8a3d3cdcc9da365777c7ad535d62"
                ]
            }
        ]
    }
}
```

## 响应码定义

### 模板说明

响应码表格列出该接口可能返回的 HTTP 状态码、错误码或成功码。

**请按以下顺序组织响应码**：

1. **成功码**（2xx）放在最上边，表示请求成功处理
2. **客户端错误码**（4xx）在中间，表示客户端请求问题
3. **服务端错误码**（5xx）在最后，表示服务端错误

这样可以快速区分成功和错误情况。

### 模板示例

| HTTP状态码 | 错误码 | 描述 |
|------------|--------|------|
| 200 | 0 | 请求成功 |
| 400 | 41050 | no user authority error |
| 400 | 40011 | page size is invalid |
| 400 | 40012 | page token is invalid error |
| 403 | 40004 | no dept authority error |

## 附录

### 模板说明

附录是一个总括性的章节，用于存放接口文档的补充信息。

通过模板在生成接口文档时，会根据接口实际情况自动判断是否需要添加额外的补充信息章节，补充信息章节必须用二级分类章节的形式。请参考"模板示例"下的"相关链接"

### 模板示例

#### 相关链接

| 链接类型 | 链接 |
|----------|------|
| 应用权限配置 | [https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN](https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN) |
| 用户相关的 ID 概念 | [https://open.feishu.cn/document/home/user-identity-introduction/introduction](https://open.feishu.cn/document/home/user-identity-introduction/introduction) |
| 部门 ID 说明 | [https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview) |
| 权限范围校验 | [https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority](https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority) |
| 通用错误码 | [https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN) |

path: README.md
content: # README.md - skill-feishu

这个 skill 用于**收集和记录飞书开放平台的 API 文档**，存放在 `open-apis/` 目录下。

## 目的

将飞书开放平台的 API 文档整理成本地 Markdown 文档，方便离线查阅和引用。

## 目录结构

```
skills/skill-feishu/
├── SKILL.md          - Skill 使用规范和规则说明
├── README.md         - 本文档
└── open-apis/        - 飞书 API 文档集合
    ├── README.md     - API 分类说明
    ├── TEMPLATE.md   - API 文档模板
    └── *.md          - 各 API 的完整文档
```

## API 分类

| 分类 | 说明 |
|------|------|
| `auth-*.md` | 认证相关 API（tenant_access_token, user_access_token） |
| `authen-*.md` | OAuth 2.0 认证 API |
| `contact-v3-*.md` | 通讯录 v3 API（用户、部门管理） |
| `im-*.md` | 消息 API |
| `passport-*.md` | 用户登录信息 API |

## 使用说明

1. 查看 `SKILL.md` 了解文档收集规则和禁止操作
2. 参考 `open-apis/TEMPLATE.md` 创建新的 API 文档
3. 已记录的 API 列表见 `open-apis/README.md`


Security scan verdicts — ClawScan: clean | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)