Skip to main content
批量 API 使你的应用能够在一次调用中跨越多个已连接的 Fluz 用户执行操作,而无需逐个遍历用户令牌。它专为需要代表已连接到你应用的用户读取或(即将推出)转移资金的 OAuth 应用开发者而构建。
这与虚拟卡中的“Create Virtual Card Bulk Order(创建虚拟卡批量订单)”操作不同,后者是为单个账户创建多张卡。批量 API 则是在你的已连接用户之间进行操作。

适用对象

批量 API 在应用级别受控。你的应用必须由 Fluz 启用批量 API 能力——请联系我们申请访问权限。非批量启用应用发起的调用会被以 BulkApiAccessDenied 拒绝。

认证

所有批量 API 调用都使用基于你的应用 API key 的 Basic 认证(你的 client_idclient_secret),而不是用户访问令牌:
端点(staging):
端点(production):

授权来源于现有连接

批量 API 从不创建新的同意界面。仅当用户与你的应用存在有效的 OAuth 授权时,该用户才可访问;且每项操作仅在用户已授予该操作所需的 scope 时才被允许。批量访问从不超出等价的单用户操作范围。
  • 断开连接会移除授权,因此断开的用户将不再可访问。
  • 如果用户的授权被限定在特定的消费账户上,则该用户的批量结果会自动限制在这些账户内。

选择目标用户

每个批量操作都接受一个 targetSpec
  • 用户通过他们连接时你提供的 externalReferenceId 来标识——而不是通过 accountId
  • 同步请求最多可指定100 个目标
  • 未使用 externalReferenceId 连接的用户无法单独选择;他们只能通过 ALL_CONNECTED 访问。使用发现已连接用户查看谁已连接以及他们授予了哪些 scope。

按目标的失败约定

单个目标的失败不会导致整个请求失败。每个结果都包含 success,且当 successfalse 时包含 error 只有在应用级问题时,整个请求才会被拒绝:未启用批量功能、无效请求、超过 100 个目标上限,或当所有请求的目标均不可解析时。 每个响应还会汇总 targetCountsuccessCountfailureCount

同步 vs. 异步

  • 有界读取为同步并内联返回:最多 100 个目标,带有每目标限制(例如每个 20 笔交易、90 天时间窗)。本节记录了这三个查询。
  • 写入与大规模导出为异步(即将推出):你提交作业,轮询其状态,并下载结果。同步读取上的 hasNextPage/totalCount 会告诉你何时应改用导出,而不是静默截断。

本节中的操作