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

# 企業註冊

## 概觀

透過 API 以程式化方式建立新的企業帳戶。此動作會建立企業帳戶、儲存企業資訊，並啟動 KYB（Know Your Business）流程。成功註冊後，帳戶狀態將為 `PENDING`，直到完成 KYB 驗證。

## 必要範圍

| Property        | Value               |
| --------------- | ------------------- |
| Endpoint        | GraphQL API         |
| Authentication  | OAuth Bearer Token  |
| Required Scopes | `REGISTER_BUSINESS` |

## 先決條件

在呼叫此 mutation 之前，請使用 **getBusinessCategories** 查詢以取得有效的 `businessCategoryId` 與 `businessSubCategoryId` 值。

## 基本 mutation 結構

```graphql theme={null}
mutation RegisterBusiness($input: RegisterBusinessInput!) {
  registerBusiness(input: $input) {
    accountId
    kybStatus
    success
    error {
      message
      code
    }
  }
}
```

## 參數

| Parameter                       | Type                     | Required    | Description                                                              |
| ------------------------------- | ------------------------ | ----------- | ------------------------------------------------------------------------ |
| `businessName`                  | `String`                 | Yes         | 企業的法定名稱                                                                  |
| `dbaName`                       | `String`                 | No          | 「以…之名營業」（DBA）名稱                                                          |
| `businessStructure`             | `BusinessStructure`      | Yes         | 必須為下列其中一項：`LLC`、`CORPORATION`、`PARTNERSHIP`、`SOLE_PROPRIETORSHIP`、`COOP` |
| `businessLegalAddress`          | `BusinessLegalAddress`   | Yes         | 企業法定地址物件（見下方）                                                            |
| `stateOfIncorporation`          | `String`                 | Yes         | 企業設立註冊所在州                                                                |
| `taxId`                         | `String`                 | Yes         | 稅務編號 / EIN。格式：`XX-XXXXXXX`（2 位數、連字號、7 位數）                                |
| `soleProprietorshipDocumentUrl` | `String`                 | Conditional | 若 `businessStructure` 為 `SOLE_PROPRIETORSHIP` 則必填。請先透過 REST 端點上傳         |
| `businessCategoryId`            | `UUID`                   | Yes         | 企業類別 ID（來自 **getBusinessCategories** 查詢）                                 |
| `businessSubCategoryId`         | `UUID`                   | Yes         | 企業子類別 ID（來自 **getBusinessCategories** 查詢）                                |
| `natureOfBusiness`              | `String`                 | No          | 簡述企業營業性質                                                                 |
| `websiteUrl`                    | `String`                 | No          | 企業網站 URL                                                                 |
| `businessAccountUsage`          | `[BusinessAccountUsage]` | Conditional | 使用型態陣列。若未提供 `businessAccountUsageOther` 則必填。                             |
| `businessAccountUsageOther`     | `String`                 | Conditional | 當 `businessAccountUsage` 為空或未提供時必填。                                      |
| `owners`                        | `[BusinessOwner]`        | Yes         | 企業所有者清單。至少需一位所有者。主要所有者必須為已在 Fluz 註冊的使用者。                                 |

<Note>
  **地址格式**

  使用下列結構化欄位格式化 `businessLegalAddress` 與每位所有者的 `address`，需提供可投遞之真實地址，且城市 / 州 / 郵遞區號需一致。**企業法定地址**可為國際地址（國家名稱採 ISO 3166；部分國家受限，如俄羅斯或伊朗）。**所有者地址必須為美國境內地址。** 若地址格式錯誤或不相符，將回傳 `BS-0002`（企業法定地址）或 `BS-0003`（所有者資訊）。詳見[地址格式要求](/concepts/address-formatting-requirements)。
</Note>

### BusinessLegalAddress

