注册与验证企业

概览

registerBusiness mutation 会在 Fluz 平台上创建一个企业账户。一次调用即可完成：

创建与现有 Fluz 用户（主要所有者）关联的企业账户，
存储法律实体记录——法定名称、组织结构、税号、注册州、法定地址、类别以及账户的预期用途，
存储你提供的每位所有者的实益所有权信息，以及
为合规审查开启一个 KYB（了解你的企业） 案件。

该 mutation 会立即返回一个 accountId，以及 PENDING 的 kybStatus。注册成功表示 Fluz 已接受并验证你的提交——这并不代表企业已获批。审批将在 KYB 审查完成后异步发生。

注册是校验，不是审批。 带有 kybStatus: PENDING 的 success 响应确认了负载通过了字段级校验，并已开启 KYB 案件。构建集成时请等待状态为已批准后再尝试为账户注资或发卡。

企业账户可解锁的功能

一旦 KYB 获批，企业账户即可用于平台的商业场景：

企业消费账户和余额
商业虚拟卡，包括批量发卡
授权用户与卡级别的消费控制
卡片、转账与报销的审批流
企业级交易报告与费用注释

何时使用此端点

当你的平台在 Fluz 轨道上为企业进行入驻，且你希望在自有 UI 中采集实体与所有权数据而不是将用户引导至 Fluz 托管流程时，使用 registerBusiness。如果你更希望由 Fluz 托管采集与文档上传体验，请与客户经理沟通基于小部件的入驻选项。

注册流程

端到端时序

步骤详解

确保主要所有者是已注册的 Fluz 用户

在 owners 数组中至少有一名所有者——主要所有者——必须已是 Fluz 用户，并且你为该所有者发送的 emailAddress 必须与其 Fluz 账户上的邮箱完全一致。如果该人尚无账户，请先使用 registerUser 创建。Fluz 建议主要所有者在提交企业信息之前或同时完成身份验证（KYC），因为所有者身份数据会作为 KYB 的一部分进行审查。

确认你的应用持有 REGISTER_BUSINESS scope

应用级授权和个人用户授权都必须处于激活状态。参见 Application Scopes。

解析企业类别与子类别

调用 getBusinessCategories，并让用户选择一个类别及该类别下的一个子类别。不要硬编码这些 UUID——它们可能变更，而且来自不同类别的子类别将因 BS-0006 被拒绝。

如适用，上传个体工商户证明文件

仅当 businessStructure 为 SOLE_PROPRIETORSHIP 时必需。先上传文件，然后将返回的 URL 传入 soleProprietorshipDocumentUrl。参见提交企业文件。

提交 registerBusiness mutation

在一次调用中发送完整的实体记录和所有所有者。按响应详情所述处理响应——错误会返回在负载内，而不是作为 GraphQL 错误。

等待 KYB 决策，然后进行开通配置

账户会以 PENDING 状态创建。请向用户展示该状态，而不是暗示他们已可使用。一旦状态变为已批准，创建消费账户并发卡。

KYB 状态生命周期

状态	含义	你的应用应执行的操作
`PENDING`	提交已被接受，正在审核中。	显示“审核中”状态。不要尝试为账户注资或发卡。
`APPROVED`	KYB 已通过。企业账户可用。	开通消费账户、发卡，并解锁你的企业端 UI。
`DECLINED`	KYB 未通过。	显示中性提示并引导用户联系支持。不要自动重试提交。

注册后如何检查状态

目前没有 KYB 的 webhook 事件，因此你的集成应在用户返回企业入驻界面时读取状态，并以低频后台计划（例如每小时一次——不要在每次页面加载时）进行轮询。你可以使用 getAccountsByUserId 确认企业账户已存在并将其与用户对应：

query GetAccountsByUserId($userId: UUID!) {
  getAccountsByUserId(userId: $userId) {
    accountId
    type
    accountName
  }
}

审核通常会在一至两个工作日内完成，但当被要求补充文件时可能更久。如果某个案件看似停滞，请联系你的客户经理并提供 accountId，而不是重新提交——第二次提交会被 BS-0007 阻止。

