跳至主要内容

取得部門詳情

取得指定部門的節點基本資訊。

介面資訊​

項目說明
介面名稱取得部門詳情
權限標識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. 目標部門必須在應用的可見範圍內。

請求參數​

參數名類型必填說明
access_tokenstring是應用級令牌（未在 Authorization 標頭中攜帶時必填）
dept_idstring是部門 ID（正整數字串）。系統相容別名 deptId、departmentId、department_id
languagestring否語言/國際化保留參數，目前不影響返回內容

注意：當企業部門樹只有一個根節點時，dept_id="1" 會自動映射至該根部門。

請求範例​

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

{ "dept_id": "20" }
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 }
}
欄位類型說明
codeinteger業務狀態碼；200 表示成功
msgstring訊息；成功時為空
data.deptIdstring部門 ID，以字串返回
data.namestring部門名稱
data.parentIdstring父部門 ID。父部門超出應用可見範圍時向上截斷為 "0"，使該部門成為可見樹中的頂層節點
data.orderinteger父部門下的顯示排序權重

權限與可見範圍過濾​

  1. 可見範圍檢查：部門不存在、已刪除或超出應用授權的可見範圍時，介面返回 DEPARTMENT_NOT_FOUND，不洩漏未授權的企業結構。
  2. 虛擬根節點適配：應用只獲得某個分支的權限時，查詢該分支部門會將 parentId 顯示為 "0"，方便客戶端建立可遍歷的本地樹。

錯誤碼​

HTTP 狀態碼msg 錯誤碼說明
401INVALID_TOKEN令牌缺失、過期、撤銷，或應用不可用
403SCOPE_DENIED令牌缺少 contact.department.read 權限
403IP_DENIED來源 IP 不在應用安全設定的 IP 白名單中
200 / code=500INVALID_REQUESTdept_id 缺失、為空或不是合法的正整數字串
200 / code=500DEPARTMENT_NOT_FOUND部門不存在、已刪除或超出應用授權的可見範圍
200 / code=500PERMISSION_DENIED應用狀態無效（已停用、未發布或已刪除）
200 / code=500SERVER_ERROR服務端異常，請稍後重試

多語言呼叫範例​

Shell​

curl -sS -X POST "https://{gateway_host}/open/v1/contact/department/get" -H "Authorization: Bearer access-token-xxx" -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_POST => true, 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"); response, _ := http.DefaultClient.Do(request); defer response.Body.Close() }

C++​

#include <curl/curl.h>
int main() { CURL* handle = curl_easy_init(); struct curl_slist* headers = curl_slist_append(nullptr, "Authorization: Bearer access-token-xxx"); curl_easy_setopt(handle, CURLOPT_URL, "https://{gateway_host}/open/v1/contact/department/get"); 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; }