Skip to main content
連接器會接受你的供應商請求結構,並回傳你的供應商回應結構。有些內容屬於 Fluz 而非供應商,且在三個禮品卡連接器中皆相同。在切換之前請先閱讀此頁面。

驗證與帳戶範圍

每個連接器都使用你的 Fluz API 金鑰進行 HTTP Basic 驗證:
一把金鑰只對應一個 Fluz 帳戶。使用該金鑰下的每筆訂單都由該帳戶出資,且所有讀取範圍也限定於該帳戶。 你的供應商用來在次帳戶間路由的欄位,例如 Tango 的 accountIdentifier,在此不會用來選擇次帳戶。若你營運多個帳戶,請為每個帳戶申請一把金鑰。

訂單狀態值

訂單上的 status 欄位(InComm 為 OrderStatus)攜帶的是 Fluz 的值,而非你的供應商的:
你的供應商狀態字串不會沿用。以供應商值撰寫的判斷,例如 status === "COMPLETE",不會匹配 COMPLETED。在切換前請更新所有狀態比較。

時間

Tango Card 和 InComm 以同步方式建立訂單,且總是執行至完成。呼叫在購買完成前不會回傳,可能長達 150 秒,因此請將用戶端的讀取逾時設定高於此值。 Runa 預設為非同步。POST /v2/order 會立刻回傳 202 與參考 ID,你之後再讀取該訂單。傳送 X-Execution-Mode: sync 可阻塞至購買完成並取得完整結果,就像 Tango 與 InComm 一樣。

讀取訂單

一筆訂單在購買完成後即可讀取。在此之前讀取參考 ID 會回傳錯誤而非擱置中的狀態,因此請將新建立的非同步訂單上出現的錯誤視為仍在處理,並稍後再讀取。 列表端點會在單一回應中回傳該帳戶最近的 100 筆訂單,最新的在最前。

錯誤回應

錯誤使用 Fluz 的包覆格式,而非你的供應商錯誤結構:
被拒絕的請求與伺服器故障都會回傳 500。請讀取 error 訊息以區分:若為拒絕,表示請求需要更改;若為故障,則可安全重試。

速率限制

每把 API 金鑰與每個來源 IP 各自每秒 20 次請求。超出任一限制將封鎖該金鑰或 IP 10 秒,因此在收到 429 後請至少退避該時長。 每把金鑰的限額為共享,因此多台主機使用同一把金鑰會共用同一預算。

餘額

餘額讀取會回報你的 API 金鑰所屬 Fluz 帳戶的可用餘額。Tango 回傳為 currentBalance,Runa 為 balance;InComm 會在 availableBalance 之外另外回傳 prepaidBalance,其涵蓋禮品卡本身的餘額。 餘額讀取一律限定於你的金鑰所屬帳戶,因此你供應商餘額呼叫中的辨識子不會進一步縮小範圍:Tango 的 :accountId、InComm 的 :programId 與 Runa 的 ?currency= 會被接受,以維持你的既有請求結構相容性。 需要注意的一點:帶任何查詢字串的餘額呼叫會回傳單一物件,而不帶查詢字串的呼叫會回傳包含一個元素的陣列。若你的用戶端會對回應呼叫 .map(),請不要附帶查詢字串。

品牌代碼

三個連接器都會針對同一個 Fluz 目錄解析品牌代碼,無論它們在哪個欄位:Tango 的 utid、InComm 的 Sku、Runa 的 items[].products.value。你的供應商產品代碼不會沿用,且 Fluz 無法識別的代碼會回傳錯誤。
在切換前,請將你的完整品牌清單對照 Fluz 目錄進行映射。解析到錯誤 Fluz 方案的代碼會在沒有錯誤的情況下交付錯誤的卡片。

請求限制

連接器會接受你的供應商請求結構,但部分值是固定的。違反以下任一項的請求會被拒絕。 Fluz 會直接在訂單回應中回傳禮品卡憑證,這也是為何上述電子郵件旗標必須關閉:寄送給收件人的流程仍由你掌控。