所需 scope

属性	值
Endpoint	GraphQL API
Authentication	OAuth Bearer Token
Required Scopes	`REGISTER_BUSINESS`

基本 mutation 结构

mutation RegisterBusiness($input: RegisterBusinessInput!) {
  registerBusiness(input: $input) {
    accountId
    kybStatus
    success
    error {
      message
      code
    }
  }
}

参数

参数	类型	必填	描述
`businessName`	`String`	是	法定企业名称，需与实体设立文件和报税文件上的名称完全一致
`dbaName`	`String`	否	“Doing Business As” 名称（经营名）
`businessStructure`	`BusinessStructure`	是	必须是以下之一：`LLC`、`CORPORATION`、`PARTNERSHIP`、`SOLE_PROPRIETORSHIP`、`COOP`
`businessLegalAddress`	`BusinessLegalAddress`	是	企业法定地址对象（见下文）
`stateOfIncorporation`	`String`	是	企业注册成立所在州
`taxId`	`String`	是	税号 / EIN。格式：`XX-XXXXXXX`（2 位数字、连字符、7 位数字）
`soleProprietorshipDocumentUrl`	`String`	条件	当 `businessStructure` 为 `SOLE_PROPRIETORSHIP` 时必填。先上传文件
`businessCategoryId`	`UUID`	是	企业类别 ID（来自 getBusinessCategories 查询）
`businessSubCategoryId`	`UUID`	是	企业子类别 ID（来自 getBusinessCategories 查询）
`natureOfBusiness`	`String`	否	对业务性质的简要描述。强烈推荐——可加速人工审核
`websiteUrl`	`String`	否	企业网站 URL。对于在线卖家强烈推荐
`businessAccountUsage`	`[BusinessAccountUsage]`	条件	用途类型数组。当未提供 `businessAccountUsageOther` 时必填
`businessAccountUsageOther`	`String`	条件	当 `businessAccountUsage` 为空或未提供时必填
`owners`	`[BusinessOwner]`	是	企业所有者列表。至少需要一名所有者。主要所有者必须是已注册的 Fluz 用户

地址格式使用下方的结构化字段格式化 businessLegalAddress 与每位所有者的 address，并确保是真实可投递地址，且城市 / 州 / 邮编一致。企业法定地址可以是国际地址（国家名称采用 ISO 3166；部分国家受限，如俄罗斯或伊朗）。所有者地址必须为美国地址。 格式错误或不匹配将返回 BS-0002（企业法定地址）或 BS-0003（所有者信息）。详见地址格式要求。

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 后四位
`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`	是	美国 ZIP 码格式为 5 位数字

BusinessStructure（枚举）

值	说明
`LLC`	单成员或多成员
`CORPORATION`	C-corp 或 S-corp
`PARTNERSHIP`	普通合伙或有限合伙
`SOLE_PROPRIETORSHIP`	需要 `soleProprietorshipDocumentUrl`
`COOP`	合作社

不在此列表中的结构将以 BS-0005 被拒绝。信托、非营利组织和其他实体类型将个案处理——在针对这些类型构建之前，请联系你的客户经理。

BusinessAccountUsage（枚举）

值	适用场景
`CORPORATE_GIFTING`	为员工、客户或激励项目购买礼品卡
`CORPORATE_SPENDING_ADMIN`	管理员工卡及受控支出
`REWARDS_MAXIMIZER`	优化企业支出奖励
`GIFT_CARD_RESELLING`	转售礼品卡
`PURCHASE_GOODS_FOR_BUSINESS_USE`	一般性商品与服务采购
`ONLINE_SELLER_RETAIL_PURCHASING`	为在线零售采购库存

发送所有适用的取值。如果没有合适的，省略 businessAccountUsage，并在 businessAccountUsageOther 中描述预期用途。选择你的应用未获批的用途类型将返回 BS-0004。

实益所有权要求

KYB 审查依赖于一次性准确获取所有权信息。请收集并提交：

