> ## 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 狀態，以及各所有人的身分驗證進度。

## Overview

**getBusiness** 查詢會回傳某個企業帳戶目前的 KYB 狀態，並附上所有權名冊快照，以及各所有人在身分驗證上的進度。

在[註冊企業](/business-registration)之後，這能幫你回答兩個不同的問題：

* **企業核准了嗎？** 讀取 `kybStatus`。
* **卡在哪裡？** 讀取 `owners` — 仍在 `PENDING_CIP` 或 `PENDING_INVITE` 的所有人通常就是原因。

<Note>
  你也可以訂閱 `KYB_STATUS_UPDATE` webhook 以接收狀態變更，避免排程讀取。該 webhook 只攜帶企業狀態，因此當你需要所有人名冊時，請呼叫此查詢。請參見[追蹤申請](/kyb-overview#tracking-an-application)。
</Note>

## Required scopes

| Property        | Value                               |
| --------------- | ----------------------------------- |
| Endpoint        | GraphQL API                         |
| Authentication  | OAuth Bearer Token，帳戶類型為 `BUSINESS` |
| Required Scopes | `REGISTER_BUSINESS`                 |

此查詢不接受引數 — 它一律解析為與呼叫權杖之 `accountId` 綁定的企業。請使用 `registerBusiness` 為該企業帳戶鑄造的權杖；你用來註冊的消費者權杖將無法使用。

<Info>
  當 Fluz 在註冊期間建立企業的 OAuth 授權時，`REGISTER_BUSINESS` 會被強制包含在該授權的 scopes 中，因此為新企業帳戶鑄造的權杖一律可以呼叫此查詢。
</Info>

## Basic query structure

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

## Response details

| Field       | Type                    | Description                       |
| ----------- | ----------------------- | --------------------------------- |
| `accountId` | `UUID`                  | 此回應所描述的企業帳戶                       |
| `kybStatus` | `ExternalKybStatus`     | `PENDING`、`APPROVED` 或 `DECLINED` |
| `owners`    | `[BusinessOwnerStatus]` | 目前的名冊快照，包含註冊後新增或更新的所有人            |

### BusinessOwnerStatus

| Field              | Type                            | Description                                                              |
| ------------------ | ------------------------------- | ------------------------------------------------------------------------ |
| `id`               | `UUID`                          | 該所有人的身分 ID，對於尚未接受邀請的受邀所有人則為 `null`。請參見[可使用哪些 ID](#which-ids-can-be-used) |
| `name`             | `String`                        | 源自連結之身分紀錄的顯示名稱                                                           |
| `verificationType` | `BusinessOwnerVerificationType` | 此所有人「預期」要進行的身分驗證方式                                                       |
| `status`           | `ExternalBusinessOwnerStatus`   | 該所有人目前的驗證進度                                                              |

### ExternalKybStatus (enum)

| Value      | What it means             | What your app should do |
| ---------- | ------------------------- | ----------------------- |
| `PENDING`  | 個案審查中、等待篩檢結果，或等待某位所有人完成驗證 | 持續追蹤。不要為帳戶入金或發卡         |
| `APPROVED` | KYB 通過                    | 設立消費帳戶並發卡               |
| `DECLINED` | KYB 未通過                   | 呈現中性訊息並引導使用者聯繫客服。不要自動重試 |

`registerBusiness` 會回傳 `SUBMITTED`，但這不是此列舉的值 — 在這裡，同一時點會呈現為 `PENDING`。

<Warning>
  `PENDING` 將多個內部狀態折疊為一個值。這在一處會有影響：只有在個案處於特定的內部狀態時，[requestOwnerDocumentVerificationLink](/owner-verification-link) 才能運作，而 `kybStatus` 無法告訴你目前是哪一個狀態。
</Warning>

### BusinessOwnerVerificationType (enum)

| Value          | When you see it                           |
| -------------- | ----------------------------------------- |
| `SSN`          | 所有人以 SSN（CIP）驗證 — 其提交時 `isUsPerson: true` |
| `DOCUMENTS`    | 所有人上傳身分文件進行驗證 — 其提交時 `isUsPerson: false`  |
| `NOT_REQUIRED` | 不預期需要額外驗證：提供的所有人持股低於 25%，且不是控管人           |

### ExternalBusinessOwnerStatus (enum)

| Value            | What it means            | What your app should do                                   |
| ---------------- | ------------------------ | --------------------------------------------------------- |
| `PENDING_INVITE` | 所有人仍有未接受的邀請              | 無需動作。Fluz 會寄送電子郵件；沒有用於重寄或代為接受的 API                        |
| `PENDING_CIP`    | 所有人仍需完成預期的身分驗證           | 對於 `DOCUMENTS` 的所有人，[傳送驗證連結給他們](/owner-verification-link) |
| `READY`          | 該所有人的驗證要求已滿足             | 無需動作                                                      |
| `FAILED`         | 為前向相容性而存在於 schema，目前不會回傳 | —                                                         |

## cURL Example

```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 } } }"
  }'
```

## Example Response

```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` 之前，企業無法獲得核准。

## Error Codes

此查詢將所有失敗回傳在最上層的 `errors` 陣列中 — 不會有 `success: false` 的 payload。

| Code        | Name               | Description                                                                    | How to resolve                                 |
| ----------- | ------------------ | ------------------------------------------------------------------------------ | ---------------------------------------------- |
| `AUTH-0002` | InvalidCredentials | 使用了基本認證；權杖的帳戶類型不是 `BUSINESS`；權杖缺少 `userId` 或 `accountId`；或該 `accountId` 下不存在企業 | 使用 `registerBusiness` 回傳之企業 `accountId` 所鑄造的權杖 |
| `AUTH-0031` | InvalidScope       | 權杖缺少 `REGISTER_BUSINESS` scope                                                 | 新增該 scope 並重新鑄造權杖                              |
| `G-0001`    | InternalError      | 內部錯誤                                                                           | 重試一次。若持續發生，請攜帶 `accountId` 聯絡客服                |

## Best practices

* **偏好使用 webhook，讀取用於對帳。** 訂閱 `KYB_STATUS_UPDATE` 以獲得低延遲，並在使用者返回你的導覽流程頁面時，或以低頻率的背景排程進行讀取 — 每小時一次，而非每次載入頁面。
* **在上線前同時滿足兩個訊號。** `kybStatus: APPROVED`，且每位所有人皆為 `READY`。
* **不要將連結請求視為進度。** 所有人的 `status` 只有在實際完成驗證後才會改變，而非當你產生其連結時。

## Related pages

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