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

# 用户

> 了解 KillB 中的用户管理和 KYC

## 什么是用户？

KillB 中的**用户**代表可以执行 ramp 交易的个人或企业实体。用户在交易前必须完成了解您的客户（KYC）或了解您的业务（KYB）验证。

<Info>
  KillB 中的每笔交易都必须与已验证的用户关联，以符合监管要求。
</Info>

## 用户类型

<Tabs>
  <Tab title="PERSON">
    个人用户（自然人）

    **必需信息：**

    * 全名（名、中、姓）
    * 出生日期
    * 电子邮件和电话
    * 物理地址
    * 政府颁发的 ID
    * 国籍和公民身份

    **用例：**

    * 个人汇款
    * 个人投资
    * 个人加密货币购买

    **示例：**

    ```json theme={null}
    {
      "type": "PERSON",
      "data": {
        "firstName": "Juan",
        "lastName": "García",
        "dateOfBirth": "1990-05-15",
        "email": "juan@example.com",
        "phone": "+573001234567",
        "document": {
          "type": "NUIP",
          "number": "1234567890",
          "issuedCountryCode": "CO"
        }
      }
    }
    ```
  </Tab>

  <Tab title="COMPANY">
    企业实体和公司

    **必需信息：**

    * 公司名称和商号
    * 注册号码
    * 法律结构
    * 营业地址
    * 税务 ID（NIT、EIN、RFC 等）
    * 所有者信息

    **用例：**

    * 企业支付
    * 企业资金管理
    * B2B 交易
    * 工资服务

    **示例：**

    ```json theme={null}
    {
      "type": "COMPANY",
      "data": {
        "companyName": "Acme Corp SAS",
        "tradeName": "Acme",
        "registeredNumber": "900123456",
        "legalStructure": "LLC",
        "email": "business@acme.com",
        "document": {
          "type": "NIT",
          "number": "900123456-1",
          "issuedCountryCode": "CO"
        }
      }
    }
    ```
  </Tab>
</Tabs>

## 用户状态

用户可以有不同的状态：

| 状态         | 描述          | 可以交易？ |
| ---------- | ----------- | ----- |
| `ACTIVE`   | 用户已验证并批准    | ✅ 是   |
| `PENDING`  | KYC 文档正在审查中 | ❌ 否   |
| `REJECTED` | KYC 验证失败    | ❌ 否   |

<Tip>
  所有操作都应以 `status === ACTIVE` 为准。如果用户为 `PENDING`，请将其引导到 `complianceUrl` 完成验证。
</Tip>

## 必需文档

### 个人文档

<Tabs>
  <Tab title="哥伦比亚">
    * **NUIP** (Número Único de Identificación Personal)
    * **Cédula de Ciudadanía** (CC)
    * **护照**
    * **驾照**
  </Tab>

  <Tab title="墨西哥">
    * **INE** (Instituto Nacional Electoral)
    * **IFE** (INE 的旧版本)
    * **护照**
    * **RFC** (税务 ID)
    * **CURP** (人口登记 ID)
  </Tab>

  <Tab title="美国">
    * **护照**
    * **驾照**
    * **SSN** (社会保障号码)
  </Tab>

  <Tab title="其他国家">
    * **护照**（普遍接受）
    * **国民身份证**
    * **DNI** (Documento Nacional de Identidad)
  </Tab>
</Tabs>

### 公司文档

* **NIT**（哥伦比亚）- 税务识别号码
* **RFC**（墨西哥）- 联邦纳税人登记
* **EIN**（美国）- 雇主识别号码
* **CNPJ**（巴西）- 法人实体国家登记
* **CUIT**（阿根廷）- 唯一税务识别代码

## 外部 ID

`externalId` 字段允许您将 KillB 用户链接到您自己的用户系统：

```json theme={null}
{
  "type": "PERSON",
  "externalId": "user_abc123_from_my_system",
  "data": { ... }
}
```

**优势：**

* 将 KillB 用户映射到您的数据库
* 避免重复创建用户
* 简化用户查找
* 保持引用完整性

<Tip>
  使用您的内部用户 ID 作为 `externalId`，以便在系统之间轻松映射。
</Tip>

## 用户属性

### 核心字段

| 字段              | 类型     | 必需 | 描述                      |
| --------------- | ------ | -- | ----------------------- |
| `id`            | UUID   | 自动 | KillB 生成的用户 ID          |
| `type`          | Enum   | ✅  | PERSON 或 COMPANY        |
| `status`        | Enum   | 自动 | ACTIVE、PENDING、REJECTED |
| `customerId`    | UUID   | 自动 | 您的客户 ID                 |
| `externalId`    | String | 可选 | 您系统的用户 ID               |
| `complianceUrl` | URL    | 自动 | KYC 验证门户                |

### 个人特定字段

* `firstName`、`middleName`、`lastName`
* `dateOfBirth`
* `nationality`、`citizenship`
* `employmentStatus`、`occupation`
* `employerName`、`employmentDescription`

### 公司特定字段