每一位直接或间接持有该实体25% 或以上股份的个人。
一名控制人——对实体管理负有重要责任的个人（CEO、CFO、管理成员、普通合伙人或类似），即使其不持股。将其以 ownershipPercentage 为 0 且提供准确 title 提交。
至少一位已注册 Fluz 用户的所有者，且 emailAddress 必须匹配。

实用提示：

数组中 ownershipPercentage 的总和不得超过 100，但不需要等于 100。若企业由三名个人按 40/35/25 持股，外加一名不持股的 CEO，请提交四人，持股百分比分别为 40、35、25 和 0。
若由实体（而非个人）持股，请穿透至其背后的个人并提交这些个人。
title 为自由文本，但会由人工审核。请使用易识别的头衔（如“Chief Executive Officer”“Managing Member”），而非内部缩写。

校验速查

大多数 BS-000x 错误源于格式问题。提交前请检查：

字段	规则
`taxId`	`XX-XXXXXXX`——2 位数字、连字符、7 位数字。去除其他任何标点。
`owners[].dob`	`MM/DD/YYYY`
`owners[].phoneNumber`	仅数字，至少 10 位。不得包含 `+`、空格、括号或连字符。
`owners[].lastFourSsnDigits`	正好 4 位数字，字符串
`owners[].ownershipPercentage`	整数 0–100；所有者总和 ≤ 100
`owners[].address.state`	美国州全名，而非两字母缩写
`owners[].address.postalCode`	5 位数字
`businessLegalAddress.country`	ISO 3166 国家名称；受限国家将被拒绝
`businessSubCategoryId`	必须隶属于所提供的 `businessCategoryId`
`businessAccountUsage` / `...UsageOther`	两者必须恰有其一被填写
`soleProprietorshipDocumentUrl`	当 `businessStructure` 为 `SOLE_PROPRIETORSHIP` 时必填

日期格式与用户注册不同。 registerBusiness 期望所有者生日为 MM/DD/YYYY，而 registerUser 期望 YYYY-MM-DD。在两次调用中复用同一日期格式器是导致 BS-0003 的常见原因。

文件

个体工商户必须在注册前上传支持性文件，且任何组织结构都可能在 KYB 审查期间被要求提供更多文件。两条路径均在此页面说明：

提交企业文件

上传端点、可接受的个体工商户文件，以及在合规要求更多信息时应如何处理。

响应详情

字段	类型	描述
`accountId`	`UUID`	新创建企业的账户 ID
`kybStatus`	`String`	企业的 KYB 状态（初始为 `PENDING`）
`success`	`Boolean`	指示注册是否成功（出错时）
`error`	`RegisterBusinessError`	若注册失败则包含错误信息（出错时）

RegisterBusinessError

字段	类型	描述
`message`	`String`	简短的信息性错误消息
`code`	`String`	下表所列的预定义代码

失败会在响应负载内返回，而不是顶层 GraphQL 错误。请始终根据是否存在 error（或 success === false）进行分支，而不是依赖 HTTP 状态或 GraphQL errors 数组。

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

错误代码

代码	名称	描述	解决方法
`BS-0001`	InvalidTaxId	税号必须为 `XX-XXXXXXX` 格式（2 位数字、连字符、7 位数字）	重新格式化 EIN。去除空格与除单个连字符外的所有标点。
`BS-0002`	InvalidBusinessLegalAddress	企业法定地址不正确	参照地址格式要求进行校验。
`BS-0003`	InvalidOwnerInformation	一位或多位所有者信息不正确	检查 `dob` 格式、仅数字的 `phoneNumber`、4 位 SSN、州全名与 5 位 ZIP。
`BS-0004`	InvalidBusinessAccountUsage	所选企业账户用途不被允许	确认你的应用已获该用途类型的批准，或在 `businessAccountUsageOther` 中描述用途。
`BS-0005`	InvalidBusinessStructure	所选企业结构不被允许	使用五个受支持的枚举值之一，或就其他实体类型联系你的客户经理。
`BS-0006`	InvalidBusinessCategory	确保企业类别与子类别有效且正确关联（不同类别的子类别不可组合；例如，Art 不能与 Pharmacy 子类别一起选择）	重新获取 getBusinessCategories，并传递与同一类别对应的子类别。
`BS-0007`	RegistrationNotAllowed	等待上一次企业完成注册后再开始新的注册	用户已有未结申请。请等待批准或拒绝后再重新提交。
`AR-0001`	MissingArguments	缺少必填参数（详见错误消息）	查看 `message` 中的字段名。
`AR-0002`	InvalidArguments	提供了无效参数（详见错误消息）	查看 `message` 中的字段名。
`AU-0001`	UnsuccessfulRegistration	通用注册失败	重试一次。若仍失败，请携带请求负载与时间戳联系支持。

