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

# 注册并验证企业

> 端到端了解企业注册与 KYB 验证如何运作：所需准备、调用顺序，以及如何跟踪申请直至获得决策。

## 概述

Fluz KYB（Know Your Business）允许你的平台在自有 UI 中将企业接入 Fluz 轨道。通过一小组操作你将：

1. 确定该实体从事的企业类别与子类别，
2. 提交法律实体信息——法定名称、组织形式、税号、注册州、法定地址，以及账户的预期用途——连同最终受益所有人名单，
3. 为需要的所有者完成身份验证，及
4. 将产生的 **KYB 案件**跟踪至通过或被拒。

提交本身是一个单一的 mutation，[registerBusiness](/business-registration)。它会立即返回一个 `accountId`，同时 `kybStatus` 为 `SUBMITTED`。

<Note>
  **注册表示通过校验，不等于审批。** `success` 响应仅确认载荷通过了校验并已开启 KYB 案件。它并不意味着企业已获批。请将集成构建为在状态批准之前，不尝试为账户入金或发行卡片。
</Note>

### 企业账户能解锁什么

一旦 KYB 获批，企业账户可用于平台的商业功能：

* 企业消费账户与余额
* 商业虚拟卡，包括批量发卡
* 授权用户与卡级别的消费控制
* 卡片、转账与报销的审批流程
* 企业级别的交易报告与费用注释

### 何时使用这些端点

当你希望在自有 UI 中收集实体与所有权数据，而不是将用户引导到 Fluz 托管的体验时，使用该流程。若你更希望由 Fluz 托管资料收集与文档上传，请联系你的客户经理，了解基于组件的上手方案。

***

## KYB 流程

### 分步说明

