負責人身分驗證連結

Overview

requestOwnerDocumentVerificationLink 這個 mutation 會產生一個可分享的 URL，企業負責人可以用它完成文件式的身分驗證。此連結可獨立運作——負責人不需要 Fluz 認證憑證。將它用於 getBusiness 回傳 verificationType: DOCUMENTS 且 status: PENDING_CIP 的負責人。這些是以 isUsPerson: false 送出的實益擁有人或控制人，因此走文件驗證路徑，而不是 SSN 路徑。

走 SSN 路徑（verificationType: SSN）的負責人不需要使用此 mutation；尚未接受邀請的負責人也不需要——Fluz 會直接寄 Email 給這些負責人，並由他們自行驗證。

Required scopes

Property	Value
Endpoint	GraphQL API
Authentication	OAuth Bearer Token，帳戶類型為 `BUSINESS`
Required Scopes	`REGISTER_BUSINESS`

使用 registerBusiness 為該企業帳戶簽發的權杖。

Prerequisites

以下條件必須全部成立，否則呼叫會失敗：

具備 REGISTER_BUSINESS 的企業帳戶權杖

權杖需限定在擁有該名冊的企業之下。

案件必須處於已提交待篩檢狀態

僅能在提交後的一個特定狀態期間產生連結。仍在建立中、已在等待篩檢結果、或進入人工審查的案件都會被拒絕——即使 getBusiness 會將這些都回報為 kybStatus: PENDING。請見 Timing。

businessOwnerId 為負責人的 business-user ID

取自 getBusiness 的 owners[].id，且屬於該企業。不可使用 Fluz 使用者 ID；尚未接受邀請的負責人其 id: null。

負責人走文件驗證路徑

verificationType: DOCUMENTS 且 status: PENDING_CIP。

Basic mutation structure

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

Parameters

Parameter	Type	Required	Description
`businessOwnerId`	`UUID`	Yes	負責人的 business-user ID，來自 getBusiness 的 `owners[].id`。不是 Fluz 使用者 ID

Response details

Field	Type	Description
`success`	`Boolean`	產生連結時為 `true`
`id`	`UUID`	產生連結所對應的 `businessOwnerId`
`verificationLink`	`String`	可分享的 Plaid IDV URL。直接傳送給負責人使用

失敗會以「GraphQL 最上層錯誤」回傳，而不是 success: false。請檢查 errors 陣列，而非僅看資料載荷。這點與 registerBusiness 相反；後者會在其載荷內回報驗證失敗。

Timing

先決條件 2 的狀態要求是此呼叫最常失敗的原因，且無法透過 kybStatus 直接看見。

請「及早」呼叫。於 registerBusiness 回傳後不久，只要 getBusiness 顯示該負責人為 verificationType: DOCUMENTS 且 status: PENDING_CIP，就立刻產生連結。若收到 ARG-0001 且訊息為 business is not submitted for approval，代表案件已超過——或尚未到達——該時窗。請勿持續重試。請持續讀取 getBusiness，若某位負責人一直維持 PENDING_CIP 卻無法發送連結，請攜帶 accountId 聯絡您的客戶經理。

cURL Example

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

Example Response

Success

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

Error

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

Error Codes

Code	Name	Description	How to resolve
`AUTH-0002`	InvalidCredentials	使用了 Basic auth；權杖的帳戶類型不是 `BUSINESS`；權杖缺少 `userId` 或 `accountId`；或該 `accountId` 並不存在企業	使用為該企業 `accountId` 簽發的權杖
`AUTH-0031`	InvalidScope	權杖缺少 `REGISTER_BUSINESS` 權限範圍	新增該範圍並重新簽發權杖
`ARG-0002`	MissingArguments	未提供 `businessOwnerId`	傳入負責人的 business-user ID
`ARG-0001`	InvalidArguments	`businessOwnerId` 不屬於此企業的負責人，或案件未處於 submitted-for-approval 狀態	重新讀取 getBusiness 以取得最新 ID，並參閱 Timing
`G-0001`	InternalError	驗證供應商未回傳連結，或向其發送的請求失敗	重試一次。若持續發生，請攜帶 `accountId` 聯絡客服

Notes

產生的連結僅限單一用途。若負責人的連結過期或遺失，請再次呼叫此 mutation 以取得新的連結，而非重複使用舊連結。
產生連結不會改變負責人的 status。只有當負責人實際完成驗證後，狀態才會變為 READY——請持續讀取 getBusiness。
無批次版本。每位需要連結的負責人都需各自呼叫一次。

企業 KYB 狀態

辨識哪些負責人需要連結，並確認他們何時完成。

KYB 概覽

瞭解此步驟在端到端流程中的位置。

註冊企業

瞭解 isUsPerson 如何讓負責人走文件驗證路徑。

​Overview

​Required scopes

​Prerequisites

​Basic mutation structure

​Parameters

​Response details

​Timing

​cURL Example

​Example Response

​Success

​Error

​Error Codes

​Notes

​Related pages

企業 KYB 狀態

KYB 概覽

註冊企業

Overview

Required scopes

Prerequisites

Basic mutation structure

Parameters

Response details

Timing

cURL Example

Example Response

Success

Error

Error Codes

Notes

Related pages