輪詢批次作業的狀態與計數器、讀取每個目標的結果,並下載結果檔案。在你提交批次操作之後,接著執行兩個查詢:用
getBulkOperationJob 取得作業的狀態與彙總計數器,並用 getBulkOperationItems 取得每個目標的詳細資訊。完成狀態僅支援輪詢 — 不提供批次用的 webhook。
需求條件
Authorization: Basic <API_KEY>- 你的應用程式已啟用批次 API 能力。
- 作業必須屬於你的應用程式 — 不明或屬於其他應用的作業 id 會回傳找不到。
查詢 — 作業狀態
持續輪詢直到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。當連結過期(resultUrlExpiresAt)後,再次請求該欄位即可取得新的 URL。
參數
回應欄位
getBulkOperationItems 與結果檔案是相同逐項目資料的兩種檢視。使用 items 查詢可程式化對帳(篩到 FAILED,對應 resultResourceId);對於大型作業,使用結果檔案一次拉取完整分錄。錯誤
這些查詢僅會在請求本身失敗時整體失敗 — 錯誤的目標絕非請求錯誤,而是逐項目的FAILED/SKIPPED 結果(見下方)。
逐項目失敗代碼
FAILED 或 SKIPPED 項目會包含機器可讀的 errorCode 與給人看的 errorMessage。SKIPPED 代碼在提交時指派(該目標從未進入佇列);FAILED 代碼可能來自提交時驗證,或對於已被接受的項目,來自執行時下游服務的錯誤。
任何操作:
僅限
CREATE_TRANSFER:
僅限
DEPOSIT_CASH_BALANCE:
帶有類別前綴的代碼為 Fluz 指派;標示為 downstream 的列表示該項目攜帶執行服務本身的錯誤代碼,故這些代碼是開放集合。請針對你能處理的代碼撰寫程式,並將未知代碼視為一般性失敗 — 可讀取
errorMessage 取得人類可讀的原因。