<Steps>
  <Step title="步骤 0 — 满足前置条件">
    这些不属于流程的一部分，但都必须在调用 `registerBusiness` 前成立。每行链接到下文详情。见[前置条件](#prerequisites)
  </Step>

  <Step title="确定企业类别与子类别">
    调用 [getBusinessCategories](/business-categories)，让用户选择一个类别及其下的某个子类别。
  </Step>

  <Step title="如适用，上传授权签字人文件">
    仅当申请人持股少于 25% **且** 非控制人时需要。先上传文档，然后将返回的 URL 传入 `authorizedSignerDocumentUrl`。见[提交企业文件](/submit-business-documents)。
  </Step>

  <Step title="提交 registerBusiness mutation">
    在一次调用中发送完整的实体信息、所有权声明，以及每位所有者。校验错误会在载荷内返回——见[响应详情](/business-registration#response-details)。
  </Step>

  <Step title="让剩余所有者完成验证">
    读取 [getBusiness](/business-status) 查看每位所有者的预期验证方式与当前进度。对于走文档验证路径的所有者，使用 [requestOwnerDocumentVerificationLink](/owner-verification-link) 生成链接并发送给他们。被邀请的所有者会由 Fluz 发送邮件，自行完成验证。
  </Step>

  <Step title="等待 KYB 决策，然后配置上线">
    申请会进入审核中。将该状态展示给你的用户，而非暗示已经上线。一旦状态变为 `APPROVED`，创建消费账户并发行卡片。
  </Step>
</Steps>

### 端到端时序

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant App as Your Application
    participant API as Fluz GraphQL API
    participant Files as Fluz File Upload (REST)
    participant KYB as Fluz Compliance / KYB
    participant Owner as Business Owner

    Note over App,API: Step 0 — the applicant is already a verified Fluz user
    App->>API: query getBusinessCategories
    API-->>App: businessCategoryId + businessSubCategoryId values

    opt Applicant is an authorized signer
        App->>Files: Upload authorization document
        Files-->>App: document URL
    end

    Note over App,API: Step 1 — submit the business
    App->>API: mutation registerBusiness(input)
    alt Validation fails
        API-->>App: success false, with error code and message
        App->>App: Correct the field and resubmit
    else Validation passes
        API-->>App: accountId plus kybStatus SUBMITTED
        API->>KYB: Open KYB case
    end

    Note over App,Owner: Step 2 — owners verify identity
    opt Owner must verify by document
        App->>API: requestOwnerDocumentVerificationLink
        API-->>App: verificationLink
        App->>Owner: Forward the link
        Owner->>KYB: Completes verification
    end

    Note over KYB,App: Step 3 — asynchronous review
    KYB->>KYB: Entity, tax ID, address, and owner checks
    KYB-->>API: Decision (or request for more documentation)
    App->>API: KYB_STATUS_UPDATE webhook, or query getBusiness
    API-->>App: Updated KYB status and owner roster

    Note over App,API: Step 4 — go live
    App->>API: Create spend accounts and issue cards
```

***

## 前置条件

| 前置条件                                                               | 若缺失         |
| ------------------------------------------------------------------ | ----------- |
| 你的应用请求了 [`REGISTER_BUSINESS` 权限范围](#application-permission-scopes) | `AUTH-0031` |
| 申请人已为你的应用[授权](#applicant-authorization)其所请求的企业权限范围                 | `AUTH-0008` |
| 申请人[已通过 CIP 验证](#the-applicant-must-already-be-identity-verified)  | `ARG-0001`  |
| 申请人[没有正在进行中的 KYB 申请](#one-open-application-per-user)               | `BS-0007`   |
| 你持有[每个操作所需账户类型的 Bearer 令牌](#access-tokens)                         | `AUTH-0002` |
| 若申请人为授权签字人，已上传授权签字人文件                                              | `ARG-0001`  |
| 企业法定地址为真实且可验证的地址                                                   | `BS-0002`   |

### 应用权限范围

在 Fluz 仪表板为你的应用选择 **`REGISTER_BUSINESS`** 权限范围。每个 KYB 操作都需要它，而令牌只能携带你的应用已配置可请求的范围。见 [Application Scopes](/fluz-dashboard/application-scopes)。

订阅 [`KYB_STATUS_UPDATE` webhook](#tracking-an-application) 也需要相同的范围。

### 申请人授权

申请人必须已为你的应用完成 OAuth 授权，且该授权需覆盖你的应用所请求的每个企业范围。若你后来新增了范围，现有用户必须重新授权后方可注册企业——否则注册会以 `AUTH-0008` 失败。

### 申请人必须已通过 CIP 验证

Bearer 令牌标识的是**申请人**：提交申请的用户。名单中必须恰有一位所有者与该令牌用户的**邮箱**（不区分大小写）或**电话号码**匹配，且该所有者不可标记为 `isInvited: true`。

KYB 验证的是企业及“其他”所有者，不会验证申请人本人，因此申请人必须事先达到已验证状态。你为其发送的 `isUsPerson` 值决定适用的检查：

| 申请人 `isUsPerson` | 注册前所需状态             |
| ---------------- | ------------------- |
| `true`           | 已存在成功的 SSN（CIP）验证记录 |
| `false`          | 已存在成功的文档验证记录        |

身份验证在 KYB 之外进行，使用 `VERIFY_KYC` 范围，通过 `verifyUserInformation`、`verifyUserPrefillInformation`，或 `requestDocumentVerificationLink`。见[身份验证（KYC）](/docs/user-kyc-verification)。若该人尚无 Fluz 账户，请先使用 [registerUser](/user-registration) 创建。

### 每位用户一次只能有一个进行中的申请

在现有申请仍未关闭时，用户不能发起新的注册——否则返回 `BS-0007`。

<Warning>
  不提供幂等键，也没有取消进行中申请的 API。被拒的申请不会留下任何记录，可以重新提交，但**成功**的申请会阻止用户在其解决前再次注册。请在提交前做好校验，若案件似乎停滞，请联系你的客户经理并提供 `accountId`。
</Warning>

### 访问令牌

每个操作需要特定账户类型的 Bearer 令牌：

| 操作                                                               | 令牌账户类型     | 所需范围                |
| ---------------------------------------------------------------- | ---------- | ------------------- |
| [getBusinessCategories](/business-categories)                    | `CONSUMER` | `REGISTER_BUSINESS` |
| [registerBusiness](/business-registration)                       | `CONSUMER` | `REGISTER_BUSINESS` |
| [getBusiness](/business-status)                                  | `BUSINESS` | `REGISTER_BUSINESS` |
| [requestOwnerDocumentVerificationLink](/owner-verification-link) | `BUSINESS` | `REGISTER_BUSINESS` |

<Note>
  使用 `generateUserAccessToken` 生成 Mint Bearer 令牌——参见 API 参考的 Authentication 章节。
</Note>

***

## KYB 状态生命周期

```mermaid theme={null}
stateDiagram-v2
    [*] --> SUBMITTED: registerBusiness returns accountId
    SUBMITTED --> PENDING: Case under review
    PENDING --> PENDING: Owners still verifying, or more documentation requested
    PENDING --> APPROVED: Entity and ownership checks cleared
    PENDING --> DECLINED: Checks not cleared
    APPROVED --> [*]: Business can transact
    DECLINED --> [*]: New submission required
```

| 状态          | 含义                                            | 你的应用应当执行                  |
| ----------- | --------------------------------------------- | ------------------------- |
| `SUBMITTED` | 仅由 `registerBusiness` 返回。提交已被接受，并开启了 KYB 案件。  | 存储 `accountId`。展示“审核中”状态。 |
| `PENDING`   | 由 `getBusiness` 返回。案件审核中、等待筛查结果，或等待某位所有者完成验证。 | 持续跟踪。不要尝试为账户入金或发行卡片。      |
| `APPROVED`  | KYB 已通过。企业账户可用。                               | 配置消费账户、发行卡片、解锁你的企业 UI。    |
| `DECLINED`  | KYB 未通过。                                      | 呈现中性提示并引导用户联系支持。不要自动重试提交。 |

<Note>
  `SUBMITTED` 只会由 `registerBusiness` 返回。[getBusiness](/business-status) 报告三值状态，注册后立即读取会显示为 `PENDING`——两者描述的是同一时刻，只是用词不同。
</Note>

***

## 跟踪申请

有两种方式将申请跟踪至最终状态。选择与你的基础设施契合的方式；许多集成使用 webhook 获得低延迟，并偶尔读取以做对账。

<Tabs>
  <Tab title="Webhook">
    在 Fluz 仪表板订阅 **`KYB_STATUS_UPDATE`** 事件：注册你的回调 URL 并选择该事件。你的应用需要 `REGISTER_BUSINESS` 范围才能订阅。

    当企业的 KYB 状态发生变化时，Fluz 会向你的端点发起 `POST`。

    ```json theme={null}
    {
      "accountId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "previousStatus": "PENDING",
      "newStatus": "APPROVED",
      "externalReferenceId": "your-partner-user-id-123"
    }
    ```

    | 字段                    | 类型       | 说明                                                   |
    | --------------------- | -------- | ---------------------------------------------------- |
    | `accountId`           | `UUID`   | 状态发生改变的企业账户——与 `registerBusiness` 返回的 `accountId` 相同 |
    | `previousStatus`      | `String` | 变更前的状态：`PENDING`、`APPROVED` 或 `DECLINED`             |
    | `newStatus`           | `String` | 变更后的状态：`PENDING`、`APPROVED` 或 `DECLINED`             |
    | `externalReferenceId` | `String` | 当你在注册时提供了该值，则会返回你的自有引用；否则省略                          |

    需要处理两点：

    * **将投递视为至少一次。** 让你的处理器具备幂等性，以 `accountId` 加 `newStatus` 作为幂等键。
    * **你可能会收到 `previousStatus` 等于 `newStatus` 的事件。** 案件在内部状态间移动，但对外呈现的状态相同。将这些视为 no-op。

    <Note>
      负载仅携带企业状态——不包含所有者名单。当你需要查看每位所有者的进度时，调用 [getBusiness](/business-status)。
    </Note>
  </Tab>

  <Tab title="直接读取状态">
    使用企业账户令牌调用 [getBusiness](/business-status)。它返回相同的 `kybStatus`，并带有当前的所有者名单，因此这是唯一能判断某位所有者是否仍需验证的方式。

    ```graphql theme={null}
    query GetBusiness {
      getBusiness {
        accountId
        kybStatus
        owners {
          id
          name
          verificationType
          status
        }
      }
    }
    ```

    在用户返回你的企业上手界面时读取一次，并按低频后台计划读取——按小时级，而非每次页面加载。持续读取，直到 `kybStatus` 到达最终状态，且每位所有者都报告为 `READY`。
  </Tab>
</Tabs>

<Info>
  审核通常在一到两个工作日内完成，但若被要求补充资料，或某位所有者尚未完成身份验证，时间可能更长。若案件似乎停滞，请联系你的客户经理并提供 `accountId`，而非重新提交——第二次提交会被 `BS-0007` 拦截。
</Info>

***

## 使用 `externalReferenceId` 标识企业

Fluz 通过在注册时生成的 UUID `accountId` 来标识企业。`externalReferenceId` 则是一个可选标识符，由**你**提供，便于你用自有系统里该客户的 ID 与 Fluz 交互。

在 [registerBusiness](/business-registration) 时一次性传入：

```json theme={null}
{ "externalReferenceId": "your-partner-user-id-123" }
```

它会被存储到企业账户上，并带来三点益处：

* **无需存储 Fluz ID 即可铸造令牌。** 可按引用而非 `userId` 与 `accountId` 来铸造企业账户访问令牌。
* **Webhook 关联。** 该引用会出现在每个 [`KYB_STATUS_UPDATE`](#tracking-an-application) 事件中，因此无需查表即可将事件匹配到你的记录。

该字段为可选。若你省略，一切仍可正常工作——只是需要你自行存储 `accountId`，而无论如何你都应这么做。

### 规则

| 场景                | 结果                            |
| ----------------- | ----------------------------- |
| 省略                | 企业账户会在没有外部引用的情况下创建            |
| 提供，且未被占用          | 该引用会存储到新企业账户上                 |
| 提供，但已在申请人自己的个人账户上 | 该引用会从个人账户迁移到新企业账户上，之后它将解析到该企业 |
| 提供，但已在其他企业上       | 注册以 `AUTH-0008` 失败。现有企业保留该引用  |

<Warning>
  **每个企业使用一个唯一值。** 一个引用只能指向一个企业账户，因此在两个企业间复用同一值会导致第二次注册失败。请基于你的主键生成，而不要使用可复用的信息（如邮箱地址）。
</Warning>

<Note>
  此处涉及两个不同的引用，容易混淆。**你的访问令牌已携带的引用**用于定位申请人的现有授权；而 **`registerBusiness` 输入中的引用** 会被写入新的企业账户。二者用途不同。
</Note>

***

## 相关页面

<CardGroup cols={2}>
  <Card title="注册企业" icon="building" href="/business-registration">
    `registerBusiness` mutation：完整参数参考、所有权规则与错误码。
  </Card>

  <Card title="企业类别" icon="list" href="/business-categories">
    获取 mutation 所需的类别与子类别 ID。
  </Card>

  <Card title="提交企业文件" icon="file-arrow-up" href="/submit-business-documents">
    上传授权文件并响应 KYB 的补件请求。
  </Card>

  <Card title="企业 KYB 状态" icon="arrows-rotate" href="/business-status">
    读取 KYB 状态与每位所有者的验证进度。
  </Card>

  <Card title="所有者验证链接" icon="id-card" href="/owner-verification-link">
    为所有者生成可分享的身份验证链接。
  </Card>

  <Card title="注册客户" icon="user-plus" href="/user-registration">
    创建将作为申请人的 Fluz 用户。
  </Card>
</CardGroup>