企业 KYB 状态

概览

getBusiness 查询会返回某个企业账户当前的 KYB 状态，并附带一份所有权名册快照，展示每位所有者在身份验证中的进度。在注册企业之后，它能帮助你回答两个问题：

企业是否已经获批？ 查看 kybStatus。
是什么在阻碍审批？ 查看 owners —— 仍处于 PENDING_CIP 或 PENDING_INVITE 的所有者通常就是原因。

你也可以订阅 KYB_STATUS_UPDATE webhook 来接收状态变更，从而避免定时读取。该 webhook 仅承载企业状态，因此当你需要所有者名册时仍应调用此查询。参见跟踪申请。

必需的权限范围

Property	Value
Endpoint	GraphQL API
Authentication	OAuth Bearer Token，账户类型为 `BUSINESS`
Required Scopes	`REGISTER_BUSINESS`

该查询不接受参数——它始终解析与调用令牌的 accountId 绑定的企业。请使用为 registerBusiness 返回的企业账户铸造的令牌；你用于注册的消费者令牌将无法使用。

当 Fluz 在注册期间创建企业 OAuth 授权时，会强制将 REGISTER_BUSINESS 包含在该授权的 scopes 中，因此为新企业账户铸造的令牌始终可以调用此查询。

基本查询结构

query GetBusiness {
  getBusiness {
    accountId
    kybStatus
    owners {
      id
      name
      verificationType
      status
    }
  }
}

响应详情

字段	类型	说明
`accountId`	`UUID`	本响应所描述的企业账户
`kybStatus`	`ExternalKybStatus`	`PENDING`、`APPROVED` 或 `DECLINED`
`owners`	`[BusinessOwnerStatus]`	当前名册快照，包括注册后新增或更新的所有者

BusinessOwnerStatus

字段	类型	说明
`id`	`UUID`	所有者的身份 ID；对尚未接受邀请的受邀所有者为 `null`。参见可使用哪些 ID
`name`	`String`	来源于关联身份记录的显示名称
`verificationType`	`BusinessOwnerVerificationType`	该所有者预期需要进行的身份验证方式
`status`	`ExternalBusinessOwnerStatus`	该所有者当前的验证进度

ExternalKybStatus（枚举）

值	含义	你的应用应如何处理
`PENDING`	案件正在审核、等待筛查结果，或等待某位所有者完成验证	继续跟踪。不要为账户入金或发卡
`APPROVED`	KYB 已通过	开立消费账户并发卡
`DECLINED`	KYB 未通过	展示中性提示并引导用户联系支持。不要自动重试

registerBusiness 返回 SUBMITTED，它不属于该枚举的取值——同一时刻在这里会读作 PENDING。

PENDING 将多个内部状态折叠为一个值。这在一个地方很重要：requestOwnerDocumentVerificationLink 仅在案件处于某个特定内部状态时可用，而 kybStatus 无法告知你当前所处的具体状态。

BusinessOwnerVerificationType（枚举）

值	何时出现
`SSN`	所有者通过 SSN（CIP）进行验证——提交时 `isUsPerson: true`
`DOCUMENTS`	所有者通过上传身份证件进行验证——提交时 `isUsPerson: false`
`NOT_REQUIRED`	不期望额外验证：所提供的所有者持股低于 25% 且并非控制人

ExternalBusinessOwnerStatus（枚举）

值	含义	你的应用应如何处理
`PENDING_INVITE`	所有者有尚未接受的邀请	无需操作。Fluz 会给他们发送邮件；没有重发或代为接受的 API
`PENDING_CIP`	所有者仍需完成预期的身份验证	对于 `DOCUMENTS` 的所有者，向他们发送验证链接
`READY`	该所有者的验证要求已满足	无需操作
`FAILED`	为前向兼容而在架构中预留；当前不会返回	—

cURL 示例

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

示例响应

{
  "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 需要一个验证链接。Carol 已被邀请，Fluz 将会给她发送邮件。只有当两人都达到 READY 后，该企业才能获批。

错误代码

此查询将所有失败返回在顶层的 errors 数组中——不会有 success: false 的负载。

代码	名称	描述	解决方式
`AUTH-0002`	InvalidCredentials	使用了基本认证；令牌的账户类型不是 `BUSINESS`；令牌缺少 `userId` 或 `accountId`；或该 `accountId` 没有对应的企业	使用为 `registerBusiness` 返回的企业 `accountId` 铸造的令牌
`AUTH-0031`	InvalidScope	令牌缺少 `REGISTER_BUSINESS` scope	添加该 scope 并重新铸造令牌
`G-0001`	InternalError	内部错误	重试一次。若仍然失败，请携带 `accountId` 联系支持

最佳实践

优先使用 webhook，读取用于对账。 订阅 KYB_STATUS_UPDATE 以降低延迟；当用户返回你的引导页时或以低频后台计划进行读取——每小时一次，而非每次页面加载都读取。
在上线前等待双重信号。 kybStatus: APPROVED，且每位所有者均为 READY。
不要将链接请求视为进度。 只有当所有者实际完成验证时，其 status 才会变化，而不是当你生成了他们的链接时。

KYB 概览

状态生命周期以及如何将案件跟踪至决策。

所有者验证链接

为被报告为 DOCUMENTS 且处于 PENDING_CIP 的所有者生成链接。

注册企业

创建本查询所读取账户的 mutation。

构建平台

企业 KYB 状态

概览

必需的权限范围

基本查询结构

响应详情

BusinessOwnerStatus

ExternalKybStatus（枚举）

BusinessOwnerVerificationType（枚举）

ExternalBusinessOwnerStatus（枚举）

cURL 示例

示例响应

错误代码

最佳实践

相关页面

KYB 概览

所有者验证链接

注册企业

​概览

​必需的权限范围

​基本查询结构

​响应详情

​BusinessOwnerStatus

​ExternalKybStatus（枚举）

​BusinessOwnerVerificationType（枚举）

​ExternalBusinessOwnerStatus（枚举）

​cURL 示例

​示例响应

​错误代码

​最佳实践

​相关页面

KYB 概览

所有者验证链接

注册企业

概览

必需的权限范围

基本查询结构

响应详情

BusinessOwnerStatus

ExternalKybStatus（枚举）

BusinessOwnerVerificationType（枚举）

ExternalBusinessOwnerStatus（枚举）

cURL 示例

示例响应

错误代码

最佳实践

相关页面