Skip to main content
通过一次异步调用,对许多已连接用户执行写入或大型导出。你提交一个作业,轮询其状态,并(对于导出和写入)下载结果文件。
在一次调用中对你已连接的用户运行批量操作。与同步读取(获取批量余额获取批量交易)不同,submitBulkOperation异步的:它会验证请求,为每个目标创建一个作业和一条项目,并立即返回一个 jobId。工作在后台运行——跟踪该作业以了解进度并获取结果。 一个变更覆盖所有五种操作,由 operation 字段选择:

要求

  • Authorization: Basic <API_KEY>
  • 你的应用已启用批量 API 能力。
  • 所选操作所需的 scope,且由每个目标用户授予(见上表)。缺少 scope 的目标会成为逐项失败——永远不会导致整个作业失败。
每次提交必须携带一个幂等性键——可以是 idempotencyKey 输入,或 Idempotency-Key 头(如果两者都发送则必须匹配)。在请求逐字节完全相同的情况下,使用相同键重新提交会返回原始作业,而不是创建重复项;在相同键下的不同请求将被拒绝。对于扇出式写入,没有安全的默认行为,因此该键为必填。

变更

成功提交会返回处于 QUEUED 状态的作业。acceptedItemCount 表示将被处理的目标数量;skippedItemCount 表示在前置阶段被拒绝的数量(例如缺少所需的 scope)。轮询该作业以观察 succeededItemCount / failedItemCount 的变化——参见跟踪批量作业

变量 — 导出余额 / 交易

exportOptions 限定窗口(默认为最近 90 天;GET_BALANCES_EXPORT 为时点快照,忽略该窗口)。与读取相同,使用目标选择

变量 — 创建转账

每个项目指定其各自的 fromto 端点,因此一个作业可以混合多种方向:运营方→用户、用户→运营方,以及用户→用户。一个端点要么{ "operator": true }(你的应用的付款账户)要么{ "externalReferenceId": "…" }(一个已连接用户)。fromto 必须不同。来源用户的授权必须允许 MAKE_PAYOUT_TRANSFER_SEND;目的方只需已连接。转账在同一赞助银行内进行。对于转账不需要 targetSpec——参与方来自各条项目。

变量 — 充值现金余额

从已连接用户本人的支付方式为其消费账户充值——每条项目在 bankCardIdbankAccountId 中恰好选择一个。使用 SELECTED 目标方式,每个目标一条项目。userCashBalanceId 可选(默认为用户的许可/默认消费账户)。

变量 — 更新交易元数据

编辑用户交易上的 memo 和/或 transactionCategory。使用 SELECTED 目标方式,每个目标一条项目,每次提交最多 100 次编辑。将某字段设为 null 会清空它;省略的字段保持不变。元数据编辑是同步执行的——返回的作业已处于终态,因此你可以立即读取每次编辑的结果而无需轮询。

响应

参数

响应字段

失败是逐项的——某个目标的失败不会使作业失败(参见按目标的失败约定)。仅当发生认证失败、无效操作、超出上限,或当_所有_目标均不可解析时,请求本身才会被拒绝并失败。达到终态后,通过跟踪批量作业读取逐项详情——包括每次写入产生的资源。

错误

仅在以下情况会拒绝整个提交(不创建作业)。其他一切将成为逐项结果,可通过跟踪批量作业读取。