> ## 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.

# 提交 RFI

> 使用 submitRfi 傳送客戶對資訊請求的回答,可一次全部提交或分批提交,並處理各題的驗證錯誤。

## 概覽

**submitRfi** mutation 會儲存客戶對未結 RFI 的回答。

* 當 `finalize: true`(預設值)時,RFI 會被送交審核並進入 `IN_REVIEW` 狀態。所有必填問題都必須已回答,可以是在本次呼叫中回答,也可以是先前已儲存的回答。
* 當 `finalize: false` 時,只會儲存您傳送的回答,RFI 仍維持 `PENDING_DOCUMENTS` 狀態,其餘回答可在之後的呼叫中補上。

無論哪種方式,回答都會依據 RFI 的問題進行驗證。

## 所需權限範圍

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

請使用與讀取 RFI 時相同的客戶權杖。請參閱[誰可以回答 RFI](https://docs.fluz.app/rfi-overview#who-can-answer-an-rfi)。

## 基本 mutation 結構

```graphql theme={null}
mutation SubmitRfi($input: SubmitRfiInput!) {
  submitRfi(input: $input) {
    success
    rfiId
    status
    error {
      code
      message
      validationErrors {
        questionId
        code
        message
      }
    }
  }
}
```

## 參數

### SubmitRfiInput

| 欄位 | 類型 | 必填 | 說明 |
| - | - | - | - |
| `rfiId` | `UUID!` | 是 | 要回答的 RFI |
| `answers` | `[RfiAnswerInput!]!` | 是 | 尚未有已儲存回答之問題的回答 |
| `finalize` | `Boolean` | 否 | `true`(預設):將 RFI 送交審核。`false`:儲存這些回答並保持 RFI 開啟 |

### RfiAnswerInput

| 欄位 | 類型 | 必填 | 說明 |
| - | - | - | - |
| `questionId` | `String!` | 是 | 來自 `RfiQuestion.questionId` |
| `value` | `JSON` | — | 回答內容。其格式取決於問題類型,請參閱[問題類型](https://docs.fluz.app/rfi-overview#question-types) |

每個問題請傳送一個回答。請省略以下項目:

* `isSubmitted: true` 的問題(已儲存),
* `SECTION_BREAK` 問題,
* 您已透過 [completeRfiPlaidLink](https://docs.fluz.app/complete-rfi-plaid-link) 回答的銀行連結與地址問題,除非您改為為這些問題上傳文件。

## 範例變數

```json theme={null}
{
  "input": {
    "rfiId": "7c1e2a90-4b3d-4f6e-9a18-3d5b2c7e8f01",
    "finalize": true,
    "answers": [
      {
        "questionId": "q_formation",
        "value": [
          { "fileId": "b52f0e4a-1c7d-4a9b-8e36-0f2d9c4a7b15" }
        ]
      },
      {
        "questionId": "q_address",
        "value": [
          { "fileId": "e1d94c3b-6a2f-4c8e-b07d-5a9f1e3c2d48" }
        ]
      },
      {
        "questionId": "q_source_of_funds",
        "value": "Other"
      },
      {
        "questionId": "q_source_of_funds_other",
        "value": "Proceeds from the sale of a previous business"
      }
    ]
  }
}
```

## 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 SubmitRfi($input: SubmitRfiInput!) { submitRfi(input: $input) { success rfiId status error { code message validationErrors { questionId code message } } } }",
    "variables": {
      "input": {
        "rfiId": "7c1e2a90-4b3d-4f6e-9a18-3d5b2c7e8f01",
        "answers": [
          { "questionId": "q_source_of_funds", "value": "Business revenue" }
        ]
      }
    }
  }'
```

## 回應詳細資料

### SubmitRfiResponse

| 欄位 | 類型 | 說明 |
| - | - | - |
| `success` | `Boolean!` | 回答已儲存時為 `true` |
| `rfiId` | `UUID!` | 輸入中的 RFI |
| `status` | `RfiStatus` | 已完成提交時為 `IN_REVIEW`。`finalize` 為 `false` 時為 `PENDING_DOCUMENTS`。失敗時為 `null` |
| `error` | `SubmitRfiError` | 當 `success` 為 `false` 時會設定 |

### 成功

```json theme={null}
{
  "data": {
    "submitRfi": {
      "success": true,
      "rfiId": "7c1e2a90-4b3d-4f6e-9a18-3d5b2c7e8f01",
      "status": "IN_REVIEW",
      "error": null
    }
  }
}
```

### 驗證失敗

```json theme={null}
{
  "data": {
    "submitRfi": {
      "success": false,
      "rfiId": "7c1e2a90-4b3d-4f6e-9a18-3d5b2c7e8f01",
      "status": null,
      "error": {
        "code": "RFI_VALIDATION_FAILED",
        "message": "Some answers are invalid.",
        "validationErrors": [
          {
            "questionId": "q_address",
            "code": "REQUIRED",
            "message": "This question is required. Upload a document or link a bank account with completeRfiPlaidLink."
          },
          {
            "questionId": "q_source_of_funds",
            "code": "DUPLICATE_ANSWER",
            "message": "Only one answer per question is allowed."
          }
        ]
      }
    }
  }
}
```

驗證失敗時,本次呼叫中的任何內容都不會被儲存。請修正列出的回答後重新傳送呼叫。

## 分批儲存

使用 `finalize: false` 可讓客戶中途離開稍後再回來,或在填寫長表單時逐頁儲存。

> [!WARNING]
>
> **已儲存的回答為最終結果。** 問題一旦有已儲存的回答,就會被標記為 `isSubmitted: true` 且無法變更,再次傳送會回傳 `ALREADY_SUBMITTED`。請僅在客戶確認後才儲存回答。唯一的例外是 Plaid 銀行連結,可由 [completeRfiPlaidLink](https://docs.fluz.app/complete-rfi-plaid-link) 取代。

* 分批儲存不會變更 RFI 的狀態,也不會將其送交審核。
* 必填問題只會在您完成提交時檢查。如果所有必填項目都已儲存,完成提交的呼叫可以只是 `{ "rfiId": "...", "answers": [] }`。
* 完成提交後,RFI 會變為 `IN_REVIEW`,之後的呼叫會回傳 `RFI_NOT_OPEN`。如果 Fluz 需要更多資料,RFI 會帶著新問題回到 `PENDING_DOCUMENTS`。

## 條件式問題

`visibilityCondition` 不成立的問題會被略過:

* 這些問題不是必填,且
* 您為這些問題傳送的任何回答都會被忽略,不會有錯誤,也不會儲存任何內容。

可見性會依 `ordinal` 順序,根據先前的回答判定,並使用已儲存的回答以及同一次呼叫中的回答。請參閱[條件式問題](https://docs.fluz.app/rfi-overview#conditional-questions)。

## 錯誤代碼

### Payload 錯誤

`submitRfi` 會在 payload 中以 `success: false` 回傳 RFI 錯誤,而不是放在頂層的 `errors` 陣列中。

| `error.code` | 說明 | 解決方式 |
| - | - | - |
| `ACCESS_DENIED` | RFI 不存在,或並非寄給該權杖的使用者與帳戶 | 使用您讀取 RFI 時所用的權杖 |
| `RFI_NOT_OPEN` | RFI 不是 `PENDING_DOCUMENTS` 狀態,已在審核中或已完成 | 讀取 RFI 以查看其狀態 |
| `RFI_EXPIRED` | RFI 已過期 | 請引導客戶聯絡支援團隊 |
| `RFI_VALIDATION_FAILED` | 一個或多個回答未通過驗證。請參閱 `validationErrors` | 修正每個列出的回答並重新傳送 |
| `RFI_SUBMIT_FAILED` | 非預期錯誤 | 重試一次。若問題持續,請提供 `rfiId` 聯絡支援團隊 |

### validationErrors 代碼

| `code` | 說明 |
| - | - |
| `UNKNOWN_QUESTION` | 沒有具此 `questionId` 的可回答問題,或該問題為 `SECTION_BREAK` |
| `ALREADY_SUBMITTED` | 該問題已有已儲存的回答 |
| `DUPLICATE_ANSWER` | 相同的 `questionId` 在 `answers` 中出現超過一次 |
| `REQUIRED` | 適用的必填問題沒有回答。僅在完成提交時發生 |
| `INVALID_VALUE` | 值與問題類型不符,例如格式錯誤、不屬於 `options` 之一、檔案過多、`fileId` 是為其他問題上傳或被重複使用,或該問題不接受此檔案類型 |

### 頂層錯誤

這些錯誤會在 mutation 執行之前,於 `errors` 陣列中回傳。

| 代碼 | 名稱 | 說明 | 解決方式 |
| - | - | - | - |
| `AUTH-0002` | InvalidCredentials | 使用了 Basic auth | 使用 Bearer 使用者權杖進行呼叫 |
| `AUTH-0031` | InvalidScope | 權杖缺少 `MANAGE_RFI` | 新增該權限範圍並重新產生權杖 |

## 最佳實務

* **先在您的 UI 中驗證。** 呼叫之前先檢查格式、選項與必填欄位,讓驗證失敗的情況很少發生。
* **只完成提交一次。** 如有需要,可使用 `finalize: false` 儲存各頁,並在客戶按下提交時再完成提交。
* **顯示結果。** 進入 `IN_REVIEW` 後,顯示「審核中」狀態,並停止針對此 RFI 再次提示客戶。

## 相關頁面

> [card] [讀取 RFI](https://docs.fluz.app/get-rfis)
>
> 問題、已儲存的回答與狀態。

> [card] [上傳 RFI 文件](https://docs.fluz.app/upload-rfi-document)
>
> 取得檔案類問題所需的 `fileId` 值。

> [card] [以銀行連結回答](https://docs.fluz.app/complete-rfi-plaid-link)
>
> 使用 Plaid 回答銀行對帳單與地址證明類問題。

> [card] [RFI 概覽](https://docs.fluz.app/rfi-overview)
>
> 狀態、問題類型與完整流程。


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