> ## 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.

# 查询用户 KYC 信息

> 按用户维度查询 KYC 概要（GET /open-api/kyc/v1/detail），并说明它与查询 KYC 工单的区别；当 kycRenewalRequired=true 时，请引导用户更新 KYC 资料。

## 📄 正文

除了按工单查询某一次认证的进度，您还可以按**用户维度**查询该用户当前的 KYC 概要——他的身份证明来自哪个国家、以及他的 KYC 资料是否已到期需要更新。这条接口是您在开卡前做准入判断、以及在日常运营中发现「该用户需要续期」的入口。

## 与「查询 KYC 工单」的区别

两条接口都叫「查 KYC」，但视角不同，容易混：

|       | 查询 KYC 工单                            | 查询用户 KYC 信息（本页）               |
| ----- | ------------------------------------ | ----------------------------- |
| 接口    | `GET /open-api/kyc-ticket/v1/detail` | `GET /open-api/kyc/v1/detail` |
| 请求参数  | `kycTicketId` 或 `kycTicketRef`       | `customerId`                  |
| 回答的问题 | **这一次**认证进行到哪一步了、被拒的原因是什么            | **这个用户**当前的 KYC 概要，资料是否到期     |
| 典型用途  | 提交 KYC 后轮询结果                         | 开卡前准入判断、发现需要续期                |

工单维度的查询见[查询 KYC](./query-kyc)。

## 接口

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

### 查询参数

| 参数           | 位置    | 类型     |  必填 | 说明             |
| ------------ | ----- | ------ | :-: | -------------- |
| `customerId` | query | string |  是  | 用户 ID（创建用户时返回） |

### 请求示例

```
GET /open-api/kyc/v1/detail?customerId=1000000123
```

### 响应示例

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": null,
  "data": {
    "poiCountryCode": "SG",
    "kycRenewalRequired": false
  }
}
```

### `data` 字段

| 字段                   | 类型      | 说明                                                  |
| -------------------- | ------- | --------------------------------------------------- |
| `poiCountryCode`     | string  | 身份证明（POI）签发国家码，2 位 ISO，如 `CN` / `US` / `SG`         |
| `kycRenewalRequired` | boolean | 该用户的 KYC 资料是否需要更新。`true` 表示证件 / KYC 资料已到期，需引导用户重新认证 |

> 统一响应结构为 `{ code, message, messageDetail, data }`，成败以 `code == "SYS_SUCCESS"` 判断。字段含义见[鉴权指南](../../integration-resources/authentication)。

## `kycRenewalRequired=true` 之后怎么办

`kycRenewalRequired` 为 `true` 表示该用户的证件 / KYC 资料已过期，需要重新完成一次认证。**在更新完成前，该用户的部分操作（如消费）可能被限制。**

您有两种途径感知这件事，两者取值一致：

* **主动查**：调用本接口，读 `kycRenewalRequired`。
* **被动收**：DCS 会通过用户级 [`KYC` Webhook](../webhooks/events-and-schema#kyc) 推送 `kycRenewalRequired=true`，并在 `kycRenewalType` 中给出需要更新的因子（`POI` / `SELFIE`），便于您在前端只提示该补的那一项。

引导用户完成更新的完整两步流程，见[更新 KYC 资料](./kyc-renewal)。更新通过后，DCS 会再推一条 `kycRenewalRequired=false` 解除限制。

## 前置条件

* 已拥有企业（Enterprise）的 ApiKey / SecretKey，见[前置准备](../../getting-started/first-steps)。
* 已创建用户并拿到 `customerId`，见[创建用户](../users/create-customer)。

## 下一步

* 用户需要更新资料 → [更新 KYC 资料](./kyc-renewal)
* 查询某一次认证的进度 → [查询 KYC](./query-kyc)
* 复用用户在 DeCard 托管模式已有的 KYC → [KYC 信息迁移](./kyc-migration)