企業註冊 - Fluz

概觀

透過 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 結構

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 註冊的使用者。

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

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

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

回應範例

成功

{
  "data": {
    "registerBusiness": {
      "accountId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "kybStatus": "PENDING"
    }
  }
}

錯誤

{
  "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 至少需擇一提供。
若使用者已有進行中的申請，則不可註冊新企業。必須等待現有申請被核准或駁回後，才能再次提交。

​概觀

​必要範圍

​先決條件

​基本 mutation 結構

​參數

​BusinessLegalAddress

​BusinessOwner

​OwnerAddress

​BusinessStructure（列舉）

​BusinessAccountUsage（列舉）

​回應細節

​RegisterBusinessError

​cURL 範例

​回應範例

​成功

​錯誤

​錯誤代碼

​注意事項

概觀

必要範圍

先決條件

基本 mutation 結構

參數

BusinessLegalAddress

BusinessOwner

OwnerAddress

BusinessStructure（列舉）

BusinessAccountUsage（列舉）

回應細節

RegisterBusinessError

cURL 範例

回應範例

成功

錯誤

錯誤代碼

注意事項