这与虚拟卡中的“Create Virtual Card Bulk Order(创建虚拟卡批量订单)”操作不同,后者是为单个账户创建多张卡。批量 API 则是在你的已连接用户之间进行操作。
适用对象
批量 API 在应用级别受控。你的应用必须由 Fluz 启用批量 API 能力——请联系我们申请访问权限。非批量启用应用发起的调用会被以BulkApiAccessDenied 拒绝。
认证
所有批量 API 调用都使用基于你的应用 API key 的 Basic 认证(你的client_id 和 client_secret),而不是用户访问令牌:
授权来源于现有连接
批量 API 从不创建新的同意界面。仅当用户与你的应用存在有效的 OAuth 授权时,该用户才可访问;且每项操作仅在用户已授予该操作所需的 scope 时才被允许。批量访问从不超出等价的单用户操作范围。- 断开连接会移除授权,因此断开的用户将不再可访问。
- 如果用户的授权被限定在特定的消费账户上,则该用户的批量结果会自动限制在这些账户内。
选择目标用户
每个批量操作都接受一个targetSpec:
- 用户通过他们连接时你提供的
externalReferenceId来标识——而不是通过accountId。 - 同步请求最多可指定100 个目标。
- 未使用
externalReferenceId连接的用户无法单独选择;他们只能通过ALL_CONNECTED访问。使用发现已连接用户查看谁已连接以及他们授予了哪些 scope。
按目标的失败约定
单个目标的失败不会导致整个请求失败。每个结果都包含success,且当 success 为 false 时包含 error:
只有在应用级问题时,整个请求才会被拒绝:未启用批量功能、无效请求、超过 100 个目标上限,或当所有请求的目标均不可解析时。
每个响应还会汇总
targetCount、successCount 和 failureCount。
同步 vs. 异步
- 有界读取为同步并内联返回:最多 100 个目标,带有每目标限制(例如每个 20 笔交易、90 天时间窗)。本节记录了这三个查询。
- 写入与大规模导出为异步(即将推出):你提交作业,轮询其状态,并下载结果。同步读取上的
hasNextPage/totalCount会告诉你何时应改用导出,而不是静默截断。