> ## 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 状态

> 使用 getBusiness 查询读取企业账户的 KYB 状态，以及每位所有者的身份验证进度。

## 概览

**getBusiness** 查询会返回某个企业账户当前的 KYB 状态，并附带一份所有权名册快照，展示每位所有者在身份验证中的进度。

在[注册企业](/business-registration)之后，它能帮助你回答两个问题：

* **企业是否已经获批？** 查看 `kybStatus`。
* **是什么在阻碍审批？** 查看 `owners` —— 仍处于 `PENDING_CIP` 或 `PENDING_INVITE` 的所有者通常就是原因。

<Note>
  你也可以订阅 `KYB_STATUS_UPDATE` webhook 来接收状态变更，从而避免定时读取。该 webhook 仅承载企业状态，因此当你需要所有者名册时仍应调用此查询。参见[跟踪申请](/kyb-overview#tracking-an-application)。
</Note>

## 必需的权限范围

| Property        | Value                               |
| --------------- | ----------------------------------- |
| Endpoint        | GraphQL API                         |
| Authentication  | OAuth Bearer Token，账户类型为 `BUSINESS` |
| Required Scopes | `REGISTER_BUSINESS`                 |

该查询不接受参数——它始终解析与调用令牌的 `accountId` 绑定的企业。请使用为 `registerBusiness` 返回的企业账户铸造的令牌；你用于注册的消费者令牌将无法使用。

<Info>
  当 Fluz 在注册期间创建企业 OAuth 授权时，会强制将 `REGISTER_BUSINESS` 包含在该授权的 scopes 中，因此为新企业账户铸造的令牌始终可以调用此查询。
</Info>

## 基本查询结构

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

## 响应详情

| 字段          | 类型                      | 说明                                |
| ----------- | ----------------------- | --------------------------------- |
| `accountId` | `UUID`                  | 本响应所描述的企业账户                       |
| `kybStatus` | `ExternalKybStatus`     | `PENDING`、`APPROVED` 或 `DECLINED` |
| `owners`    | `[BusinessOwnerStatus]` | 当前名册快照，包括注册后新增或更新的所有者             |

### BusinessOwnerStatus

| 字段                 | 类型                              | 说明                                                                   |
| ------------------ | ------------------------------- | -------------------------------------------------------------------- |
| `id`               | `UUID`                          | 所有者的身份 ID；对尚未接受邀请的受邀所有者为 `null`。参见[可使用哪些 ID](#which-ids-can-be-used) |
| `name`             | `String`                        | 来源于关联身份记录的显示名称                                                       |
| `verificationType` | `BusinessOwnerVerificationType` | 该所有者预期需要进行的身份验证方式                                                    |
| `status`           | `ExternalBusinessOwnerStatus`   | 该所有者当前的验证进度                                                          |

### ExternalKybStatus（枚举）

| 值          | 含义                         | 你的应用应如何处理              |
| ---------- | -------------------------- | ---------------------- |
| `PENDING`  | 案件正在审核、等待筛查结果，或等待某位所有者完成验证 | 继续跟踪。不要为账户入金或发卡        |
| `APPROVED` | KYB 已通过                    | 开立消费账户并发卡              |
| `DECLINED` | KYB 未通过                    | 展示中性提示并引导用户联系支持。不要自动重试 |

`registerBusiness` 返回 `SUBMITTED`，它不属于该枚举的取值——同一时刻在这里会读作 `PENDING`。

<Warning>
  `PENDING` 将多个内部状态折叠为一个值。这在一个地方很重要：[requestOwnerDocumentVerificationLink](/owner-verification-link) 仅在案件处于某个特定内部状态时可用，而 `kybStatus` 无法告知你当前所处的具体状态。
</Warning>

### BusinessOwnerVerificationType（枚举）

| 值              | 何时出现                                       |
| -------------- | ------------------------------------------ |
| `SSN`          | 所有者通过 SSN（CIP）进行验证——提交时 `isUsPerson: true` |
| `DOCUMENTS`    | 所有者通过上传身份证件进行验证——提交时 `isUsPerson: false`   |
| `NOT_REQUIRED` | 不期望额外验证：所提供的所有者持股低于 25% 且并非控制人             |

### ExternalBusinessOwnerStatus（枚举）

| 值                | 含义                  | 你的应用应如何处理                                                 |
| ---------------- | ------------------- | --------------------------------------------------------- |
| `PENDING_INVITE` | 所有者有尚未接受的邀请         | 无需操作。Fluz 会给他们发送邮件；没有重发或代为接受的 API                         |
| `PENDING_CIP`    | 所有者仍需完成预期的身份验证      | 对于 `DOCUMENTS` 的所有者，[向他们发送验证链接](/owner-verification-link) |
| `READY`          | 该所有者的验证要求已满足        | 无需操作                                                      |
| `FAILED`         | 为前向兼容而在架构中预留；当前不会返回 | —                                                         |

## cURL 示例

```bash theme={null}
curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <BUSINESS_ACCESS_TOKEN>" \
  -d '{
    "query": "query GetBusiness { getBusiness { accountId kybStatus owners { id name verificationType status } } }"
  }'
```

## 示例响应

```json theme={null}
{
  "data": {
    "getBusiness": {
      "accountId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "kybStatus": "PENDING",
      "owners": [
        {
          "id": "3f2a1b0c-9d8e-4f7a-8b6c-5d4e3f2a1b0c",
          "name": "John Doe",
          "verificationType": "SSN",
          "status": "READY"
        },
        {
          "id": "d4e5f6a7-b8c9-0123-def0-234567890123",
          "name": "Jane Smith",
          "verificationType": "DOCUMENTS",
          "status": "PENDING_CIP"
        },
        {
          "id": null,
          "name": "Carol Investor",
          "verificationType": "SSN",
          "status": "PENDING_INVITE"
        }
      ]
    }
  }
}
```

Jane 需要一个[验证链接](/owner-verification-link)。Carol 已被邀请，Fluz 将会给她发送邮件。只有当两人都达到 `READY` 后，该企业才能获批。

## 错误代码

此查询将所有失败返回在顶层的 `errors` 数组中——不会有 `success: false` 的负载。

| 代码          | 名称                 | 描述                                                                              | 解决方式                                           |
| ----------- | ------------------ | ------------------------------------------------------------------------------- | ---------------------------------------------- |
| `AUTH-0002` | InvalidCredentials | 使用了基本认证；令牌的账户类型不是 `BUSINESS`；令牌缺少 `userId` 或 `accountId`；或该 `accountId` 没有对应的企业 | 使用为 `registerBusiness` 返回的企业 `accountId` 铸造的令牌 |
| `AUTH-0031` | InvalidScope       | 令牌缺少 `REGISTER_BUSINESS` scope                                                  | 添加该 scope 并重新铸造令牌                              |
| `G-0001`    | InternalError      | 内部错误                                                                            | 重试一次。若仍然失败，请携带 `accountId` 联系支持                |

## 最佳实践

* **优先使用 webhook，读取用于对账。** 订阅 `KYB_STATUS_UPDATE` 以降低延迟；当用户返回你的引导页时或以低频后台计划进行读取——每小时一次，而非每次页面加载都读取。
* **在上线前等待双重信号。** `kybStatus: APPROVED`，且每位所有者均为 `READY`。
* **不要将链接请求视为进度。** 只有当所有者实际完成验证时，其 `status` 才会变化，而不是当你生成了他们的链接时。

## 相关页面

<CardGroup cols={2}>
  <Card title="KYB 概览" href="/kyb-overview">
    状态生命周期以及如何将案件跟踪至决策。
  </Card>

  <Card title="所有者验证链接" href="/owner-verification-link">
    为被报告为 `DOCUMENTS` 且处于 `PENDING_CIP` 的所有者生成链接。
  </Card>

  <Card title="注册企业" href="/business-registration">
    创建本查询所读取账户的 mutation。
  </Card>
</CardGroup>