> ## 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（了解你的企业）流程。注册成功后，账户将在 `PENDING` 状态，直至完成 KYB 验证。

## 必需的作用域

| 属性     | 值                   |
| ------ | ------------------- |
| 端点     | GraphQL API         |
| 认证     | OAuth Bearer Token  |
| 必需的作用域 | `REGISTER_BUSINESS` |

## 前置条件

在调用此 mutation 之前，使用 **getBusinessCategories** 查询以获取有效的 `businessCategoryId` 和 `businessSubCategoryId` 值。

## 基本 mutation 结构

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

## 参数

| 参数                              | 类型                       | 必填 | 说明                                                                     |
| ------------------------------- | ------------------------ | -- | ---------------------------------------------------------------------- |
| `businessName`                  | `String`                 | 是  | 企业法定名称                                                                 |
| `dbaName`                       | `String`                 | 否  | “以…名义经营”（DBA）名称                                                        |
| `businessStructure`             | `BusinessStructure`      | 是  | 必须为以下之一：`LLC`、`CORPORATION`、`PARTNERSHIP`、`SOLE_PROPRIETORSHIP`、`COOP` |
| `businessLegalAddress`          | `BusinessLegalAddress`   | 是  | 企业法定地址对象（见下文）                                                          |
| `stateOfIncorporation`          | `String`                 | 是  | 企业注册成立所在州                                                              |
| `taxId`                         | `String`                 | 是  | 税号 / EIN。格式：`XX-XXXXXXX`（2 位数字、连字符、7 位数字）                              |
| `soleProprietorshipDocumentUrl` | `String`                 | 条件 | 当 `businessStructure` 为 `SOLE_PROPRIETORSHIP` 时必填。请先通过 REST 端点上传       |
| `businessCategoryId`            | `UUID`                   | 是  | 业务类别 ID（来源于 **getBusinessCategories** 查询）                              |
| `businessSubCategoryId`         | `UUID`                   | 是  | 业务子类别 ID（来源于 **getBusinessCategories** 查询）                             |
| `natureOfBusiness`              | `String`                 | 否  | 对业务性质的简要描述                                                             |
| `websiteUrl`                    | `String`                 | 否  | 企业网站 URL                                                               |
| `businessAccountUsage`          | `[BusinessAccountUsage]` | 条件 | 用途类型数组。当未提供 `businessAccountUsageOther` 时必填。                           |
| `businessAccountUsageOther`     | `String`                 | 条件 | 当 `businessAccountUsage` 为空或未提供时必填。                                    |
| `owners`                        | `[BusinessOwner]`        | 是  | 企业所有者列表。至少需要一位所有者。主所有者必须是已在 Fluz 注册的用户。                                |

<Note>
  **地址格式**

  使用下方的结构化字段来填写 `businessLegalAddress` 及每位所有者的 `address`，并确保为真实、可投递的地址，以及城市 / 州 / 邮编三者一致。**企业法定地址**可以为国际地址（国家名使用 ISO 3166；部分国家受限，例如俄罗斯或伊朗）。**所有者地址必须为美国地址。** 地址不规范或信息不匹配会返回 `BS-0002`（企业法定地址）或 `BS-0003`（所有者信息）。详情参见 [地址格式要求](/concepts/address-formatting-requirements)。
</Note>

### BusinessLegalAddress

| 字段                   | 类型       | 必填 | 说明                                     |
| -------------------- | -------- | -- | -------------------------------------- |
| `streetAddressLine1` | `String` | 是  | 街道地址第 1 行                              |
| `streetAddressLine2` | `String` | 否  | 街道地址第 2 行                              |
| `city`               | `String` | 是  | 城市                                     |
| `state`              | `String` | 是  | 州/省                                    |
| `postalCode`         | `String` | 是  | 邮政编码                                   |
| `country`            | `String` | 是  | 国家名称（ISO 3166）。某些国家受 KYB 注册限制，例如俄罗斯或伊朗 |

### BusinessOwner

| 字段                    | 类型             | 必填 | 说明                                     |
| --------------------- | -------------- | -- | -------------------------------------- |
| `firstName`           | `String`       | 是  | 所有者名                                   |
| `lastName`            | `String`       | 是  | 所有者姓                                   |
| `emailAddress`        | `String`       | 是  | 所有者邮箱。请确保使用该用户在 Fluz 平台注册时的邮箱地址。       |
| `title`               | `String`       | 是  | 所有者在公司内的职务                             |
| `ownershipPercentage` | `Int`          | 是  | 持股比例（0-100）。所有所有者的总持股比例不得超过 100        |
| `lastFourSsnDigits`   | `String`       | 是  | SSN 后 4 位                              |
| `dob`                 | `String`       | 是  | 出生日期，格式为 `MM/DD/YYYY`（例如，`02/28/1975`） |
| `phoneNumber`         | `String`       | 是  | 电话号码：至少 10 位，只能为数字                     |
| `address`             | `OwnerAddress` | 是  | 所有者地址（必须为美国地址，见 `OwnerAddress`）        |

### OwnerAddress

| 字段                   | 类型       | 必填 | 说明                                             |
| -------------------- | -------- | -- | ---------------------------------------------- |
| `streetAddressLine1` | `String` | 是  | 街道地址第 1 行                                      |
| `streetAddressLine2` | `String` | 否  | 街道地址第 2 行                                      |
| `city`               | `String` | 是  | 城市                                             |
| `state`              | `String` | 是  | 必须为有效的美国州名（例如，`California`、`New York`、`Texas`） |
| `postalCode`         | `String` | 是  | 必须为 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`

## 响应详情

| 字段          | 类型                      | 说明                        |
| ----------- | ----------------------- | ------------------------- |
| `accountId` | `UUID`                  | 新创建企业的账户 ID               |
| `kybStatus` | `String`                | 企业的 KYB 状态（初始为 `PENDING`） |
| `success`   | `Boolean`               | 指示注册是否成功（发生错误时）           |
| `error`     | `RegisterBusinessError` | 注册失败时的错误信息（发生错误时）         |

### RegisterBusinessError

| 字段        | 类型       | 说明        |
| --------- | -------- | --------- |
| `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"
      }
    }
  }
}
```

## 错误代码

| 代码        | 名称                          | 说明                                                                |
| --------- | --------------------------- | ----------------------------------------------------------------- |
| `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` 内容类型）上传文档。随后在 `soleProprietorshipDocumentUrl` 中提供生成的 URL
* 在指定账户用途时，必须提供 `businessAccountUsage` 或 `businessAccountUsageOther` 其中之一。
* 如果用户已有正在进行中的申请，则无法注册新企业。必须等待当前申请获批或被拒后，方可提交新的申请。

<br />