批次 API - Fluz

批次 API 讓你的應用程式能在一次呼叫中跨許多已連結的 Fluz 使用者執行動作，而不必一次又一次以單一使用者權杖迴圈呼叫。此功能是為需要代表連結至你應用程式的使用者讀取資料或（即將推出）移轉資金的 OAuth 應用程式開發者所打造。

這與虛擬卡片下的「Create Virtual Card Bulk Order」操作不同，後者會為「單一」帳戶建立多張卡片。批次 API 則是跨「你已連結的使用者」運作。

誰可以使用

批次 API 以應用程式層級控管。你的應用程式必須由 Fluz 啟用批次 API 能力——請與我們聯繫以申請存取權。非批次啟用的應用程式所發出的呼叫將以 BulkApiAccessDenied 被拒絕。

所有批次 API 呼叫均使用以你的應用程式 API 金鑰（你的 client_id 與 client_secret）進行的 Basic 驗證，而非使用者存取權杖：

Authorization: Basic <API_KEY>

端點（staging）：

https://transactional-graph.staging.fluzapp.com/api/v1/graphql

端點（production）：

https://transactional-graph.fluzapp.com/api/v1/graphql

批次 API 不會建立新的同意介面。只有在使用者對你的應用程式具有有效的 OAuth 授權時，該使用者才可被觸及，且每個操作都僅在使用者已授與該操作所需的範圍（scopes）時才被允許。批次存取絕不會比等價的單一使用者操作更寬鬆。

每個批次操作都需要 targetSpec：

Mode	Meaning
`ALL_CONNECTED`	目前所有已連結至你應用程式的使用者。
`SELECTED`	僅限你在 `targets` 中列出的、其 `externalReferenceId` 所對應的使用者。

以你在連結時提供的 externalReferenceId 指定使用者——不是以 accountId。
同步請求最多可指定100 個目標。
未以 externalReferenceId 連結的使用者無法被個別選取；只能透過 ALL_CONNECTED 觸及。使用 Discover Connected Users 來查看誰已連結以及他們授與了哪些範圍。

單一目標的失敗不會使整個請求失敗。每個結果都會帶有 success，且當 success 為 false 時會包含 error：

Code	Meaning
`TARGET_NOT_CONNECTED`	此 ID 並非目前已連結至你應用程式的使用者（未知、已撤銷、或從未連結）。
`INVALID_TARGET_IDENTIFIER`	此 ID 不是有效的識別碼。
`INSUFFICIENT_SCOPE`	使用者未授與此操作所需的範圍。
`ACCOUNT_NOT_PERMITTED`	使用者的授權不允許在請求的帳戶上執行此操作。

整個請求只會因應用程式層級的問題而被拒絕：未啟用批次、無效的請求、超過 100 個目標上限，或當所有請求的目標都無法解析時。每個回應也會彙總 targetCount、successCount 與 failureCount。

受限範圍的讀取為同步，並在回應中直接提供：最多 100 個目標，且具每個目標的限制（例如各 20 筆交易、90 天期間）。本章節文件化的即是這三個查詢。
寫入與大型匯出為非同步（即將推出）：你提交作業、輪詢其狀態，並下載結果。同步讀取中的 hasNextPage/totalCount 會告訴你何時該改用匯出，而不是默默截斷。