> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thedecard.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 查询用户

> 使用用户 ID（或创建用户时的幂等键）查询用户的最新状态，并根据返回结果继续 KYC 或开卡流程。

## 📄 正文

无论您是交易所、钱包还是平台方，都可以在创建用户之后随时查询其最新信息——用户 ID、当前状态与创建/更新时间，便于您在自有系统中核对用户记录、判断是否可进入开卡流程。

查询用户由**接入机构**发起，**DCS** 返回用户的当前快照。

### 前置条件

* 您已持有企业（Enterprise）的 `ApiKey` / `SecretKey`。若尚未领取，请参阅[前置准备](../../getting-started/first-steps)。
* 您已创建过用户。若还未创建，请先完成[创建用户](./create-customer)。

### 步骤

1. 准备用户标识：使用创建用户时返回的 `customerId`，或您在创建时传入的幂等键 `customerRef`（接入机构）。
2. 按[鉴权约定](../../integration-resources/authentication)生成请求头，调用查询接口（接入机构 → DCS）。
3. 从响应 `data` 中读取用户 `status` 与时间字段，在自有系统中核对（接入机构）。

### 查询用户详情

**`GET /open-api/customer/v1/detail`**

#### 查询参数

| 参数            | 位置    | 类型     | 必填 | 说明                   |
| ------------- | ----- | ------ | -- | -------------------- |
| `customerId`  | query | string | 否  | 用户 ID（DCS 创建用户时返回）   |
| `customerRef` | query | string | 否  | 用户幂等字段（接入机构创建用户时自定义） |

> **请注意**：`customerId` 与 `customerRef` 需至少传入其一；二者均未传时无法定位用户。

#### 请求示例

```
GET /open-api/customer/v1/detail?customerId=100000000123
Host: <api-base>
Content-Type: application/json
X-DAPI-API-KEY: <your-api-key>
X-DAPI-TIMESTAMP: 1743044911331
X-DAPI-NONCE: 12345
X-DAPI-SIGN: <signature>
```

> 完整鉴权头（`X-DAPI-API-KEY` / `X-DAPI-TIMESTAMP` / `X-DAPI-NONCE` / `X-DAPI-SIGN`）的生成方式见[鉴权](../../integration-resources/authentication)。

#### 响应示例

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": "success",
  "messageDetail": null,
  "data": {
    "customerId": "100000000123",
    "status": "SUCCEED",
    "createTime": "2025-01-01T12:00:00+08:00",
    "modifyTime": "2025-01-02T09:30:00+08:00"
  }
}
```

#### `data` 字段

| 字段           | 类型     | 说明                                      |
| ------------ | ------ | --------------------------------------- |
| `customerId` | string | 用户 ID                                   |
| `status`     | string | 用户状态，枚举值 `SUCCEED`（接口即此拼写，请按此匹配，详见下方备注） |
| `createTime` | string | 创建时间，格式 `yyyy-MM-dd'T'HH:mm:ss+08:00`   |
| `modifyTime` | string | 最后更新时间，格式 `yyyy-MM-dd'T'HH:mm:ss+08:00` |

> **关于 `status` 取值**：示例值为 `SUCCEED`，表示用户已就绪、可进入后续流程。完整状态取值集合将在后续版本补充说明，集成时请以实际返回值为准。

### 统一响应结构

所有 `/open-api/` 接口返回统一结构，本接口业务数据置于 `data`：

| 字段              | 类型             | 说明                                                                                        |
| --------------- | -------------- | ----------------------------------------------------------------------------------------- |
| `code`          | string         | 系统级返回码，成功为 `SYS_SUCCESS`                                                                  |
| `message`       | string         | 返回消息（如 `success`）                                                                         |
| `messageDetail` | object \| null | 面向终端用户的展示信息（`title`/`message`/`type`/`icon`/`action`/`linkTitle`/`linkUrl`）；成功时通常为 `null` |
| `data`          | object         | 业务数据，见上方字段表                                                                               |

> **请注意**：本接口的「成功」由系统级 `code`（`SYS_SUCCESS`）表示，业务侧的处理结果应以 `data.status` 为准。集成时请以 `code` 判断系统调用是否成功、以 `data` 内业务字段判断用户的业务状态；`messageDetail` 仅在需要面向终端用户展示提示时返回，成功时通常为 `null`。

错误码归类、是否可重试与处置建议，请参阅[错误码](../transactions/decline-codes)。

## 下一步

确认用户状态正常后，即可为其[申请 KYC](../kyc/apply-kyc)，或直接进入[开卡流程](../cards/card-issuing)。