Skip to main content
Fluz 账户上每一笔资金变动都会产生一条交易记录：礼品卡购买、虚拟卡授权、存款、取款、内部转账、钱包间转账、账单支付以及返现。一个信息流、一种结构、一个查询。 记录是账户级别的。不存在用户级别的过滤：一次查询会返回你的令牌所限定账户上的所有内容。

​
我应该使用哪个查询？

拒绝不是一种交易状态。 status 只会是 PENDING 或 SETTLED：被拒绝的授权永远不会变成已结算的交易，因此它根本不会出现在 getTransactions 中。如果你要排查“扣款没有成功”的问题，应该使用 getDeclinedTransactions 和拒绝代码，而不是这个信息流。
字段命名并不统一，你必须精确匹配。Transaction 类型上的大多数字段使用 snake_case：record_id、transaction_type、created_at、cash_balance_available_balance。但较新添加的字段使用 camelCase：memo、transactionCategory、attachmentUrl、connectedAppId、connectedAppName、expectedClearedDate。记录周围的一切都是 camelCase：过滤输入（createdGte、amountGte、virtualCardProgram）以及连接字段（totalCount、hasNextPage）。在编写查询之前先内省 schema，而不要假设某种约定。→ GraphQL API 的工作原理

​
记录包含哪些内容

大约五十个字段，分为六组。只请求你需要的字段：如果请求全部字段，响应会非常庞大。
record_id、account_id、user_id、user、transaction_type、channel（WEB、MOBILE、API）、connectedAppId 和 connectedAppName：由你的哪个应用发起。
amount、fee、cashback、cashback_rate、bonus_cashback_rate，再加上两个值得了解的方向性字段：
  • external_funding_source_activity：外部资金来源（银行卡和账户）的变动
  • fluz_balance_activity：Fluz 内部余额的变动
这两个字段合在一起可以告诉你资金是流入了 Fluz、流出了 Fluz，还是仅在内部流转。
参见下文：每条记录都携带每种余额的事后状态。
source 和 destination 为展示字符串（如 “Visa ****1234”、“Amazon”）、description、merchant_id、logo_url、card_last_four、card_display_name、virtual_card_program、source_type。外币交易还会附加 original_currency_amount、original_currency_code 和 conversion_rate。
memo、transactionCategory、attachmentUrl：参见添加注释。
reference_id、transfer_id、liability_id、used_user_cash_balance_id、descriptor_id：用于对账的字段。参见对账。

​
余额快照

每笔交易都携带该交易应用之后每一种余额类型的余额。这使得该信息流成为一个可重放的账本：你无需单独的余额历史 API，就能重建账户在其历史上任意时间点的状态。
seat_balance_* 是奖励余额。这个命名是历史遗留的，不要去寻找一个单独的“seat”概念。
每种余额都有 _available_balance 和 _total_balance 两个版本。成对出现的 is_*_affected 布尔字段（is_cash_balance_affected、is_seat_balance_affected、is_gift_card_balance_affected、is_reserve_balance_affected）会告诉你这笔交易实际影响了哪些余额，比对快照做差值判断的成本更低。 → 参见钱包概览了解每种余额分别是什么。

​
过滤

getTransactions 接受一个功能丰富的 TransactionFilterInput。各字段族如下： amount 是基础金额；finalAmount 是金额加上手续费，即实际扣款总额。在核对资金来源被扣了多少款项时，应按 finalAmount 过滤。
在依赖 transactionType 之前，请先确认其可接受的取值。 参考页面在一处列出了人类可读的字符串（Add Money、Gift Card Purchase、Transfer - Out），又在示例和示例响应中使用了枚举风格的常量（GIFT_CARD_PURCHASE、DEPOSIT）。两者不可互换。请先查询一小页未过滤的数据，查看你的账户实际返回的 transaction_type 取值。

​
分页与吞吐量

limit 最大为 20，offset 用于向前翻页。请检查 hasNextPage，而不要根据短页面去推断；totalCount 会给出过滤后结果集的完整大小。 GraphQL API 对每个 IP 和每个访问令牌都限制为每秒 20 个请求，且响应中不带任何速率限制相关的响应头。参见速率限制。
在构建同步任务之前先算一下账。 每次查询 20 条记录、每秒 20 个请求，上限是每秒 400 笔交易，而一次只发一个请求的实际吞吐量会远低于这个数字。一个累计有 50 万笔交易的账户，需要 25,000 次请求才能完整遍历一遍。应按增量同步来设计：用 createdGte/updatedGte 结合你上一次成功同步的水位线来限定每个任务的范围，绝不要重新遍历你已经拥有的历史数据。

​
为交易添加注释

你可以为任意交易附加一段自由文本 memo（最多 255 个字符）、一个 transactionCategory 和一个文件：既可以在存款、购买和转账发生时附加，也可以之后通过 updateTransactionMetadata 补充。分类会在首次使用时创建，之后再次使用相同名称时会被复用。
attachmentUrl 是一个会过期的签名 URL，切勿存储它。 需要用到文件时，请重新获取该笔交易。这也会破坏简单的缓存方案。已结算的交易看起来是不可变的，但 memo、transactionCategory 和 attachmentUrl 在结算之后仍然是可变的：因此被缓存的 SETTLED 记录会返回过期的注释和失效的附件链接。你可以缓存财务字段，但注释部分需要重新获取。
→ 添加费用详情

​
与你自己的系统对账

有五个字段用于关联： 一种可行的模式：
  1. 在创建订单时，将 record_id 和 reference_id 存储到你自己的订单记录上。不要试图之后再靠金额和时间戳去匹配。
  2. 按 updatedGte 做增量同步，而不是 createdGte：一笔 PENDING 交易之后结算时会更新 updated_at，按创建日期同步会漏掉这次状态变化。
  3. 预期会有结算延迟。 ACH 取款会保持 PENDING 状态 1 到 3 个工作日；卡授权则按各自的时间线结算。expectedClearedDate 会告诉你什么时候该再来查看。
  4. 用快照来核对余额，而不是靠累加金额。*_available_balance 字段是权威数据，已经把手续费、返现和待处理的预留都计算在内。
externalReferenceId 不会出现在交易记录上。如果你需要在一笔资金变动上带上自己的用户 ID，请通过账户进行关联，或者在交易发生时把它写进 memo。→ 管理外部引用 ID

​
权限范围

getTransactions 同时需要 LIST_PAYMENT 和 LIST_PURCHASES。缺少任意一个都会返回 FORBIDDEN 错误，并在其中指出所需的权限范围。 开始开发前，请在你应用的 Permissions（权限）标签页中启用这两项权限：请求了但未启用的权限范围会被静默丢弃，而不是报错拒绝。→ 配置 OAuth 应用

​
下一步

获取所有交易

完整的过滤、字段与分页参考。

被拒绝的交易

从未变成交易的授权请求。

拒绝代码

每种拒绝原因分别代表什么。

虚拟卡交易

限定在一张或多张卡上的交易。

礼品卡购买

订单，而非账本条目。

添加费用详情

备注、分类与附件。