| Field                | Type     | Required | Description                             |
| -------------------- | -------- | -------- | --------------------------------------- |
| `streetAddressLine1` | `String` | Yes      | 街道地址第 1 行                               |
| `streetAddressLine2` | `String` | No       | 街道地址第 2 行                               |
| `city`               | `String` | Yes      | 城市                                      |
| `state`              | `String` | Yes      | 州／省                                     |
| `postalCode`         | `String` | Yes      | 郵遞區號                                    |
| `country`            | `String` | Yes      | 國家名稱（ISO 3166）。部分國家不可進行 KYB 註冊，例如俄羅斯或伊朗 |

### BusinessOwner

| Field                 | Type           | Required | Description                            |
| --------------------- | -------------- | -------- | -------------------------------------- |
| `firstName`           | `String`       | Yes      | 所有者名字                                  |
| `lastName`            | `String`       | Yes      | 所有者姓氏                                  |
| `emailAddress`        | `String`       | Yes      | 所有者的電子郵件。請確保使用該使用者在 Fluz 平台註冊的電子郵件地址。  |
| `title`               | `String`       | Yes      | 所有者於公司中的職稱                             |
| `ownershipPercentage` | `Int`          | Yes      | 持股比例（0-100）。所有所有者的總持股不可超過 100          |
| `lastFourSsnDigits`   | `String`       | Yes      | SSN 末 4 碼                              |
| `dob`                 | `String`       | Yes      | 出生日期，格式為 `MM/DD/YYYY`（例如 `02/28/1975`） |
| `phoneNumber`         | `String`       | Yes      | 電話號碼：至少 10 位數，僅限數字                     |
| `address`             | `OwnerAddress` | Yes      | 所有者地址（必須為美國境內，見 `OwnerAddress`）        |

### OwnerAddress

| Field                | Type     | Required | Description                                    |
| -------------------- | -------- | -------- | ---------------------------------------------- |
| `streetAddressLine1` | `String` | Yes      | 街道地址第 1 行                                      |
| `streetAddressLine2` | `String` | No       | 街道地址第 2 行                                      |
| `city`               | `String` | Yes      | 城市                                             |
| `state`              | `String` | Yes      | 必須為有效的美國州名（例如 `California`、`New York`、`Texas`） |
| `postalCode`         | `String` | Yes      | 必須為 5 位數的美國 ZIP 郵遞區號格式                         |

### BusinessStructure（列舉）

* `LLC`
* `CORPORATION`
* `PARTNERSHIP`
* `SOLE_PROPRIETORSHIP`
* `COOP`

### BusinessAccountUsage（列舉）

* `CORPORATE_GIFTING`
* `CORPORATE_SPENDING_ADMIN`
* `REWARDS_MAXIMIZER`
* `GIFT_CARD_RESELLING`
* `PURCHASE_GOODS_FOR_BUSINESS_USE`
* `ONLINE_SELLER_RETAIL_PURCHASING`

## 回應細節

| Field       | Type                    | Description               |
| ----------- | ----------------------- | ------------------------- |
| `accountId` | `UUID`                  | 新建立企業的帳戶 ID               |
| `kybStatus` | `String`                | 企業的 KYB 狀態（初始為 `PENDING`） |
| `success`   | `Boolean`               | 指示註冊是否成功（錯誤時）             |
| `error`     | `RegisterBusinessError` | 若註冊失敗則提供錯誤資訊（錯誤時）         |

### RegisterBusinessError

| Field     | Type     | Description |
| --------- | -------- | ----------- |
| `message` | `String` | 簡要的錯誤訊息     |
| `code`    | `String` | 下表所列的預先定義代碼 |

## cURL 範例

