Skip to main content
Fluz 在每個環境中都只公開一個 GraphQL 端點。並沒有依功能區分的基礎 URL,你會將查詢或變更操作傳送到 /api/v1/graphql,權杖則會決定你目前操作的是哪個帳戶。

端點

存取權杖會透過同一個端點的 generateUserAccessToken 變更操作產生,並以你的 API 金鑰授權,詳見身分驗證。

請求剖析

  • query:GraphQL 文件本身。使用具名操作(例如 query GetSpendAccount)可以讓日誌記錄更清楚。
  • variables:具型別的輸入值,讓數值不必寫在查詢字串中。
  • operationName:可省略,適用於一份文件中定義多個操作的情況。

查詢與變更操作

  • **查詢(Query)**為唯讀操作(viewer、wallet、transactions)。
  • **變更操作(Mutation)**會改變狀態(createVirtualCard、purchaseGiftCard、depositCashBalance、createTransfer)。
搬移資金的變更操作會使用請求去重機制,詳見冪等性。

回應格式

只要查詢有執行,就會回傳 HTTP 200,並附上 data / errors 的封裝格式,即使查詢因應用程式錯誤而失敗,也是如此:
失敗時,data 可能為 null,而 errors 會說明發生了什麼問題,其中包含可用於程式判斷的機器可讀 code。詳見錯誤。 變數的值與其宣告型別不符時,同樣會回傳 200,並附上 BAD_USER_INPUT。若請求在執行前就被拒絕,則會收到不同的狀態碼,例如速率限制器回傳的 429,或查詢超出查詢成本限制時的 400。

Introspection 與 Schema

測試環境已啟用 Introspection,因此你可以將 Apollo Studio 或 GraphiQL 等工具指向該端點。正式環境則停用了 Introspection,請改用API 參考文件中已發布的 schema。

下一步

身分驗證

那個 Authorization 標頭中的權杖如何產生,無論是你自己的帳戶或客戶的帳戶。

錯誤

errors 陣列包含哪些內容,以及如何依錯誤代碼進行判斷。