服务端 API/通讯录/部门/获取父部门信息
# 获取父部门信息

该接口用来递归获取部门父部门的信息，并按照由子到父的顺序返回有权限的父部门信息列表。

**注意事项**：使用`tenant_access_token`时,该接口只返回可见性范围内的父部门信息。
例如：A >>B>>C>>D四级部门，通讯录权限只到B，那么查询D部门的parent，会返回B和C两级部门。
使用user_access_token时,该接口只返回对于用户可见的父部门信息。

## 请求

基本 |  
---|---
HTTP URL | https://open.larksuite.com/open-apis/contact/v3/departments/parent
HTTP Method | GET
支持的应用类型 | Custom App、Store App
权限要求<br>**调用该 API 所需的权限。开启其中任意一项权限即可调用**<br>开启任一权限即可 | 以应用身份读取通讯录(contact:contact:readonly_as_app)<br>获取部门组织架构信息(contact:department.organize:readonly)<br>以应用身份访问通讯录(contact:contact:access_as_app)<br>读取通讯录(contact:contact:readonly)
字段权限要求 | **注意事项**：该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请<br>获取部门组织架构信息(contact:department.organize:readonly)<br>以应用身份读取通讯录(contact:contact:readonly_as_app)<br>获取部门基础信息(contact:department.base:readonly)<br>获取用户 user ID(contact:user.employee_id:readonly)<br>以应用身份访问通讯录(contact:contact:access_as_app)<br>读取通讯录(contact:contact:readonly)

### 请求头

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

### 查询参数