```bash theme={null}
curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
    "query": "mutation RegisterBusiness($input: RegisterBusinessInput!) { registerBusiness(input: $input) { accountId kybStatus success error { message code } } }",
    "variables": {
      "input": {
        "businessName": "Acme Corporation",
        "dbaName": "Acme Co",
        "businessStructure": "LLC",
        "businessLegalAddress": {
          "streetAddressLine1": "123 Main Street",
          "streetAddressLine2": "Suite 100",
          "city": "San Francisco",
          "state": "California",
          "postalCode": "94102",
          "country": "United States"
        },
        "stateOfIncorporation": "California",
        "taxId": "12-3456789",
        "businessCategoryId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "businessSubCategoryId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "natureOfBusiness": "E-commerce retail",
        "websiteUrl": "https://acme.example.com",
        "businessAccountUsage": ["CORPORATE_SPENDING_ADMIN", "PURCHASE_GOODS_FOR_BUSINESS_USE"],
        "owners": [
          {
            "firstName": "John",
            "lastName": "Doe",
            "emailAddress": "john@example.com",
            "title": "CEO",
            "ownershipPercentage": 60,
            "lastFourSsnDigits": "1234",
            "dob": "02/28/1975",
            "phoneNumber": "4155551234",
            "address": {
              "streetAddressLine1": "456 Oak Avenue",
              "city": "San Francisco",
              "state": "California",
              "postalCode": "94103"
            }
          },
          {
            "firstName": "Jane",
            "lastName": "Smith",
            "emailAddress": "jane@example.com",
            "title": "CFO",
            "ownershipPercentage": 40,
            "lastFourSsnDigits": "5678",
            "dob": "07/15/1980",
            "phoneNumber": "4155555678",
            "address": {
              "streetAddressLine1": "789 Pine Street",
              "city": "San Francisco",
              "state": "California",
              "postalCode": "94104"
            }
          }
        ]
      }
    }
  }'
```

## 回應範例

### 成功

```json theme={null}
{
  "data": {
    "registerBusiness": {
      "accountId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "kybStatus": "PENDING"
    }
  }
}
```

### 錯誤

```json theme={null}
{
  "data": {
    "registerBusiness": {
      "success": false,
      "error": {
        "message": "The entered tax id taxId must be in format XX-XXXXXXX (2 digits, hyphen, 7 digits)",
        "code": "BS-0001"
      }
    }
  }
}
```

## 錯誤代碼

| Code      | Name                        | Description                                                  |
| --------- | --------------------------- | ------------------------------------------------------------ |
| `BS-0001` | InvalidTaxId                | 稅務編號必須為 `XX-XXXXXXX` 格式（2 位數、連字號、7 位數）                       |
| `BS-0002` | InvalidBusinessLegalAddress | 企業法定地址不正確                                                    |
| `BS-0003` | InvalidOwnerInformation     | 一位或多位所有者資訊不正確                                                |
| `BS-0004` | InvalidBusinessAccountUsage | 選擇的企業帳戶使用方式不被允許                                              |
| `BS-0005` | InvalidBusinessStructure    | 選擇的企業結構不被允許                                                  |
| `BS-0006` | InvalidBusinessCategory     | 請確保企業類別與企業子類別有效且正確關聯（不可混用不同類別之子類別；例如，Art 不可與 Pharmacy 子類別搭配） |
| `BS-0007` | RegistrationNotAllowed      | 請等待上一筆企業完成註冊後再開始新的申請                                         |
| `AR-0001` | MissingArguments            | 缺少必要參數（詳情請見錯誤訊息）                                             |
| `AR-0002` | InvalidArguments            | 提供的參數無效（詳情請見錯誤訊息）                                            |
| `AU-0001` | UnsuccessfulRegistration    | 一般註冊失敗                                                       |

***

## 注意事項

* 若 `businessStructure` 為 `SOLE_PROPRIETORSHIP`，請透過 REST 端點 `POST https://transactional-graph.staging.fluzapp.com/api/v1/file-upload/sole-proprietorship-document`（使用 `form-data` 內容型態）上傳文件。接著，將產生的 URL 填入 `soleProprietorshipDocumentUrl`
* 指定帳戶使用方式時，`businessAccountUsage` 與 `businessAccountUsageOther` 至少需擇一提供。
* 若使用者已有進行中的申請，則不可註冊新企業。必須等待現有申請被核准或駁回後，才能再次提交。

<br />