Skip to main content
如果你已將禮品卡訂單送往 Tango、Runa 或 InComm，要從 Fluz 購買時無須重建任何東西。改 base URL、改認證，其他程式碼全部保留。 這正是**API 轉接器（adapter）**的作用。

​
什麼是 API 轉接器

我們將自己的 API 呼叫對應到他們的。你的供應商所提供的每個操作——建立訂單、檢查訂單、讀取餘額——在 Fluz 這邊都有一個對應的操作，而轉接器位於中間，負責雙向的轉換。 結果是，你先前對 Tango、Runa 或 InComm 打造的整合，現在改為向 Fluz 購買。你的請求格式維持不變，而成功回應也會以你的剖析器原本預期的格式返回。 有兩件事採用 Fluz 的而非你供應商的：錯誤回應與訂單狀態值。兩者皆在連接器行為中說明。 How the Fluz API Adapter works 想像旅行用插頭轉接器。電器本身不變，牆上的插座不變，中間的東西讓兩者匹配。

​
對應是如何運作的

你的請求以供應商的格式傳來。轉接器會把路由與欄位轉換成等價的 Fluz 操作，對 Fluz 供應執行後，再把結果轉回你的程式碼已預期的回應格式。 Request and response mapping through the Fluz API Adapter

​
操作對應

每個連接器頁面都會公布該供應商的完整對應表。以 Tango Card 為例： 路徑與動詞刻意維持不變。轉接器的重點是你的路由層不需要知道有任何改變。

​
欄位對應

仍以 Tango Card 為例：
Tango 與 InComm 會以同步方式回傳完整結果。 呼叫會在購買完成前不返回，可能長達 150 秒，因此請將客戶端的讀取逾時設定在此之上。Runa 預設為非同步：它會立即回傳一個參考 ID，並在完成後由你讀取訂單。若要等待完整結果，請送出 X-Execution-Mode: sync。兩者皆在連接器行為中說明。

​
各供應商請求限制

會接受你供應商的請求格式，如實使用，但有些值是固定的。關閉寄送至收件人電子郵件，訂單為單一收件人且單一商品，且 Runa 訂單必須以 USD 帳戶餘額出資。違反其中任一點的請求將被拒絕。 完整清單見連接器行為。切換前請與你連接器頁面的請求範例一併閱讀。

​
會變更的與不會變更的

品牌識別碼是你唯一必須更改的項目。 轉接器不會把供應商的產品型錄轉換成 Fluz 的。Tango 的 utid 為 U561593 並不等同於 Fluz 的 utid 為 1800FL-US。在切換前先將你的品牌清單對應到 Fluz 型錄，否則訂單會成功但送達錯誤的卡。

​
三個步驟完成切換

1

Change the base URL

將你現有的客戶端指向對應供應商的 Fluz 轉接器主機。以 Tango Card 為例，測試環境為 https://api-adapter.staging.fluzapp.com/tangocard，正式環境為 https://api-adapter.fluzapp.com/tangocard，取代 https://integration-api.tangocard.com/rass。每個連接器頁面皆列出兩個主機。
2

Change the Authorization header

每個連接器都使用 HTTP Basic 認證搭配你的 Fluz API 金鑰：Authorization: Basic <FLUZ-API-Key>。請移除供應商的使用者名稱與密碼。
3

Remap your brand identifiers and send the same calls

將你供應商的產品代碼換成其對應的 Fluz 代碼。其他一切——路徑、動詞、請求本文、回應解析——都維持原樣。

​
可用的連接器

Gift cards

已文件化且可用。 Tango Card、Runa、InComm——皆有公布端點對照與請求範例。

Payment processing

Beta。 Stripe、Worldpay、TSYS、Checkout、Braintree、TabaPay、Finix、Authorize.net、Sola / Cardknox。請聯絡業務以取得搶先體驗與端點細節。

Wallet withdrawals

Beta。 Venmo 與 PayPal。請聯絡業務以取得搶先體驗與端點細節。
禮品卡連接器是已成熟的系列，亦是目前唯一具備作業層級文件者。每個禮品卡連接器頁面都會列出實作的確切操作，並附上其對應的原供應商端點。

​
覆蓋範圍以「操作」為單位

轉接器只實作各連接器頁面所列的那些操作。 每一個都是針對該操作量身打造的轉換，而非通用的全通透代理。
若某個操作未出現在連接器頁面的端點對照表中，表示尚未建置。 開始之前，請列出你現行整合所呼叫的每一個供應商端點，並逐一與連接器頁面比對。若缺少你所依賴的功能，請在開始前告知你的 Fluz 窗口——多數差距只是小幅補強，但仍需排期。

​
連接器與 Fluz GraphQL API 彼此獨立

這點常讓人混淆，值得明白說清楚。Fluz 有兩個截然不同的開發介面，且不共用憑證。
連接器金鑰不是儀表板金鑰。 你在 Fluz 儀表板 Developers 區產生的 API 金鑰無法用於連接器認證，反之亦然。連接器憑證由 Fluz 配置。請聯絡你的 Fluz 代表申請。

​
何時該用連接器，何時不該

Use a connector when

你已有可用的供應商整合在生產環境，想快速取得 Fluz 供應與 Fluz 費率，且不想花費工程週期來切換。上線時間以天計。

Use the Fluz API when

你要完整平台：虛擬卡、錢包與消費帳戶、交易資料、webhooks、現金回饋費率、報價，以及完整商家型錄。這些皆非以供應商外形的介面可觸達。
常見的路徑是先用連接器讓交易量流入，接著在採用舊供應商沒有的能力時，遷移到 Fluz API。

​
取得存取

API 連接器目前以 beta 計畫提供。請聯絡你的 Fluz 代表或寄信給業務，以申請連接器憑證並確認你供應商的操作覆蓋。

​
選擇你的供應商

Tango Card

訂單與帳戶餘額。Basic 認證、同步回應。

Runa

訂單與幣別餘額。支援同步與非同步執行模式。

InComm

即時訂單、訂單明細、卡片擷取與計畫餘額。