取得成員詳情

取得指定企業成員的詳細資訊。

介面資訊

項目	說明
介面名稱	取得成員詳情
權限標識	contact.user.read（讀取成員基本資訊）
請求方式	POST / GET
請求地址	https://{gateway_host}/open/v1/contact/user/get
資料格式	application/json（POST 時）或 URL Query
鑑權方式	應用級 access_token（需具備 contact.user.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 標頭中攜帶時必填）
userid	string	是	目標成員使用者 ID（正整數字串）。系統相容別名 userId、user_id
language	string	否	語言/國際化保留參數，目前不影響返回內容

請求範例

POST 請求：

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

{ "userid": "42" }

GET 請求：

GET https://{gateway_host}/open/v1/contact/user/get?userid=42
Authorization: Bearer <access_token>

回應參數

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

欄位	類型	說明
code	integer	業務狀態碼；200 表示成功
msg	string	訊息；成功時為空
data.userId	string	成員 ID，以字串返回以避免大數精度損失
data.name	string	成員暱稱/姓名
data.avatar	string	成員頭像 URL；未設定時省略
data.mobile	string	手機號碼；未設定時省略
data.email	string	電子郵件；未設定時省略
data.jobNumber	string	工號；未設定時省略
data.title	string	職稱；未設定時省略
data.deptIdList	string[]	成員所屬部門 ID 列表（僅包含應用可見範圍內的部門）；無資料時為 []

權限與可見範圍過濾

1. 可見範圍限制：應用只能讀取自己可見範圍內的成員資料。
2. 資料遮罩與保護：內部標記、角色權限設定等管理欄位不會返回。
3. 不存在與不可見等價：目標成員不存在、已停用/刪除或超出應用目前可見範圍時，介面統一返回 USER_NOT_FOUND，避免洩漏企業組織結構。

錯誤碼

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

多語言呼叫範例

以下範例在服務端執行；應用密鑰和令牌不得下發到客戶端。

Shell

curl -sS -X POST "https://{gateway_host}/open/v1/contact/user/get" -H "Authorization: Bearer access-token-xxx" -H "Content-Type: application/json" -d '{"userid":"42"}'

PHP

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