所有者验证链接

概览

requestOwnerDocumentVerificationLink 变更会生成一个可分享的 URL，企业所有者可用其通过证件完成身份验证。该链接可独立使用——所有者不需要 Fluz 凭证。将其用于那些 getBusiness 返回 verificationType: DOCUMENTS 且 status: PENDING_CIP 的所有者。这些是以 isUsPerson: false 提交的实益所有人或控制人，因此走证件通道而不是 SSN 通道。

走 SSN 通道（verificationType: SSN）的所有者不需要使用此变更；尚未接受邀请的所有者也不需要——Fluz 会直接给这些所有者发送邮件，他们自行完成验证。

必需的范围

属性	值
端点	GraphQL API
认证	OAuth Bearer Token，账户类型为 `BUSINESS`
所需范围	`REGISTER_BUSINESS`

使用为 registerBusiness 返回的该企业账户铸造的令牌。

先决条件

以下条件全部满足，否则调用失败：

具有 REGISTER_BUSINESS 的企业账户令牌

作用域限定到拥有该花名册的企业。

案件处于已提交等待筛查状态

该链接只能在提交后的特定状态下生成。仍在创建中、已在等待筛查结果或处于人工审核的案件都会被拒绝——尽管 getBusiness 会将这些都报告为 kybStatus: PENDING。参见时机。

businessOwnerId 是所有者的业务用户 ID

取自 getBusiness 的 owners[].id，且属于此企业。不接受 Fluz 用户 ID，尚未接受邀请的所有者其 id: null。

该所有者走证件通道

verificationType: DOCUMENTS 且 status: PENDING_CIP。

基本变更结构

mutation RequestOwnerDocumentVerificationLink($businessOwnerId: UUID!) {
  requestOwnerDocumentVerificationLink(businessOwnerId: $businessOwnerId) {
    success
    id
    verificationLink
  }
}

参数

参数	类型	必填	描述
`businessOwnerId`	`UUID`	是	所有者的业务用户 ID，来自 getBusiness 的 `owners[].id`。不是 Fluz 用户 ID

响应详情

字段	类型	描述
`success`	`Boolean`	当生成了链接时为 `true`
`id`	`UUID`	生成链接所针对的 `businessOwnerId`
`verificationLink`	`String`	可分享的 Plaid IDV URL。直接发送给所有者

失败作为GraphQL 顶层错误返回，而不是 success: false。请检查 errors 数组，而不只是数据负载。与 registerBusiness 相反，后者会在其负载内报告校验失败。

时机

先决条件 2 中的状态要求是此调用失败的最常见原因，并且它不会通过 kybStatus 直观显示。

要尽早调用。 在 registerBusiness 返回后不久，只要 getBusiness 显示该所有者为 verificationType: DOCUMENTS 且 status: PENDING_CIP，即可调用。如果你收到 ARG-0001，并提示 business is not submitted for approval，说明案件已越过——或尚未到达——该时间窗口。不要循环重试。持续读取 getBusiness，如果某位所有者一直停留在 PENDING_CIP 且无法向其发送链接，请携带 accountId 联系你的客户经理。

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": "mutation RequestOwnerDocumentVerificationLink($businessOwnerId: UUID!) { requestOwnerDocumentVerificationLink(businessOwnerId: $businessOwnerId) { success id verificationLink } }",
    "variables": { "businessOwnerId": "d4e5f6a7-b8c9-0123-def0-234567890123" }
  }'

示例响应

成功

{
  "data": {
    "requestOwnerDocumentVerificationLink": {
      "success": true,
      "id": "d4e5f6a7-b8c9-0123-def0-234567890123",
      "verificationLink": "https://verify.docs../..."
    }
  }
}

错误

{
  "errors": [
    {
      "message": "Invalid arguments received - business owner not found.",
      "extensions": {
        "code": "ARG-0001",
        "statusCode": 422
      }
    }
  ],
  "data": null
}

错误代码

代码	名称	描述	解决方法
`AUTH-0002`	InvalidCredentials	使用了基本认证；令牌的账户类型不是 `BUSINESS`；令牌缺少 `userId` 或 `accountId`；或该 `accountId` 不存在企业	使用为该企业 `accountId` 铸造的令牌
`AUTH-0031`	InvalidScope	令牌缺少 `REGISTER_BUSINESS` 范围	添加该范围并重新铸造令牌
`ARG-0002`	MissingArguments	未提供 `businessOwnerId`	传入所有者的业务用户 ID
`ARG-0001`	InvalidArguments	`businessOwnerId` 不匹配此企业上的某位所有者，或案件不处于已提交等待批准状态	重新读取 getBusiness 以获取最新 ID，并参见时机
`G-0001`	InternalError	验证服务商未返回链接，或对其的请求失败	重试一次。如仍持续，请携带 `accountId` 联系支持

备注

生成的链接仅用于单一目的。若所有者的链接过期或丢失，请再次调用该变更以获取新的链接，而不是重复使用旧的。
生成链接不会改变所有者的 status。只有当所有者实际完成验证后才会变为 READY——请持续读取 getBusiness。
没有批量版本。每位需要链接的所有者都需单独调用。

企业 KYB 状态

识别哪些所有者需要链接，并确认他们何时完成。

KYB 概览

了解此步骤在端到端流程中的位置。

注册企业

isUsPerson 如何使所有者走证件通道。

构建平台

所有者验证链接

概览

必需的范围

先决条件

基本变更结构

参数

响应详情

时机

cURL 示例

示例响应

成功

错误

错误代码

备注

相关页面

企业 KYB 状态

KYB 概览

注册企业

​概览

​必需的范围

​先决条件

​基本变更结构

​参数

​响应详情

​时机

​cURL 示例

​示例响应

​成功

​错误

​错误代码

​备注

​相关页面

企业 KYB 状态

KYB 概览

注册企业

概览

必需的范围

先决条件

基本变更结构

参数

响应详情

时机

cURL 示例

示例响应

成功

错误

错误代码

备注

相关页面