取得部門成員列表

分頁取得指定部門下的直属成員列表。

介面資訊

項目	說明
介面名稱	取得部門成員列表
權限標識	contact.department.read（讀取組織架構）
請求方式	POST / GET
請求地址	https://{gateway_host}/open/v1/contact/user/list
資料格式	application/json（POST 時）或 URL Query
鑑權方式	應用級 access_token（需具備 contact.department.read 權限）

前置條件

1. 應用已在管理後臺「內部應用」中發布並啟用。
2. 已取得有效的應用級 access_token。
3. 目標部門必須在應用的可見範圍內。

請求參數

參數名	類型	必填	說明
access_token	string	是	應用級令牌（未在 Authorization 標頭中攜帶時必填）
dept_id	string	是	部門 ID（正整數字串）。必填，不能省略；單根部門授權時可傳 "1" 作為根映射。相容別名 deptId、departmentId、department_id
cursor	string	否	從 0 開始的數字偏移量，預設 0；相容別名 next_cursor、nextCursor
size	integer	否	每頁成員數，範圍 1–100，預設 100
language	string	否	語言/國際化保留參數，目前不影響返回內容

請求範例

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

{ "dept_id": "20", "cursor": "0", "size": 50 }

GET https://{gateway_host}/open/v1/contact/user/list?dept_id=20&cursor=0&size=50
Authorization: Bearer <access_token>

回應參數

{
  "code": 200,
  "msg": "",
  "data": {
    "users": [{
      "userId": "42", "name": "張三", "avatar": "https://cdn.example.com/avatar/42.png",
      "mobile": "13800000000", "email": "zhangsan@example.com", "jobNumber": "A-001", "title": "工程師", "deptIdList": ["10", "20"]
    }],
    "hasMore": true,
    "nextCursor": "1"
  }
}

欄位	類型	說明
code	integer	業務狀態碼；200 表示成功
msg	string	訊息；成功時為空
data.users	object[]	成員列表；沒有成員時為 []，欄位與取得成員詳情介面一致
data.users[].userId	string	成員 ID
data.users[].name	string	成員暱稱/姓名
data.users[].avatar	string	頭像 URL；未設定時省略
data.users[].mobile	string	手機號碼；未設定時省略
data.users[].email	string	電子郵件；未設定時省略
data.users[].jobNumber	string	工號；未設定時省略
data.users[].title	string	職稱；未設定時省略
data.users[].deptIdList	string[]	成員所屬部門 ID 列表（僅包含可見部門）
data.hasMore	boolean	是否還有更多成員
data.nextCursor	string	下一頁游標；僅在 hasMore=true 時返回，下一次請求作為 cursor 傳入

返回規則與注意事項

1. 只返回直属成員，不遞迴：本介面只返回直接隸屬於指定部門的成員，不會展開子部門成員。需要子部門成員時，先用部門列表介面取得子部門 ID，再逐一呼叫本介面。
2. 欄位完整，不需逐一補查：返回的成員物件包含全部公開成員欄位，不需要再逐一呼叫詳情介面。
3. 按可見範圍過濾：只返回應用可見範圍內的正常成員；應用無權查看的成員即使直接隸屬該部門，也會被省略。
4. 分頁終止條件：嚴格使用 hasMore 和 nextCursor 判斷是否完成，不要用當前頁數量小於 size 判斷。

錯誤碼

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

多語言呼叫範例

Shell

curl -sS -X POST "https://{gateway_host}/open/v1/contact/user/list" -H "Authorization: Bearer access-token-xxx" -H "Content-Type: application/json" -d '{"dept_id":"20","cursor":"0","size":50}'

PHP

<?php
// 生產環境應檢查 HTTP 狀態和回應體，再映射業務錯誤。
$handle = curl_init('https://{gateway_host}/open/v1/contact/user/list'); curl_setopt_array($handle, [CURLOPT_POST => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer access-token-xxx', 'Content-Type: application/json'], CURLOPT_POSTFIELDS => '{"dept_id":"20","cursor":"0","size":50}', 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/user/list", bytes.NewBufferString(`{"dept_id":"20","cursor":"0","size":50}`)); 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/user/list"); curl_easy_setopt(handle, CURLOPT_HTTPHEADER, headers); curl_easy_setopt(handle, CURLOPT_POSTFIELDS, R"({"dept_id":"20","cursor":"0","size":50})"); const CURLcode result = curl_easy_perform(handle); curl_slist_free_all(headers); curl_easy_cleanup(handle); return result == CURLE_OK ? 0 : 1; }