* `companyName`、`tradeName`
* `registeredNumber`
* `legalStructure`（LLC、C\_CORP、S\_CORP 等）
* `establishedOn`
* `naics`、`naicsDescription`
* `mainOwnerUser`、`ownerUsers[]`

## 投资档案

用户必须提供投资档案以符合合规要求：

```json theme={null}
{
  "investmentProfile": {
    "primarySourceOfFunds": "EMPLOYMENT",
    "primarySourceOfFundsDescription": "Software engineer salary",
    "totalAssets": "TEN_TO_100K",
    "usdValueOfFiat": "TEN_TO_100K",
    "monthlyDeposits": "UPTO_5",
    "monthlyWithdrawals": "UPTO_5",
    "monthlyInvestmentDeposit": "ONE_TO_100K",
    "monthlyInvestmentWithdrawal": "UPTO_1K",
    "usdValueOfCrypto": "TEN_TO_100K",
    "monthlyCryptoDeposits": "UPTO_5",
    "monthlyCryptoWithdrawals": "UPTO_5"
  }
}
```

### 资金来源选项

* `EMPLOYMENT` - 工资/薪水
* `SAVINGS` - 个人储蓄
* `INVESTMENT` - 投资收益
* `COMPANY` - 业务收入
* `REAL_ESTATE` - 房地产收入
* `TRUST` - 信托基金
* `OTHER` - 其他来源

## KYC 档案

反洗钱和合规信息：

```json theme={null}
{
  "kycProfile": {
    "fundsSendReceiveJurisdictions": ["CO", "US", "MX"],
    "engageInActivities": ["NONE"]
  }
}
```

### 禁止活动

用户必须确认他们不从事：

* `ADULT_ENTERTAINMENT`
* `DRUGS`
* `FIREARMS`
* `GAMBLING`
* `MARIJUANA`
* `TUMBLING`（加密货币混合）

## 管理用户

### 创建用户

```bash theme={null}
POST /api/v2/users
```

查看[创建用户指南](/zh/guides/users/create-user)了解详细示例。

### 查询用户

```bash theme={null}
GET /api/v2/users?type=PERSON&email=user@example.com
```

**过滤选项：**

* `type` - PERSON 或 COMPANY
* `firstName`、`lastName`、`email`
* `externalId` - 您的系统 ID
* `customerId` - 按客户过滤

### 更新用户

```bash theme={null}
PATCH /api/v2/users/{userId}
```

更新用户信息、上传额外文档或修改档案数据。

### 删除用户

```bash theme={null}
DELETE /api/v2/users/{userId}
```

<Warning>
  用户删除是软删除。用户数据为合规目的而保留，但标记为非活动。
</Warning>

## 最佳实践

<AccordionGroup>
  <Accordion title="收集准确信息" icon="clipboard-check">
    * 在提交前验证数据格式
    * 确保姓名与政府 ID 完全匹配
    * 使用正确的电话号码格式（+\[国家代码]\[号码]）
    * 验证电子邮件地址
    * 确认地址完整且准确
  </Accordion>

  <Accordion title="使用外部 ID" icon="link">
    * 始终提供 `externalId`
    * 使用您的内部用户 ID
    * 实现轻松查找和对账
    * 防止重复创建用户
  </Accordion>

  <Accordion title="处理 KYC 状态" icon="hourglass">
    * 在允许交易前检查 `status`
    * 引导用户进行下一步验证
    * 监控 `complianceUrl` 以获取 KYC 更新
  </Accordion>

  <Accordion title="存储用户 ID" icon="database">
    * 在您的数据库中存储 KillB `userId`
    * 映射到您的 `externalId`
    * 适当缓存用户数据
    * 通过 webhooks 同步状态更改
  </Accordion>
</AccordionGroup>

## 常见问题

<AccordionGroup>
  <Accordion title="一个人可以有多个用户配置文件吗？">
    不可以。每个独特的个人应该只有一个用户配置文件。对所有交易使用相同的用户 ID。
  </Accordion>

  <Accordion title="KYC 验证需要多长时间？">
    通常从几分钟到 24 小时不等，具体取决于提交信息的完整性以及是否需要人工审查。
  </Accordion>

  <Accordion title="创建后可以更新用户信息吗？">
    可以，使用 PATCH `/api/v2/users/{id}` 端点。某些字段需要重新验证。
  </Accordion>

  <Accordion title="如果 KYC 被拒绝会怎样？">
    用户状态变为 `REJECTED`，他们无法交易。检查 `note` 字段了解拒绝原因。用户可以重新提交更正后的信息。
  </Accordion>
</AccordionGroup>

## 下一步

<CardGroup cols={2}>
  <Card title="创建您的第一个用户" icon="user-plus" href="/zh/guides/users/create-user">
    遵循分步指南创建用户
  </Card>

  <Card title="了解账户" icon="wallet" href="/zh/concepts/accounts">
    了解银行账户和钱包
  </Card>

  <Card title="API 参考" icon="code" href="/api-reference/endpoint/users-create">
    查看完整的用户 API 文档
  </Card>
</CardGroup>