> ## 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**(或多个 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.