获取部门详情

获取指定部门的节点基础信息。

接口信息

项目	说明
接口名称	获取部门详情
权限标识	contact.department.read（读取组织架构）
请求方式	POST / GET
请求地址	https://{gateway_host}/open/v1/contact/department/get
数据格式	application/json（POST 时）或 URL Query
鉴权方式	应用级 access_token（需具备 contact.department.read 权限）

前置条件

1. 应用已在管理后台「内部应用」中发布并启用。
2. 已获取有效的应用级凭证 access_token。
3. 查询的部门必须处于应用的可见范围之内。

请求参数

请求头

请求头	必填	说明
Authorization	否	Bearer <access_token>，推荐的凭证传递方式（与 Query / 表单三选一）
Content-Type	否	POST 请求使用 JSON 时传 application/json

参数列表

参数支持在 POST JSON Body、POST Form 表单或 GET Query 中传递：

参数名	类型	必填	说明
access_token	string	是	应用级令牌（若未在 Authorization 头中携带，则必填）
dept_id	string	是	部门 ID（正整数字符串）。系统兼容别名 deptId、departmentId、department_id
language	string	否	语言/国际化预留参数，当前不影响返回内容

注：当企业部门树只有一个根节点时，dept_id="1" 会自动映射为该根部门。

请求示例

POST 请求示例：

POST https://{gateway_host}/open/v1/contact/department/get
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "dept_id": "20"
}

GET 请求示例：

GET https://{gateway_host}/open/v1/contact/department/get?dept_id=20
Authorization: Bearer <access_token>

响应参数

成功响应（平台统一响应外壳）：

{
  "code": 200,
  "msg": "",
  "data": {
    "deptId": "20",
    "name": "研发部",
    "parentId": "10",
    "order": 1
  }
}

字段	类型	说明
code	integer	业务状态码，200 表示成功
msg	string	提示信息，成功时为空
data.deptId	string	部门 ID（字符串类型）
data.name	string	部门名称
data.parentId	string	上级部门 ID。若上级部门不在应用可见范围内，系统将自动向上截断并返回 "0"，作为当前可见树的顶层根节点
data.order	integer	该部门在同级父部门下的显示排序权重

权限与可见范围过滤

1. 可见范围判断：若指定部门不存在、已被删除，或不在应用的可见授权范围内，接口统一返回 DEPARTMENT_NOT_FOUND，不暴露企业未授权的部门结构。
2. 虚拟根节点适配：若应用仅被授权了某分支部门，当查询该部门详情时，其 parentId 会表现为 "0"，便于应用端构建可遍历的本地树结构。

错误码说明

鉴权与中间件错误（HTTP 状态码）

HTTP 状态码	msg 错误码	说明
401	INVALID_TOKEN	令牌缺失、已过期、已失效，或应用不可用
403	SCOPE_DENIED	令牌缺少 contact.department.read 权限
403	IP_DENIED	请求来源 IP 未命中应用安全设置的 IP 白名单

业务错误（HTTP 200，code=500）

{
  "code": 500,
  "msg": "DEPARTMENT_NOT_FOUND",
  "data": null
}

msg 错误码	说明与排查建议
INVALID_REQUEST	参数 dept_id 缺失、为空或不是有效的正整数字符串
DEPARTMENT_NOT_FOUND	部门不存在、已被删除，或该部门不在应用的可见授权范围内
PERMISSION_DENIED	应用状态异常（已被停用、取消发布或删除）
SERVER_ERROR	服务端内部异常，请稍后重试

多语言调用示例

以下示例使用服务端调用方式；应用密钥和应用令牌不得下发到客户端。

Shell

curl -sS -X POST "https://{gateway_host}/open/v1/contact/department/get" \
  -H "Authorization: Bearer access-token-xxx" \\\n  -H "Content-Type: application/json" \
  -d '{"dept_id":"20"}'

PHP

<?php
// 中文注释：生产环境应检查 HTTP 状态码和响应体，再映射业务错误。
$handle = curl_init('https://{gateway_host}/open/v1/contact/department/get');
curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => ['Authorization: Bearer access-token-xxx', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => '{"dept_id":"20"}',
    CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($handle);
curl_close($handle);

Golang

package main

import (
    "bytes"
    "net/http"
)

func main() {
    // 中文注释：令牌只在服务端请求中使用，并按接口约定携带。
    request, _ := http.NewRequest(http.MethodPost, "https://{gateway_host}/open/v1/contact/department/get", bytes.NewBufferString(`{"dept_id":"20"}`))
    request.Header.Set("Authorization", "Bearer access-token-xxx")
    request.Header.Set("Content-Type", "application/json")
    response, _ := http.DefaultClient.Do(request)
    defer response.Body.Close()
}

C++

#include <curl/curl.h>

int main() {
    // 中文注释：生产环境应启用 TLS 校验并处理 HTTP 错误。
    CURL* handle = curl_easy_init();
    struct curl_slist* headers = nullptr;
    headers = curl_slist_append(headers, "Authorization: Bearer access-token-xxx");
    headers = curl_slist_append(headers, "Content-Type: application/json");
    curl_easy_setopt(handle, CURLOPT_URL, "https://{gateway_host}/open/v1/contact/department/get");
    curl_easy_setopt(handle, CURLOPT_CUSTOMREQUEST, "POST");
    curl_easy_setopt(handle, CURLOPT_HTTPHEADER, headers);
    curl_easy_setopt(handle, CURLOPT_POSTFIELDS, R"({"dept_id":"20"})");
    const CURLcode result = curl_easy_perform(handle);
    curl_slist_free_all(headers);
    curl_easy_cleanup(handle);
    return result == CURLE_OK ? 0 : 1;
}