> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 以銀行連結回覆資訊請求

> 使用 completeRfiPlaidLink，透過 Plaid 連結銀行帳戶來回覆銀行對帳單或地址證明的 RFI 問題。

## 概觀

有兩種問題類型可以透過連結銀行帳戶來回覆，而不必上傳文件：

| 問題類型 | 銀行連結視為已回覆的條件 |
| - | - |
| `BANK_LINK_OR_STATEMENT` | 銀行連結成功 |
| `ADDRESS_VERIFICATION_OR_DOCUMENT` | 銀行已連結**且**確認客戶的地址 |

**completeRfiPlaidLink** mutation 會交換 Plaid Link 提供的公開權杖，將銀行連結至客戶的 Fluz 帳戶，並將該連結儲存為該問題的回覆。

此操作不會提交 RFI。請在之後呼叫 [submitRfi](https://docs.fluz.app/submit-rfi) 以送出審核。

## 所需權限範圍

| 屬性 | 值 |
| - | - |
| 端點 | GraphQL API |
| 驗證 | OAuth Bearer Token。不接受 Basic 驗證 |
| 所需權限範圍 | `MANAGE_RFI` 與 `MANAGE_PAYMENT` |

由於該銀行也會作為資金來源新增至客戶的帳戶，因此需要 `MANAGE_PAYMENT`。`createPlaidLinkToken` 同樣需要此權限範圍。

## 流程

**1. 建立 Link 權杖**

使用客戶的權杖呼叫 `createPlaidLinkToken`。請參閱[透過 Plaid 連結銀行帳戶](https://docs.fluz.app/features/link-via-plaid.md)。

**2. 開啟 Plaid Link**

使用該權杖開啟 Plaid Link。客戶完成後，Plaid 會回傳 `public_token`。

**3. 呼叫 completeRfiPlaidLink**

傳入 `rfiId`、`questionId` 與 `public_token`。銀行會被連結，回覆也會被儲存。

**4. 提交 RFI**

呼叫 [submitRfi](https://docs.fluz.app/submit-rfi)。請不要把已連結的問題放進 `answers`，因為已儲存的連結已經回覆了該問題。

## 基本 mutation 結構

```graphql theme={null}
mutation CompleteRfiPlaidLink($input: CompleteRfiPlaidLinkInput!) {
  completeRfiPlaidLink(input: $input) {
    rfiId
    status
    requiresAddress
    bankAccountId
    bankInstitutionAuthId
    newlyLinkedBankInstitutionAuthId
    bankInstitutionName
    platformItemId
    bankAccounts {
      bankInstitutionAuthId
      bankAccountId
      bankName
      lastFour
      type
      subtype
    }
  }
}
```

## 參數

### CompleteRfiPlaidLinkInput

| 欄位 | 類型 | 必填 | 說明 |
| - | - | - | - |
| `rfiId` | `UUID!` | 是 | 要回覆的 RFI |
| `questionId` | `String!` | 是 | `BANK_LINK_OR_STATEMENT` 或 `ADDRESS_VERIFICATION_OR_DOCUMENT` 問題。1–200 個字元 |
| `publicToken` | `String!` | 是 | Plaid Link 回傳的 `public_token`。以 `public-` 開頭，最多 256 個字元 |

## cURL 範例

```bash theme={null}
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 CompleteRfiPlaidLink($input: CompleteRfiPlaidLinkInput!) { completeRfiPlaidLink(input: $input) { rfiId status bankInstitutionName bankAccounts { bankAccountId bankName lastFour type subtype } } }",
    "variables": {
      "input": {
        "rfiId": "7c1e2a90-4b3d-4f6e-9a18-3d5b2c7e8f01",
        "questionId": "q_address",
        "publicToken": "public-sandbox-5c224a01-8314-4491-a06f-39e193d5cddc"
      }
    }
  }'
```

## 回應詳情

### CompleteRfiPlaidLinkResponse

| 欄位 | 類型 | 說明 |
| - | - | - |
| `rfiId` | `UUID!` | 輸入中的 RFI |
| `status` | `RfiStatus!` | 維持為 `PENDING_DOCUMENTS`。請使用 `submitRfi` 送出 RFI 以供審核 |
| `requiresAddress` | `Boolean!` | 與 `completePlaidLink` 相同：為 `true` 時，請使用 `createPlaidLinkAddress` 附上地址。請參閱[管理已連結的銀行帳戶](https://docs.fluz.app/features/link-external-bank-accounts.md) |
| `bankAccountId` | `UUID` | 已連結的銀行帳戶 |
| `bankInstitutionAuthId` | `UUID` | 已連結的銀行連線 |
| `newlyLinkedBankInstitutionAuthId` | `UUID` | 當此次呼叫建立了新的銀行連線時才會設定 |
| `bankInstitutionName` | `String` | 銀行名稱 |
| `platformItemId` | `String` | Plaid item 參考，之後用於修復連線 |
| `bankAccounts` | `[PlaidLinkedBankAccount!]!` | 此連線下所連結的帳戶 |

### PlaidLinkedBankAccount

| 欄位 | 類型 | 說明 |
| - | - | - |
| `bankInstitutionAuthId` | `UUID` | 銀行連線 |
| `bankAccountId` | `UUID` | 帳戶 |
| `bankName` | `String` | 銀行名稱 |
| `lastFour` | `String` | 帳號末四碼 |
| `type` | `String` | Plaid 帳戶類型，例如 `depository` |
| `subtype` | `String` | Plaid 帳戶子類型，例如 `checking` |

```json theme={null}
{
  "data": {
    "completeRfiPlaidLink": {
      "rfiId": "7c1e2a90-4b3d-4f6e-9a18-3d5b2c7e8f01",
      "status": "PENDING_DOCUMENTS",
      "bankInstitutionName": "Chase",
      "bankAccounts": [
        {
          "bankAccountId": "4a8d2f61-9c3e-4b7a-a215-6e0f8b9c1d32",
          "bankName": "Chase",
          "lastFour": "4417",
          "type": "depository",
          "subtype": "checking"
        }
      ]
    }
  }
}
```

此呼叫完成後，讀取該問題時會顯示 `isSubmitted: true`，且 `answer` 的類型為 `PLAID_BANK_LINK`。

## 地址問題

對於 `ADDRESS_VERIFICATION_OR_DOCUMENT` 問題，銀行必須確認客戶的地址。若銀行未確認：

* 呼叫會失敗並回傳 `ADDRESS_NOT_VERIFIED`，且不會儲存任何回覆，
* 該銀行**仍會保持連結**在客戶的帳戶上，並且
* 客戶可以連結其他銀行，或者您也可以[上傳](https://docs.fluz.app/upload-rfi-document)地址證明文件，並在 `submitRfi` 中回覆該問題。

## 取代連結

只要 RFI 仍為 `PENDING_DOCUMENTS`，針對同一個問題再次呼叫 `completeRfiPlaidLink` 就會取代已儲存的連結。已使用文件回覆的問題無法改為銀行連結。

## 錯誤碼

失敗會在最上層的 `errors` 陣列中回傳。RFI 錯誤會帶有 `extensions.rfiErrorCode`。

| 代碼 | `rfiErrorCode` | 說明 | 解決方式 |
| - | - | - | - |
| `AUTH-0002` | — | 使用了 Basic 驗證 | 使用 Bearer 使用者權杖呼叫 |
| `AUTH-0008` | — | Bearer 權杖沒有 `userId` 或 `accountId` | 為使用者與帳戶產生權杖 |
| `AUTH-0031` | — | 權杖缺少 `MANAGE_RFI` 或 `MANAGE_PAYMENT` | 加入兩個權限範圍並重新產生權杖 |
| `G-0003` | `ACCESS_DENIED` | RFI 不存在，或並非寄給該權杖的使用者與帳戶 | 使用您讀取該 RFI 時所用的權杖 |
| `ARG-0001` | `INVALID_INPUT` | `rfiId`、`questionId` 或 `publicToken` 格式不正確 | 檢查輸入內容 |
| `ARG-0001` | `RFI_NOT_OPEN` | RFI 並未在等待回覆 | 讀取 RFI 以查看其狀態 |
| `ARG-0001` | `RFI_EXPIRED` | RFI 已過期 | 引導客戶聯絡客服 |
| `ARG-0001` | `UNKNOWN_QUESTION` | 沒有具有此 `questionId` 的可回覆問題 | 使用 RFI 目前問題中的 `questionId` |
| `ARG-0001` | `NOT_A_LINK_QUESTION` | 該問題不是銀行連結或地址問題 | 在 `submitRfi` 中回覆 |
| `ARG-0001` | `ALREADY_SUBMITTED` | 該問題已儲存文件 | 無需處理。該問題已回覆 |
| `ARG-0001` | `ADDRESS_NOT_VERIFIED` | 銀行未確認客戶的地址。`extensions.identityMatchStatus` 會提供結果。該銀行仍保持連結 | 連結其他銀行，或上傳地址證明 |
| `ARG-0001` | `PLAID_LINK_FAILED` | 無法完成銀行連結 | 請客戶再次嘗試 Plaid Link |
| `ARG-0001` 或 `G-0001` | — | Plaid 無法交換公開權杖 | 使用新的 Link 權杖重新開始 |

## 相關頁面

> [card] [提交 RFI](https://docs.fluz.app/submit-rfi)
>
> 連結後送出 RFI 以供審核。

> [card] [透過 Plaid 連結銀行帳戶](https://docs.fluz.app/features/link-via-plaid.md)
>
> `createPlaidLinkToken` 與 Plaid Link 流程。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.