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

# 创建用户

> 说明如何创建用户（Customer）、DCS 与接入机构各自负责的事项，以及创建成功后的下一步操作。

## 📄 正文

创建用户是接入合作伙伴自管模式的第一步。无论您的终端用户来自交易所、钱包还是项目方应用，都可以通过一次调用将其登记到 DCS 系统，为后续 KYC 和发卡做好准备。DCS 会在这一步为每位用户分配全局唯一的用户 ID（`customerId`），并安全存储其基本联系信息。

### 用户是后续流程的起点

在合作伙伴自管模式里，额度由接入机构掌握、授权由接入机构决策，但「用户」这一身份实体仍由 DCS 统一管理。一个用户创建成功后，您拿到的 `customerId` 会贯穿后续所有动作：

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/pa-create-customer-light.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=f8374d3108e2d3bb23fc1fbd4552b7ff" alt="用户是后续一切动作的锚点" width="750" height="252" data-path="imgs/diagrams/pa-create-customer-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/pa-create-customer-dark.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=f3984eae06cab44a207f4d6bea3974da" alt="用户是后续一切动作的锚点" width="750" height="252" data-path="imgs/diagrams/pa-create-customer-dark.svg" />
</Frame>

因此，请妥善保存创建成功后返回的 `customerId`，它是后续接口的必填关联键。

### 谁做什么

| 步骤 | 谁做   | 动作                                    |
| -- | ---- | ------------------------------------- |
| 1  | 接入机构 | 准备用户的手机号、邮箱，并生成一个本地唯一的 `customerRef`  |
| 2  | 接入机构 | 调用创建用户接口，提交上述信息                       |
| 3  | DCS  | 校验信息完整性与规范、确保唯一性、分配 `customerId`、安全存储 |
| 4  | 接入机构 | 保存返回的 `customerId`，进入 KYC / 发卡流程      |

### 前置条件

* 已拥有企业（Enterprise）的 `ApiKey` / `SecretKey`，并已按照鉴权要求构造请求头（含 HMAC-SHA256 签名与 Nonce）。如尚未配置，请先参阅 [入驻指南](../../getting-started/first-steps) 与 [鉴权](../../integration-resources/authentication)。
* 已为请求设置 `Content-Type: application/json`。

### 接口

**`POST /open-api/customer/v1/create-customer`**

#### 请求参数

| 字段                 | 类型     | 必填   | 说明                                                                        |
| ------------------ | ------ | ---- | ------------------------------------------------------------------------- |
| `phoneCountryCode` | string | 必填   | 手机号国家码，2 位 ISO 国家码（如 `SG`、`MY`、`KR`、`TH`、`AU`、`JP`、`TW`、`VN`、`PH`）。长度固定 2 |
| `customerRef`      | string | 必填   | 用户幂等字段，由接入机构生成、需保证本地唯一；最大长度 50。相同 `customerRef` 重复提交将命中同一用户，不会重复创建        |
| `phone`            | string | 二选一  | 明文手机号，须带国家前缀、以 `+` 开头，长度 6–30，例如 `+6591234567`。与 `phoneEncryption` 至少填其一  |
| `phoneEncryption`  | string | 二选一  | 手机号密文（AES-GCM）。与 `phone` 至少填其一；若两者都传，**优先使用密文**                           |
| `email`            | string | 二选一  | 明文邮箱，邮箱格式，最大长度 100。与 `emailEncryption` 至少填其一                              |
| `emailEncryption`  | string | 二选一  | 邮箱密文（AES-GCM）。与 `email` 至少填其一；若两者都传，**优先使用密文**                            |
| `encryptionIV`     | string | 条件必填 | AES-GCM 模式的 IV，用于解密 `phoneEncryption` / `emailEncryption`。当使用任一密文字段时必填    |

> **关于明文与密文（必读）**
> 手机号、邮箱两组字段均为「明文 / 密文二选一」：
>
> * 若以明文传输，直接填 `phone` / `email`；
> * 若需在传输层之外再做一层加密（推荐对 PII 敏感的接入机构使用），改填 `phoneEncryption` / `emailEncryption`，并同时提供 `encryptionIV`。加密算法为 **AES-GCM**。
> * 同一字段明文与密文同传时，系统**以密文为准**。

> **字段说明**
> `phoneCountryCode`（国家码）与 `phone`（须以 `+` 开头、带国家前缀）会同时携带国家码信息。两者当前都必须提供：`phoneCountryCode` 作为 libphonenumber 的 2 位 ISO region，`phone` 使用完整 E.164 格式；两者代表的国家必须一致。

#### 最小请求示例（明文）

```json theme={null}
{
  "phoneCountryCode": "SG",
  "phone": "+6591234567",
  "email": "user@example.com",
  "customerRef": "ext-user-0001"
}
```

#### 最小请求示例（密文）

```json theme={null}
{
  "phoneCountryCode": "SG",
  "encryptionIV": "<base64-iv>",
  "phoneEncryption": "<aes-gcm-ciphertext>",
  "emailEncryption": "<aes-gcm-ciphertext>",
  "customerRef": "ext-user-0001"
}
```

#### 响应示例

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": "success",
  "messageDetail": null,
  "data": {
    "customerId": "C1234567890",
    "status": "SUCCEED",
    "createTime": "2026-06-17T10:00:00+08:00",
    "modifyTime": "2026-06-17T10:00:00+08:00"
  }
}
```

#### 响应字段（`data`）

| 字段           | 类型     | 说明                                                                     |
| ------------ | ------ | ---------------------------------------------------------------------- |
| `customerId` | string | 用户唯一 ID，由 DCS 分配；后续 KYC、发卡接口的关联键，请妥善保存                                 |
| `status`     | string | 创建状态，例如 `SUCCEED`。⚠️ 原始拼写为 `SUCCEED`（非标准 `SUCCESS`/`SUCCEEDED`），请按原值匹配 |
| `createTime` | string | 创建时间，格式 `yyyy-MM-dd'T'HH:mm:ssXXX`（含时区偏移，如 `+08:00`）                   |
| `modifyTime` | string | 最后更新时间，格式同上                                                            |

#### 统一响应结构

所有合作伙伴自管接口返回统一结构 `{ code, message, messageDetail, data }`：

| 字段              | 说明                                                                                                             |
| --------------- | -------------------------------------------------------------------------------------------------------------- |
| `code`          | 业务状态码，成功为 `SYS_SUCCESS`；失败见错误码页                                                                                |
| `message`       | 状态简述                                                                                                           |
| `messageDetail` | 结构化提示对象（可含 `title` / `message` / `type` / `icon` / `action` / `linkTitle` / `linkUrl`），主要供前端引导展示；成功时通常为 `null` |
| `data`          | 业务数据，结构随接口而定                                                                                                   |

<Warning>
  **成功语义提示**：请以 `code == "SYS_SUCCESS"` 作为成功判定的唯一依据，而非凭 `messageDetail` 是否有值或 `data.status` 文案推断。错误码与排查建议见 [授权拒绝与错误码](../transactions/decline-codes)。
</Warning>

## 下一步

用户创建成功、拿到 `customerId` 后，下一步是为该用户 [申请 KYC 认证](../kyc/apply-kyc)。KYC 通过后即可 [申请卡片](../cards/card-issuing)。