名称 | 类型 | 必填 | 描述
---|---|---|---
user_id_type | string | 否 | 用户 ID 类型<br>**示例值**："open_id"<br>**可选值有**：<br>- open_id：标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。[了解更多：如何获取 Open ID](https://open.larksuite.com/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-openid)<br>- union_id：标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。[了解更多：如何获取 Union ID？](https://open.larksuite.com/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-union-id)<br>- user_id：标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。[了解更多：如何获取 User ID？](https://open.larksuite.com/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-user-id)<br>**默认值**：`open_id`<br>**当值为 `user_id`，字段权限要求**：<br>获取用户 user ID(contact:user.employee_id:readonly)
department_id_type | string | 否 | 此次调用中使用的部门ID的类型<br>**示例值**："open_department_id"<br>**可选值有**：<br>- department_id：用来标识租户内一个唯一的部门<br>- open_department_id：用来在具体某个应用中标识一个部门，同一个部门 在不同应用中的 open_department_id 不相同。
department_id | string | 是 | 部门ID<br>**示例值**："od-4e6ac4d14bcd5071a37a39de902c7141"
page_token | string | 否 | 分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果<br>**示例值**："AQD9/Rn9eij9Pm39ED40/RD/cIFmu77WxpxPB/2oHfQLZ%2BG8JG6tK7%2BZnHiT7COhD2hMSICh/eBl7cpzU6JEC3J7COKNe4jrQ8ExwBCR"
page_size | int | 否 | 分页大小<br>**示例值**：10<br>**默认值**：`20`<br>**数据校验规则**：<br>- 最大值：`50`

## 响应

### 响应体

名称 | 类型 | 描述
---|---|---
code | int | 错误码，非 0 表示失败
msg | string | 错误描述
data | \- | \-
has_more | boolean | 是否还有更多项
page_token | string | 分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token
items | department\[\] | &nbsp;
name | string | 部门名称<br>**字段权限要求（满足任一）**：<br>以应用身份读取通讯录(contact:contact:readonly_as_app)<br>获取部门基础信息(contact:department.base:readonly)<br>以应用身份访问通讯录(contact:contact:access_as_app)<br>读取通讯录(contact:contact:readonly)
i18n_name | department_i18n_name | 国际化的部门名称<br>**字段权限要求（满足任一）**：<br>以应用身份读取通讯录(contact:contact:readonly_as_app)<br>获取部门基础信息(contact:department.base:readonly)<br>以应用身份访问通讯录(contact:contact:access_as_app)<br>读取通讯录(contact:contact:readonly)
zh_cn | string | 部门的中文名
ja_jp | string | 部门的日文名
en_us | string | 部门的英文名
parent_department_id | string | 父部门的ID<br>* 在根部门下创建新部门，该参数值为 “0”<br>**字段权限要求（满足任一）**：<br>以应用身份读取通讯录(contact:contact:readonly_as_app)<br>获取部门组织架构信息(contact:department.organize:readonly)<br>以应用身份访问通讯录(contact:contact:access_as_app)<br>读取通讯录(contact:contact:readonly)
department_id | string | 本部门的自定义部门ID<br>注意：除需要满足正则规则外，同时不能以`od-`开头<br>**字段权限要求（满足任一）**：<br>以应用身份读取通讯录(contact:contact:readonly_as_app)<br>获取部门基础信息(contact:department.base:readonly)<br>以应用身份访问通讯录(contact:contact:access_as_app)<br>读取通讯录(contact:contact:readonly)
open_department_id | string | 部门的open_id，类型与通过请求的查询参数传入的department_id_type相同
leader_user_id | string | 部门主管用户ID<br>**字段权限要求（满足任一）**：<br>以应用身份读取通讯录(contact:contact:readonly_as_app)<br>获取部门组织架构信息(contact:department.organize:readonly)<br>以应用身份访问通讯录(contact:contact:access_as_app)<br>读取通讯录(contact:contact:readonly)
chat_id | string | 部门群ID<br>**字段权限要求（满足任一）**：<br>以应用身份读取通讯录(contact:contact:readonly_as_app)<br>获取部门基础信息(contact:department.base:readonly)<br>以应用身份访问通讯录(contact:contact:access_as_app)<br>读取通讯录(contact:contact:readonly)
order | string | 部门的排序，即部门在其同级部门的展示顺序<br>**字段权限要求（满足任一）**：<br>以应用身份读取通讯录(contact:contact:readonly_as_app)<br>获取部门组织架构信息(contact:department.organize:readonly)<br>以应用身份访问通讯录(contact:contact:access_as_app)<br>读取通讯录(contact:contact:readonly)
unit_ids | string\[\] | 部门单位自定义ID列表，当前只支持一个<br>**字段权限要求（满足任一）**：<br>以应用身份读取通讯录(contact:contact:readonly_as_app)<br>获取部门组织架构信息(contact:department.organize:readonly)<br>以应用身份访问通讯录(contact:contact:access_as_app)<br>读取通讯录(contact:contact:readonly)
member_count | int | 部门下用户的个数<br>**字段权限要求（满足任一）**：<br>以应用身份读取通讯录(contact:contact:readonly_as_app)<br>获取部门组织架构信息(contact:department.organize:readonly)<br>以应用身份访问通讯录(contact:contact:access_as_app)<br>读取通讯录(contact:contact:readonly)
status | department_status | 部门状态<br>**字段权限要求（满足任一）**：<br>以应用身份读取通讯录(contact:contact:readonly_as_app)<br>获取部门基础信息(contact:department.base:readonly)<br>以应用身份访问通讯录(contact:contact:access_as_app)<br>读取通讯录(contact:contact:readonly)
is_deleted | boolean | 是否被删除
leaders | departmentLeader\[\] | 部门负责人
leaderType | int | 负责人类型<br>**可选值有**：<br>- 1：主负责人<br>- 2：副负责人
leaderID | string | 负责人ID<br>**字段权限要求（满足任一）**：<br>以应用身份读取通讯录(contact:contact:readonly_as_app)<br>获取部门组织架构信息(contact:department.organize:readonly)<br>以应用身份访问通讯录(contact:contact:access_as_app)<br>读取通讯录(contact:contact:readonly)
group_chat_employee_types | int\[\] | 部门群雇员类型限制。[]空列表时，表示为无任何雇员类型。类型字段可包含以下值，支持多个类型值；若有多个，用英文','分隔：<br>1、正式员工<br>2、实习生<br>3、外包<br>4、劳务<br>5、顾问<br>6、其他自定义类型字段，可通过下方接口获取到该租户的自定义员工类型的名称，参见[获取人员类型](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/employee_type_enum/list)。

### 响应体示例
```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,2,3]
                ]
            }
        ]
    }
}
```

### 错误码

HTTP状态码 | 错误码 | 描述 | 排查建议
---|---|---|---
409 | 43001 | dept unit repeat error | 部门unit id冲突。
409 | 43002 | dept unit is still using error | 部门unit id已存在。
409 | 43003 | multi dept unit error | 存在多个部门unit id。
400 | 43004 | illegal unit error | 部门unit id无效。
400 | 43005 | duplicate order error | 部门的order必须唯一，请检查后重试。
400 | 40001 | param error | 参数错误。
400 | 43007 | duplicated department custom id error | 部门自定义ID 企业内重复
400 | 43008 | custom dept id invalid error | 部门自定义ID不合法，不得以od-开头，不能为“0”，长度不可超过64。
400 | 43009 | exceed update custom dept limit error | 超过部门自定义id次数限制。
400 | 43010 | big dept forbid recursion error | 超大部门不允许进行查询。
400 | 43013 | dept too many children error | 子部门数量过多。
400 | 43011 | delete has member dept error | 待删除的部门下不能包含用户，请检查部门中是否还有未删除的用户。
400 | 43012 | delete has sub dept department error | 待删除的部门下不能包含部门，请检查部门中是否还有未删除的子部门。
400 | 40002 | process root dept error | 不能对根部门进行移除
400 | 40003 | internal error | 内部错误，请提供 X-Request-Id向客服反馈。[联系客服](https://applink.larksuite.com/client/helpdesk/open?id=6626260912531570952&extra=%7B%22channel%22%3A14%2C%22created_at%22%3A1614493146%2C%22scenario_id%22%3A6885151765134622721%2C%22signature%22%3A%22ca94c408b966dc1de2083e5bbcd418294c146e98%22%7D)。
403 | 40004 | no dept authority error | 操作的部门需在通讯录权限范围中，[了解更多](https://open.larksuite.com/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority)
400 | 40008 | dept Info is null error | 部门的信息不能为空
400 | 40010 | chat id is invalid error | 部门群ID格式错误。
403 | 40014 | no parent dept authority error | 没有父部门权限（组织架构可见范围权限）。
400 | 40011 | page size is invalid | 无效的分页参数
400 | 40012 | page token is invalid error | page token无效。
401 | 42008 | tenant id is invalid error | 请检查请求租户是否为合法租户。
400 | 44102 | miss department_id error | 请求缺少department_id