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

# 獎勵自動轉入

> 每天自動將已連結帳戶的可用獎勵轉入您的消費帳戶。

獎勵自動轉入功能會每天一次，將某個帳戶的可用獎勵轉入另一個 Fluz 帳戶的消費帳戶，無需使用者進行任何操作。您的應用程式會將使用者的帳戶連結至已核准的目標帳戶，其餘由 Fluz 執行轉入。

當您的平台需要收取使用者在 Fluz 上賺取的獎勵時，就可以使用此功能。例如，將會員賺取的現金回饋自動轉入您平台的營運消費帳戶。

本頁涵蓋 TGS GraphQL 介面：

* [`createRewardsSweepConnection`](https://docs.fluz.app/api-reference/mutations/create-rewards-sweep-connection)
* [`deleteRewardsSweepConnection`](https://docs.fluz.app/api-reference/mutations/delete-rewards-sweep-connection)

***

## 運作方式

1. Fluz 核准您的目標帳戶、設定獎勵轉入的消費帳戶，並將您的應用程式加入允許清單。這是由 Fluz 執行的一次性設定，完成前其他功能都無法運作。請參閱[與 Fluz 完成設定](#set-up-with-fluz)。
2. 使用者授權您的應用程式。您的應用程式使用使用者的存取權杖和您的目標帳戶 ID 呼叫 `createRewardsSweepConnection`。
3. 每個紐約日曆日一次，Fluz 會將使用者的全部可用獎勵餘額轉入您的目標消費帳戶。
4. 若要停止，您的應用程式使用使用者的存取權杖呼叫 `deleteRewardsSweepConnection`。

在本頁中，**來源帳戶**是被轉出獎勵的使用者帳戶，**目標帳戶**是接收款項的帳戶，**消費帳戶**則是款項實際轉入的目標帳戶之消費帳戶。

> [!NOTE]
>
> **只會轉入可用獎勵。**
>
> 轉入作業會在執行當下取用可花費的獎勵餘額。待處理或鎖定的獎勵會保留在來源帳戶，等待之後的轉入作業處理。系統不會預先保留任何款項：在轉入執行之前，使用者可以正常花費其獎勵。

***

## 與 Fluz 完成設定

> [!WARNING]
>
> **在您連結任何帳戶之前，Fluz 必須先核准您的目標帳戶並將您的應用程式加入允許清單。**
>
> 您無法自行透過 API 完成此設定。在 Fluz 完成這兩項作業之前，`createRewardsSweepConnection` 會失敗，並回傳 `App is not allowed to create a rewards sweep connection` 或 `Target account is not approved for rewards sweep`。

請聯絡您的 Fluz 客戶經理，並提供以下資訊：

| 提供給 Fluz | 原因 |
| - | - |
| 您的**目標帳戶 ID** | 接收轉入獎勵的帳戶。Fluz 會將其加入已核准的目標。 |
| 該目標帳戶上的**消費帳戶** | 款項轉入的位置。它必須屬於該目標帳戶。每個目標僅有一個目的地消費帳戶。 |
| 您的**應用程式 ID**（可多個） | Fluz 會將每個會呼叫獎勵自動轉入 mutation 的應用程式加入允許清單。 |

目標核准且應用程式加入允許清單後，Fluz 會通知您。若之後要變更目的地消費帳戶或新增其他應用程式，請再次聯絡 Fluz。您的應用程式無法自行變更其設定。

Fluz 也可以透過自己的後台將帳戶連結至您的目標，無需呼叫 API。

### 每次呼叫的需求

| 需求 | 值 |
| - | - |
| 驗證 | 來源帳戶的 Bearer 權杖。不支援 Basic Auth。 |
| 範圍 | `MAKE_PAYOUT_TRANSFER_SEND`（與 [`createTransfer`](https://docs.fluz.app/api-reference/mutations/create-transfer) 相同的範圍）。請在使用者授權您的應用程式時申請。 |
| 應用程式 | 已由 Fluz 加入獎勵自動轉入的允許清單 |
| 目標 | 已由 Fluz 核准用於獎勵自動轉入 |

***

## 連結帳戶

使用使用者的存取權杖呼叫 `createRewardsSweepConnection`。來源帳戶一律取自權杖。請傳入您的目標帳戶 ID，而非消費帳戶 ID。

```graphql theme={null}
mutation {
  createRewardsSweepConnection(input: {
    targetAccountId: "b2c3d4e5-f6a7-8901-bcde-f23456789012"
  }) {
    rewardsSweepSourceAccountId
    sourceAccountId
    targetAccountId
  }
}
```

```text theme={null}
Authorization: Bearer <user-access-token>
```

```json theme={null}
{
  "data": {
    "createRewardsSweepConnection": {
      "rewardsSweepSourceAccountId": "7c1e2d3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
      "sourceAccountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "targetAccountId": "b2c3d4e5-f6a7-8901-bcde-f23456789012"
    }
  }
}
```

**規則**

* 一個來源帳戶同一時間只能連結至一個目標。
* 以相同目標再次呼叫 create 是安全的，會回傳現有的連結。
* 在已有連結的情況下，以不同目標呼叫 create 會失敗。若要變更目標，請先中斷連結，再連結至新目標。
* 來源帳戶與目標帳戶必須不同。
* Fluz 也可以從其後台為帳戶建立連結。該連結的行為相同，並可透過 `deleteRewardsSweepConnection` 移除。

***

## 中斷帳戶連結

使用使用者的存取權杖呼叫 `deleteRewardsSweepConnection`。它不需要任何輸入，會移除權杖所屬帳戶的連結。

```graphql theme={null}
mutation {
  deleteRewardsSweepConnection {
    sourceAccountId
    disconnected
  }
}
```

```json theme={null}
{
  "data": {
    "deleteRewardsSweepConnection": {
      "sourceAccountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "disconnected": true
    }
  }
}
```

當帳戶沒有任何連結時，`disconnected` 為 `false`。這並非錯誤，因此可以安全地重複呼叫。

若您在當日轉入已排程之後、款項移動之前中斷連結，當日的轉入會被取消，且不會扣款。

***

## 轉入行為

| | |
| - | - |
| 頻率 | 每個來源帳戶每個日曆日最多轉入一次，以 `America/New_York` 時間為準。執行時間由 Fluz 設定。 |
| 金額 | 轉入執行當下的全部可用獎勵餘額，無條件捨去至整數分。不足一分的部分會保留在來源帳戶。 |
| 餘額為零 | 不會進行轉帳。該日仍視為已完成轉入。 |
| 目的地 | 當日轉入排程時，為該目標所設定的消費帳戶。 |
| 重試 | 每日轉入都有固定的冪等鍵，因此重試絕不會重複轉移款項。 |
| 餘額不足 | 若餘額在款項移動前發生變動，轉入作業會重新讀取餘額並重試。 |
| 被拒絕的轉入 | 若 Fluz 無法移動該帳戶的款項，例如帳戶正在審查中，當日的轉入會停止且不會重試。獎勵會保留在來源帳戶，隔天的轉入會再次嘗試。 |
| 已中斷連結 | 若帳戶在當日轉入排程之後、款項移動之前被中斷連結，則不會扣款。 |

***

## 帳戶端的顯示

每次轉入都是一筆帳戶對帳戶的轉帳，並會在兩個帳戶的活動紀錄中顯示，說明為 **Rewards transfer**。

| 帳戶 | 活動紀錄列 |
| - | - |
| 來源 | 款項從 Fluz 獎勵餘額轉出至目標帳戶及消費帳戶 |
| 目標 | 款項從來源帳戶轉入並進入消費帳戶 |

***

## 檢查連結

目前沒有可讀取連結或過往轉入紀錄的查詢。請根據 `createRewardsSweepConnection` 和 `deleteRewardsSweepConnection` 的回應，在您這邊儲存連結資訊。您可以從目標帳戶的交易活動確認轉入紀錄。

***

## 錯誤

失敗時會使用標準的 GraphQL 錯誤格式。

```json theme={null}
{
  "data": null,
  "errors": [
    {
      "message": "Target account is not approved for rewards sweep",
      "extensions": {
        "code": "APPLICATIONS-0012",
        "errorName": "InvalidArgument",
        "statusCode": 422
      }
    }
  ]
}
```

錯誤會依下列順序檢查：

| 代碼 | 訊息 | 時機 |
| - | - | - |
| `AUTH-0002` | Basic auth is not supported for this operation. | 請求使用了 Basic Auth。請改用使用者的 Bearer 權杖。 |
| `AUTH-0031` | Insufficient permissions: `<mutation>` requires MAKE\_PAYOUT\_TRANSFER\_SEND | 權杖缺少 `MAKE_PAYOUT_TRANSFER_SEND` 範圍。 |
| `AUTH-0008` | Authenticated account is required. | 權杖無法對應到任何帳戶。 |
| `AUTH-0008` | App is not allowed to create a rewards sweep connection | 您的應用程式未加入獎勵自動轉入的允許清單。Delete 會回傳相同訊息，但為 "delete"。 |
| `APPLICATIONS-0012` | Target account is not approved for rewards sweep | `targetAccountId` 不是已登記的目標，或沒有消費帳戶。僅限 create。 |
| `APPLICATIONS-0012` | Source and target accounts must be different. | 權杖所屬帳戶即為目標帳戶。僅限 create。 |
| `APPLICATIONS-0012` | Source account is already connected to a rewards sweep target | 該帳戶已連結至不同的目標。請先中斷連結。僅限 create。 |

缺少、無效或過期的存取權杖會在 GraphQL 執行前被拒絕，並回傳 HTTP 錯誤，而非 GraphQL 錯誤。請參閱[驗證](https://docs.fluz.app/api-reference/authentication.md)。


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