在测试环境进行测试

请针对上述示例所示的测试 GraphQL 端点进行注册。参见测试 vs. 生产环境。
对地址使用测试地址，可确定性地通过校验。
测试环境中的 EIN 仍需满足 XX-XXXXXXX 格式，但不需要对应真实实体。
由于一个用户不能持有两个未结申请（BS-0007），请使用不同测试用户测试重复注册路径。

最佳实践

先做客户端校验。 除 BS-0007 外的每个 BS-000x 代码都是你可以在网络请求前捕获的格式或选择问题。这样做能显著提升入驻完成率。
在运行时获取类别。 切勿硬编码类别 UUID。
不要在 KYB 被拒后自动重试。 重新提交不会改变结果，且会产生重复案件。
立即存储 accountId。 它是你获取该申请的唯一句柄，也是支持团队会索要的参考信息。
如实传达待审核状态。 告知用户企业正在审核以及大致耗时，而不是直接让他们进入尚无法交易的企业控制台。
首次就完整收集所有权信息。 缺失实益所有者是审查因补充文件而停滞的最常见原因。

备注

指定账户用途时，businessAccountUsage 与 businessAccountUsageOther 必须二选一填写。
若用户已有进行中的申请，则无法注册新企业。必须等待当前申请被批准或被拒后才能再次提交。

提交企业文件

上传个体工商户文件并响应 KYB 的文件补充请求。

企业类别

获取本次 mutation 所需的类别与子类别 ID。

注册客户

创建将作为主要所有者的 Fluz 用户。

地址格式要求

规范法定地址与所有者地址对象的规则。

构建平台

注册与验证企业

概览

企业账户可解锁的功能

何时使用此端点

注册流程

端到端时序

步骤详解

KYB 状态生命周期

注册后如何检查状态

所需 scope

基本 mutation 结构

参数

BusinessLegalAddress

BusinessOwner

OwnerAddress

BusinessStructure（枚举）

BusinessAccountUsage（枚举）

实益所有权要求

校验速查

文件

提交企业文件

响应详情

RegisterBusinessError

cURL 示例

示例响应

成功

错误

错误代码

在测试环境进行测试

最佳实践

备注

相关页面

提交企业文件

企业类别

注册客户

地址格式要求

​概览

​企业账户可解锁的功能

​何时使用此端点

​注册流程

​端到端时序

​步骤详解

​KYB 状态生命周期

​注册后如何检查状态

​所需 scope

​基本 mutation 结构

​参数

​BusinessLegalAddress

​BusinessOwner

​OwnerAddress

​BusinessStructure（枚举）

​BusinessAccountUsage（枚举）

​实益所有权要求

​校验速查

​文件

提交企业文件

​响应详情

​RegisterBusinessError

​cURL 示例

​示例响应

​成功

​错误

​错误代码

​在测试环境进行测试

​最佳实践

​备注

​相关页面

提交企业文件

企业类别

注册客户

地址格式要求

概览

企业账户可解锁的功能

何时使用此端点

注册流程

端到端时序

步骤详解

KYB 状态生命周期

注册后如何检查状态

所需 scope

基本 mutation 结构

参数

BusinessLegalAddress

BusinessOwner

OwnerAddress

BusinessStructure（枚举）

BusinessAccountUsage（枚举）

实益所有权要求

校验速查

文件

响应详情

RegisterBusinessError

cURL 示例

示例响应

成功

错误

错误代码

在测试环境进行测试

最佳实践

备注

相关页面