輪詢大量作業的狀態與計數器、讀取每個目標的結果,並下載結果檔案。在你提交大量操作之後,接著進行兩個查詢:
getBulkOperationJob 取得作業狀態與彙總計數器,getBulkOperationItems 取得每個目標的詳細結果。完成狀態僅支援輪詢——沒有大量作業的 webhook。
目前僅在
staging 可用。必要條件
Authorization: Basic <API_KEY>- 你的應用程式已啟用大量 API 能力。
- 該作業必須屬於你的應用程式——未知或屬於其他應用的作業 id 會回應 not-found。
查詢 — 作業狀態
重複輪詢直到status 進入終止狀態(COMPLETED、COMPLETED_WITH_ERRORS、FAILED 或 CANCELLED)。
查詢 — 個別目標結果
使用游標分頁(每頁 100 筆),可依項目狀態過濾——篩選FAILED 以僅對帳失敗項,或讀取 resultResourceId 將成功寫入對應回其產生的 Fluz 資源。
下載結果檔案
擷取resultUrl 會即時產生一個短效(約 15 分鐘)的簽名下載 URL——僅輪詢狀態而不請求它,成本更低。開啟該連結(或以 curl -L)下載一個 NDJSON 檔案,每個目標一行。
- 匯出(
GET_*_EXPORT)——匯出的餘額/交易。 - 寫入(
CREATE_TRANSFER、DEPOSIT_CASH_BALANCE)——結果分類帳:每個目標一列{ externalReferenceId, accountId, status, resultResourceId, resourceType, errorCode, errorMessage }。
resultUrl 在作業進入終止狀態前為 null,或對於未產生檔案的作業亦為 null。當連結過期(resultUrlExpiresAt)後,再次請求該欄位以取得新的 URL。
參數
回應欄位
getBulkOperationItems 與結果檔案是同一批每項目資料的兩種視圖。使用 items 查詢可程式化對帳(篩選 FAILED、對應 resultResourceId);使用結果檔案則可一次性拉取大型作業的完整分類帳。錯誤
這些查詢只有在請求本身出錯時才會整體失敗——有問題的目標絕非請求錯誤,而是個別項目的FAILED/SKIPPED 結果(見下)。
單項目失敗代碼
FAILED 或 SKIPPED 的項目包含可機器讀取的 errorCode 與人類可讀的 errorMessage。SKIPPED 代碼在提交時指派(該目標未進入佇列);FAILED 代碼可能來自提交時驗證,或對於已被接受的項目,來自執行時的下游服務。
任何操作:
僅限
CREATE_TRANSFER:
僅限
DEPOSIT_CASH_BALANCE:
帶有前綴類別的代碼為 Fluz 指派;downstream 表示該項目會原樣攜帶執行服務本身的錯誤代碼,因此該範圍是開放式的。請針對你已處理的代碼進行程式設計,對未知代碼一律視為一般性失敗——並讀取
errorMessage 以取得人類可讀的原因。