Skip to main content
以一次非同步呼叫,對多位已連結使用者執行寫入或大量匯出。您提交一個工作、輪詢其狀態,並且(對於匯出與寫入)下載結果檔案。
以一次呼叫,對您已連結的使用者執行大量作業。不同於同步讀取(取得大量餘額取得大量交易),submitBulkOperation非同步的:它會驗證請求、建立一個工作及每個目標一個項目,並立即回傳 jobId。作業在背景執行 — 追蹤該工作 以查看進度並擷取結果。 一個 mutation 涵蓋所有五種操作,藉由 operation 欄位選擇:

需求

  • Authorization: Basic <API_KEY>
  • 您的應用程式已啟用大量 API 能力。
  • 所選操作所需的 scope,且由每位目標使用者授與(見上表)。缺少者會成為逐項失敗—永遠不會讓整個工作失敗。
每次提交必須帶有冪等性金鑰——可使用 idempotencyKey 輸入欄位或 Idempotency-Key 標頭(若同時傳送,兩者必須相符)。在請求內容位元組完全相同的情況下,重新提交相同金鑰會回傳原始工作而不會建立重複;若在相同金鑰下送出不同請求,則會被拒絕。對於扇出式寫入沒有安全預設,因此必須提供此金鑰。

Mutation

成功提交會回傳狀態為 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 會清除它;省略的欄位則不變動。中繼資料編輯為同步執行——回傳的工作已是終態,因此您可立即讀取每筆編輯結果而無需輪詢。

回應

參數

回應欄位

失敗是逐項的——單一目標的失敗不會讓整個工作失敗(參見逐目標失敗合約)。僅在授權失敗、無效操作、超出上限、或是_所有_目標皆無法解析時,請求本身才會被拒絕。達到終態後,請透過追蹤大量工作 讀取逐項細節——包含每筆寫入所產生的資源。

錯誤

僅在以下情況下,整個提交會被拒絕(不會建立工作)。其他情況皆會成為逐項結果,您可透過追蹤大量工作讀取。