获取成员详情

获取指定企业成员的详细信息。

接口信息

项目	说明
接口名称	获取成员详情
权限标识	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	成员头像地址，未设置时不返回此字段
data.mobile	string	手机号，未设置时不返回此字段
data.email	string	邮箱地址，未设置时不返回此字段
data.jobNumber	string	员工工号，未设置时不返回此字段
data.title	string	职位名称，未设置时不返回此字段
data.deptIdList	string[]	成员所属部门 ID 列表（仅包含应用可见范围内的部门 ID），无部门时为 []

权限与可见范围过滤

1. 可见范围限制：应用仅能读取自身可见范围内的成员数据。
2. 数据脱敏与保护：管理后台的内部管理字段（如内部标记、角色权限配置等）不会对外返回。
3. 不存在与不可见同义：若请求的成员不存在、已注销，或者超出应用当前可见范围，接口均统一返回 USER_NOT_FOUND，以避免泄露企业组织架构信息。

错误码说明

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

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

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

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

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

多语言调用示例

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

Shell

curl -sS -X POST "https://{gateway_host}/open/v1/contact/user/get" \
  -H "Authorization: Bearer access-token-xxx" \\\n  -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_CUSTOMREQUEST => 'POST',
    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")
    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/user/get");
    curl_easy_setopt(handle, CURLOPT_CUSTOMREQUEST, "POST");
    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;
}