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

# 用户管理

> 讲用户创建之后的日常管理：查询用户当前交易限制（是否禁止提现/卡交易，GET /account/v1/user-status），并作为用户全生命周期各能力的导航入口。

## 📄 正文

在 DeCard 托管模式下，用户（Account）是整个发卡体系的身份基准：它承载终端用户的标识 `externalUserId`、合规状态与交易限制，开卡、充提、消费等所有能力都以它为锚点。作为持牌、自有 BIN 的发卡机构，DCS 在风控与合规侧统一管理用户的交易限制，并通过标准化接口供您随时查询。

本页面向**用户创建之后的日常管理**——查询用户当前的交易限制状态（是否禁止提现 / 禁止卡交易），并作为用户全生命周期各能力的导航入口。如需用户注册，请前往 [用户注册](../signing-up-a-customer/overview)。

## 用户生命周期一览

终端用户从注册到管理，各能力分布在不同页面。本页聚焦「用户状态/交易限制」，其余环节请前往对应页面：

| 环节          | 做什么                              | 去哪一页                                                                |
| ----------- | -------------------------------- | ------------------------------------------------------------------- |
| 注册用户        | 手机号 + OTP 注册，生成 `externalUserId` | [用户注册 › 概述](../signing-up-a-customer/overview)                      |
| KYC 与状态     | KYC 引导页、状态查询、状态机                 | [合规 › 概述](../../basic-concepts/compliance-kyc-flow)                 |
| Travel Rule | 提交/更新资金来源、财富来源等合规信息              | [合规 › 旅行规则](../virtual-accounts/travel-rule)                        |
| 扩展信息 / EDD  | 更新扩展信息、文件预上传、EDD 文件上传            | [接入资源 › H5 KYC 与开卡引导页](../../integration-resources/h5-kyc-guidance) |
| 余额与资产       | 查询可用/冻结余额、充值扣款、流水                | [交易管理 › 用户余额](../managing-transactions/user-balance)                |
| 账户与资产模型     | 独立账户、`free`/`freeze`/`total` 概念  | [账户与资产模型](../../basic-concepts/ledgering-system)                    |

## DCS 承担什么

为保障平台金融操作的合规性与安全性，DCS 会对用户施加交易限制（如禁止提现、禁止卡交易），并提供标准化接口供您随时查询用户的当前限制状态。**限制的设置规则与触发条件由 DCS 风控/合规侧管理**，接入机构通过本接口读取结果，在自有系统中据此引导用户。

## 查询用户状态

用查询接口读取某个用户当前的交易限制：是否禁止提现、是否禁止卡交易。

### 前置条件

* 您已持有企业（Enterprise）的 `ApiKey` / `SecretKey`。若尚未领取，请参阅[前置准备](../../getting-started/first-steps)。
* 您已有目标用户的 `externalUserId`（注册用户时由 DCS 生成）。

### 接口

**`GET /account/v1/user-status`**

#### 查询参数

| 参数               | 位置    | 类型     | 必填 | 说明             |
| ---------------- | ----- | ------ | -- | -------------- |
| `externalUserId` | query | string | ✓  | 用户 ID（注册用户时生成） |

#### 请求示例

```
GET /account/v1/user-status?externalUserId=u_***** HTTP/1.1
Host: <api-base>
<!-- GET 请求无 body，无需 Content-Type 头 -->
```

> 鉴权头的生成方式见[前置准备](../../getting-started/first-steps)。

<Warning>
  示例中 `externalUserId` 使用脱敏占位 `u_*****`，请替换为真实用户 ID（切勿在文档/日志中记录真实 PII）。
</Warning>

#### 响应示例（200）

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": "success",
  "messageDetail": null,
  "data": {
    "forbidWithdraw": false,
    "forbidCardTransaction": false
  }
}
```

#### `data` 字段（用户状态 / 交易限制）

| 字段                      | 类型      | 说明                             |
| ----------------------- | ------- | ------------------------------ |
| `forbidWithdraw`        | boolean | 用户是否禁止提现：`true`=禁止，`false`=允许  |
| `forbidCardTransaction` | boolean | 用户是否禁止卡交易：`true`=禁止，`false`=允许 |

> **如何使用**：当 `forbidWithdraw=true` 时应在自有系统中拦截/隐藏提现入口；当 `forbidCardTransaction=true` 时应提示用户当前卡交易受限。两者相互独立。

### 统一响应结构

所有 `/account/` 接口返回统一结构，本接口业务数据置于 `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` 内字段判断用户的业务状态。

### 错误处理

所有 `/account/` 接口使用统一响应结构。**以 `code` 字段判断调用成功与否**：

* `code` = `SYS_SUCCESS` → 调用成功，业务数据在 `data` 中
* `code` ≠ `SYS_SUCCESS` → 调用失败，应读取 `message` 与 `messageDetail`（`title` / `message` / `type` 等）了解失败原因

#### 典型错误场景

> 下表为网关/参数层错误。业务层失败通常仍返回 HTTP 200，请以响应 `code` 判定业务结果。

| HTTP 状态码      | 典型原因                              | 排查方向                                                                     |
| ------------- | --------------------------------- | ------------------------------------------------------------------------ |
| `400`         | 请求参数缺失或格式错误（如缺少 `externalUserId`） | 检查 query 参数是否完整、值是否符合预期格式                                                |
| `401` / `403` | 鉴权失败（ApiKey 无效、签名错误、secret 过期）    | 检查鉴权头生成方式，见 [鉴权指南](../../integration-resources/overview)                 |
| `404`         | 用户不存在（`externalUserId` 未注册或已注销）   | 核实 `externalUserId` 是否正确，确认用户已完成 [注册](../signing-up-a-customer/overview) |
| `500`         | 服务端异常                             | 重试；持续出现请联系 DCS 技术支持                                                      |

<Warning>
  **注意**：以上 HTTP 状态码为典型场景分类。确切错误码与 `messageDetail` 展示信息以实际返回为准；集成时不应以未列出的错误码做硬编码校验。
</Warning>

## 资产与余额

本页只覆盖**用户状态/交易限制**。用户的资金账户（可用余额 `free` / 冻结余额 `freeze` / 总额 `total`、充值 `credit`、扣款 `debit`、资产流水）属于余额域，不在此页重复展开——请前往：

* 接口与字段全表、可跑示例：[交易管理 › 用户余额](../managing-transactions/user-balance)
* 账户与资产模型（独立账户、`free`/`freeze`/`total` 概念）：[账户与资产模型](../../basic-concepts/ledgering-system)

## 下一步

* 注册用户：[用户注册 › 概述](../signing-up-a-customer/overview)
* Travel Rule：[合规 › 旅行规则](../virtual-accounts/travel-rule)
* 用户余额：[交易管理 › 用户余额](../managing-transactions/user-balance)
* 账户与资产模型：[账户与资产模型](../../basic-concepts/ledgering-system)