> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.

# API 連接器

> 將你已建好的整合指向 Fluz——無需重寫。

如果你已將禮品卡訂單送往 Tango、Runa 或 InComm，要從 Fluz 購買時無須重建任何東西。改 base URL、改認證，其他程式碼全部保留。

這正是\*\*API 轉接器（adapter）\*\*的作用。

## 什麼是 API 轉接器

我們將自己的 API 呼叫對應到他們的。你的供應商所提供的每個操作——建立訂單、檢查訂單、讀取餘額——在 Fluz 這邊都有一個對應的操作，而轉接器位於中間，負責雙向的轉換。

結果是，你先前對 Tango、Runa 或 InComm 打造的整合，現在改為向 Fluz 購買。你的請求格式維持不變，而成功回應也會以你的剖析器原本預期的格式返回。

有兩件事採用 Fluz 的而非你供應商的：錯誤回應與訂單狀態值。兩者皆在[連接器行為](/connector-behaviour)中說明。

![How the Fluz API Adapter works](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMTgwIDY2MCIgd2lkdGg9IjExODAiIGhlaWdodD0iNjYwIiBmb250LWZhbWlseT0iUG9wcGlucywgSW50ZXIsIC1hcHBsZS1zeXN0ZW0sIEJsaW5rTWFjU3lzdGVtRm9udCwgJ1NlZ29lIFVJJywgc2Fucy1zZXJpZiI+CiAgPGRlZnM+CiAgICA8bGluZWFyR3JhZGllbnQgaWQ9ImJyYW5kIiB4MT0iMCIgeTE9IjAiIHgyPSIxIiB5Mj0iMCI+CiAgICAgIDxzdG9wIG9mZnNldD0iMCUiIHN0b3AtY29sb3I9IiM4NEJFRkYiLz4KICAgICAgPHN0b3Agb2Zmc2V0PSIxMDAlIiBzdG9wLWNvbG9yPSIjMjFCQTRDIi8+CiAgICA8L2xpbmVhckdyYWRpZW50PgogICAgPG1hcmtlciBpZD0iYXJyb3ciIHZpZXdCb3g9IjAgMCAxMCAxMCIgcmVmWD0iOSIgcmVmWT0iNSIgbWFya2VyV2lkdGg9IjciIG1hcmtlckhlaWdodD0iNyIgb3JpZW50PSJhdXRvLXN0YXJ0LXJldmVyc2UiPgogICAgICA8cGF0aCBkPSJNIDAgMCBMIDEwIDUgTCAwIDEwIHoiIGZpbGw9IiM5QTk2OEEiLz4KICAgIDwvbWFya2VyPgogICAgPG1hcmtlciBpZD0iYXJyb3dHcmVlbiIgdmlld0JveD0iMCAwIDEwIDEwIiByZWZYPSI5IiByZWZZPSI1IiBtYXJrZXJXaWR0aD0iNyIgbWFya2VySGVpZ2h0PSI3IiBvcmllbnQ9ImF1dG8tc3RhcnQtcmV2ZXJzZSI+CiAgICAgIDxwYXRoIGQ9Ik0gMCAwIEwgMTAgNSBMIDAgMTAgeiIgZmlsbD0iIzBFN0EzNCIvPgogICAgPC9tYXJrZXI+CiAgPC9kZWZzPgoKICA8cmVjdCB3aWR0aD0iMTE4MCIgaGVpZ2h0PSI2NjAiIGZpbGw9IiNGQkY5RjUiLz4KICA8cmVjdCB4PSIwIiB5PSIwIiB3aWR0aD0iMTE4MCIgaGVpZ2h0PSI1IiBmaWxsPSJ1cmwoI2JyYW5kKSIvPgoKICA8IS0tIFRpdGxlIC0tPgogIDx0ZXh0IHg9IjYwIiB5PSI3MiIgZm9udC1zaXplPSIyNyIgZm9udC13ZWlnaHQ9IjYwMCIgZmlsbD0iIzE0MTQwRiI+V2hhdCBhbiBBUEkgYWRhcHRlciBkb2VzPC90ZXh0PgogIDx0ZXh0IHg9IjYwIiB5PSIxMDIiIGZvbnQtc2l6ZT0iMTUiIGZpbGw9IiM2QjZCNjAiPllvdXIgaW50ZWdyYXRpb24ga2VlcHMgc3BlYWtpbmcgdGhlIHZlbmRvciYjODIxNztzIGxhbmd1YWdlLiBGbHV6IGRvZXMgdGhlIHRyYW5zbGF0aW5nLjwvdGV4dD4KCiAgPCEtLSA9PT09PT09PT09PT0gUk9XIDEgOiBUT0RBWSA9PT09PT09PT09PT0gLS0+CiAgPHJlY3QgeD0iNjAiIHk9IjE0MCIgd2lkdGg9IjEwNjAiIGhlaWdodD0iMTg4IiByeD0iMTQiIGZpbGw9IiNGRkZGRkYiIHN0cm9rZT0iI0U3RTNEOSIgc3Ryb2tlLXdpZHRoPSIxIi8+CiAgPHRleHQgeD0iODgiIHk9IjE3NCIgZm9udC1zaXplPSIxMiIgZm9udC13ZWlnaHQ9IjYwMCIgZmlsbD0iIzlBOTY4QSIgbGV0dGVyLXNwYWNpbmc9IjEuNiI+VE9EQVk8L3RleHQ+CgogIDwhLS0gYXBwIC0tPgogIDxyZWN0IHg9Ijg4IiB5PSIxOTYiIHdpZHRoPSIyNTIiIGhlaWdodD0iOTQiIHJ4PSIxMCIgZmlsbD0iI0Y0RjFFQSIgc3Ryb2tlPSIjREREOENDIiBzdHJva2Utd2lkdGg9IjEiLz4KICA8dGV4dCB4PSIyMTQiIHk9IjIzOCIgZm9udC1zaXplPSIxNiIgZm9udC13ZWlnaHQ9IjYwMCIgZmlsbD0iIzE0MTQwRiIgdGV4dC1hbmNob3I9Im1pZGRsZSI+WW91ciBhcHBsaWNhdGlvbjwvdGV4dD4KICA8dGV4dCB4PSIyMTQiIHk9IjI2MiIgZm9udC1zaXplPSIxMyIgZmlsbD0iIzZCNkI2MCIgdGV4dC1hbmNob3I9Im1pZGRsZSI+QWxyZWFkeSBidWlsdC4gQWxyZWFkeSBsaXZlLjwvdGV4dD4KCiAgPGxpbmUgeDE9IjM0OCIgeTE9IjI0MyIgeDI9IjQyNCIgeTI9IjI0MyIgc3Ryb2tlPSIjOUE5NjhBIiBzdHJva2Utd2lkdGg9IjEuNiIgbWFya2VyLWVuZD0idXJsKCNhcnJvdykiLz4KICA8dGV4dCB4PSIzODYiIHk9IjIzMCIgZm9udC1zaXplPSIxMS41IiBmaWxsPSIjOUE5NjhBIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIj52ZW5kb3Itc2hhcGVkPC90ZXh0PgogIDx0ZXh0IHg9IjM4NiIgeT0iMjQ1IiBmb250LXNpemU9IjExLjUiIGZpbGw9IiM5QTk2OEEiIHRleHQtYW5jaG9yPSJtaWRkbGUiPnJlcXVlc3Q8L3RleHQ+CgogIDwhLS0gdmVuZG9yIGFwaSAtLT4KICA8cmVjdCB4PSI0MzIiIHk9IjE5NiIgd2lkdGg9IjI1MiIgaGVpZ2h0PSI5NCIgcng9IjEwIiBmaWxsPSIjRjRGMUVBIiBzdHJva2U9IiNEREQ4Q0MiIHN0cm9rZS13aWR0aD0iMSIvPgogIDx0ZXh0IHg9IjU1OCIgeT0iMjM4IiBmb250LXNpemU9IjE2IiBmb250LXdlaWdodD0iNjAwIiBmaWxsPSIjMTQxNDBGIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIj5UYW5nbyAvIFJ1bmEgLyBJbkNvbW08L3RleHQ+CiAgPHRleHQgeD0iNTU4IiB5PSIyNjIiIGZvbnQtc2l6ZT0iMTMiIGZpbGw9IiM2QjZCNjAiIHRleHQtYW5jaG9yPSJtaWRkbGUiPlRoZWlyIEFQSTwvdGV4dD4KCiAgPGxpbmUgeDE9IjY5MiIgeTE9IjI0MyIgeDI9Ijc2OCIgeTI9IjI0MyIgc3Ryb2tlPSIjOUE5NjhBIiBzdHJva2Utd2lkdGg9IjEuNiIgbWFya2VyLWVuZD0idXJsKCNhcnJvdykiLz4KCiAgPCEtLSBzdXBwbHkgLS0+CiAgPHJlY3QgeD0iNzc2IiB5PSIxOTYiIHdpZHRoPSIyNTIiIGhlaWdodD0iOTQiIHJ4PSIxMCIgZmlsbD0iI0Y0RjFFQSIgc3Ryb2tlPSIjREREOENDIiBzdHJva2Utd2lkdGg9IjEiLz4KICA8dGV4dCB4PSI5MDIiIHk9IjIzOCIgZm9udC1zaXplPSIxNiIgZm9udC13ZWlnaHQ9IjYwMCIgZmlsbD0iIzE0MTQwRiIgdGV4dC1hbmNob3I9Im1pZGRsZSI+VGhlaXIgZ2lmdCBjYXJkIHN1cHBseTwvdGV4dD4KICA8dGV4dCB4PSI5MDIiIHk9IjI2MiIgZm9udC1zaXplPSIxMyIgZmlsbD0iIzZCNkI2MCIgdGV4dC1hbmNob3I9Im1pZGRsZSI+VGhlaXIgcmF0ZXM8L3RleHQ+CgogIDwhLS0gPT09PT09PT09PT09IFJPVyAyIDogV0lUSCBGTFVaID09PT09PT09PT09PSAtLT4KICA8cmVjdCB4PSI2MCIgeT0iMzYwIiB3aWR0aD0iMTA2MCIgaGVpZ2h0PSIxODgiIHJ4PSIxNCIgZmlsbD0iI0ZGRkZGRiIgc3Ryb2tlPSIjQzhFOEQyIiBzdHJva2Utd2lkdGg9IjEuNSIvPgogIDxyZWN0IHg9IjYwIiB5PSIzNjAiIHdpZHRoPSIxMDYwIiBoZWlnaHQ9IjQiIHJ4PSIyIiBmaWxsPSJ1cmwoI2JyYW5kKSIvPgogIDx0ZXh0IHg9Ijg4IiB5PSIzOTQiIGZvbnQtc2l6ZT0iMTIiIGZvbnQtd2VpZ2h0PSI2MDAiIGZpbGw9IiMwRTdBMzQiIGxldHRlci1zcGFjaW5nPSIxLjYiPldJVEggVEhFIEZMVVogQVBJIEFEQVBURVI8L3RleHQ+CgogIDwhLS0gYXBwICh1bmNoYW5nZWQpIC0tPgogIDxyZWN0IHg9Ijg4IiB5PSI0MTYiIHdpZHRoPSIyNTIiIGhlaWdodD0iOTQiIHJ4PSIxMCIgZmlsbD0iI0Y0RjFFQSIgc3Ryb2tlPSIjREREOENDIiBzdHJva2Utd2lkdGg9IjEiLz4KICA8dGV4dCB4PSIyMTQiIHk9IjQ1MiIgZm9udC1zaXplPSIxNiIgZm9udC13ZWlnaHQ9IjYwMCIgZmlsbD0iIzE0MTQwRiIgdGV4dC1hbmNob3I9Im1pZGRsZSI+WW91ciBhcHBsaWNhdGlvbjwvdGV4dD4KICA8cmVjdCB4PSIxNjQiIHk9IjQ2NiIgd2lkdGg9IjEwMCIgaGVpZ2h0PSIyNCIgcng9IjEyIiBmaWxsPSIjRTNGNEU4Ii8+CiAgPHRleHQgeD0iMjE0IiB5PSI0ODIiIGZvbnQtc2l6ZT0iMTIiIGZvbnQtd2VpZ2h0PSI2MDAiIGZpbGw9IiMwRTdBMzQiIHRleHQtYW5jaG9yPSJtaWRkbGUiPnVuY2hhbmdlZDwvdGV4dD4KCiAgPGxpbmUgeDE9IjM0OCIgeTE9IjQ2MyIgeDI9IjQyNCIgeTI9IjQ2MyIgc3Ryb2tlPSIjMEU3QTM0IiBzdHJva2Utd2lkdGg9IjEuNiIgbWFya2VyLWVuZD0idXJsKCNhcnJvd0dyZWVuKSIvPgogIDx0ZXh0IHg9IjM4NiIgeT0iNDUwIiBmb250LXNpemU9IjExLjUiIGZpbGw9IiMwRTdBMzQiIHRleHQtYW5jaG9yPSJtaWRkbGUiPnNhbWU8L3RleHQ+CiAgPHRleHQgeD0iMzg2IiB5PSI0NjUiIGZvbnQtc2l6ZT0iMTEuNSIgZmlsbD0iIzBFN0EzNCIgdGV4dC1hbmNob3I9Im1pZGRsZSI+cmVxdWVzdDwvdGV4dD4KCiAgPCEtLSBhZGFwdGVyIC0tPgogIDxyZWN0IHg9IjQzMiIgeT0iNDE2IiB3aWR0aD0iMjUyIiBoZWlnaHQ9Ijk0IiByeD0iMTAiIGZpbGw9IiMwRTdBMzQiLz4KICA8dGV4dCB4PSI1NTgiIHk9IjQ1MiIgZm9udC1zaXplPSIxNiIgZm9udC13ZWlnaHQ9IjYwMCIgZmlsbD0iI0ZGRkZGRiIgdGV4dC1hbmNob3I9Im1pZGRsZSI+Rmx1eiBBUEkgQWRhcHRlcjwvdGV4dD4KICA8dGV4dCB4PSI1NTgiIHk9IjQ3NiIgZm9udC1zaXplPSIxMyIgZmlsbD0iI0I3RThDNiIgdGV4dC1hbmNob3I9Im1pZGRsZSI+dHJhbnNsYXRlcyBpbiwgdHJhbnNsYXRlcyBiYWNrPC90ZXh0PgoKICA8bGluZSB4MT0iNjkyIiB5MT0iNDYzIiB4Mj0iNzY4IiB5Mj0iNDYzIiBzdHJva2U9IiMwRTdBMzQiIHN0cm9rZS13aWR0aD0iMS42IiBtYXJrZXItZW5kPSJ1cmwoI2Fycm93R3JlZW4pIi8+CgogIDwhLS0gZmx1eiBzdXBwbHkgLS0+CiAgPHJlY3QgeD0iNzc2IiB5PSI0MTYiIHdpZHRoPSIyNTIiIGhlaWdodD0iOTQiIHJ4PSIxMCIgZmlsbD0iI0Y0RjFFQSIgc3Ryb2tlPSIjREREOENDIiBzdHJva2Utd2lkdGg9IjEiLz4KICA8dGV4dCB4PSI5MDIiIHk9IjQ1MiIgZm9udC1zaXplPSIxNiIgZm9udC13ZWlnaHQ9IjYwMCIgZmlsbD0iIzE0MTQwRiIgdGV4dC1hbmNob3I9Im1pZGRsZSI+Rmx1eiBnaWZ0IGNhcmQgc3VwcGx5PC90ZXh0PgogIDx0ZXh0IHg9IjkwMiIgeT0iNDc2IiBmb250LXNpemU9IjEzIiBmaWxsPSIjNkI2QjYwIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIj5GbHV6IHJhdGVzPC90ZXh0PgoKICA8IS0tID09PT09PT09PT09PSBGT09URVI6IHdoYXQgeW91IGNoYW5nZSA9PT09PT09PT09PT0gLS0+CiAgPHRleHQgeD0iNjAiIHk9IjU5NiIgZm9udC1zaXplPSIxMyIgZm9udC13ZWlnaHQ9IjYwMCIgZmlsbD0iIzlBOTY4QSIgbGV0dGVyLXNwYWNpbmc9IjEuMiI+QUxMIFlPVSBDSEFOR0U8L3RleHQ+CgogIDxyZWN0IHg9IjYwIiB5PSI2MDgiIHdpZHRoPSIzMzYiIGhlaWdodD0iMzYiIHJ4PSI4IiBmaWxsPSIjRkZGRkZGIiBzdHJva2U9IiNFN0UzRDkiLz4KICA8dGV4dCB4PSI3OCIgeT0iNjMxIiBmb250LXNpemU9IjEzLjUiIGZpbGw9IiMxNDE0MEYiPjx0c3BhbiBmb250LXdlaWdodD0iNjAwIj4xLjwvdHNwYW4+ICBUaGUgYmFzZSBVUkw8L3RleHQ+CgogIDxyZWN0IHg9IjQyMiIgeT0iNjA4IiB3aWR0aD0iMzM2IiBoZWlnaHQ9IjM2IiByeD0iOCIgZmlsbD0iI0ZGRkZGRiIgc3Ryb2tlPSIjRTdFM0Q5Ii8+CiAgPHRleHQgeD0iNDQwIiB5PSI2MzEiIGZvbnQtc2l6ZT0iMTMuNSIgZmlsbD0iIzE0MTQwRiI+PHRzcGFuIGZvbnQtd2VpZ2h0PSI2MDAiPjIuPC90c3Bhbj4gIFRoZSBBdXRob3JpemF0aW9uIGhlYWRlcjwvdGV4dD4KCiAgPHJlY3QgeD0iNzg0IiB5PSI2MDgiIHdpZHRoPSIzMzYiIGhlaWdodD0iMzYiIHJ4PSI4IiBmaWxsPSIjRkZGRkZGIiBzdHJva2U9IiNFN0UzRDkiLz4KICA8dGV4dCB4PSI4MDIiIHk9IjYzMSIgZm9udC1zaXplPSIxMy41IiBmaWxsPSIjMTQxNDBGIj48dHNwYW4gZm9udC13ZWlnaHQ9IjYwMCI+My48L3RzcGFuPiAgWW91ciBicmFuZCBpZGVudGlmaWVyczwvdGV4dD4KPC9zdmc+Cg==)

想像旅行用插頭轉接器。電器本身不變，牆上的插座不變，中間的東西讓兩者匹配。

## 對應是如何運作的

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

<img src="https://mintcdn.com/fluz-dd3e0eaa/ntRBNWQmiqBrvQt4/images/fluz-api-adapter-technical.svg?fit=max&auto=format&n=ntRBNWQmiqBrvQt4&q=85&s=75f36d0c5db48f78ea6ee25b2df40848" alt="Request and response mapping through the Fluz API Adapter" width="1180" height="800" data-path="images/fluz-api-adapter-technical.svg" />

### 操作對應

每個連接器頁面都會公布該供應商的完整對應表。以 Tango Card 為例：

| Operation                 | 你現有的呼叫                             | Fluz 端點                            |
| :------------------------ | :--------------------------------- | :--------------------------------- |
| Create order              | `POST /v2/orders/`                 | `POST /v2/orders/`                 |
| Get order                 | `GET /v2/orders/:referenceOrderID` | `GET /v2/orders/:referenceOrderID` |
| Get all orders            | `GET /v2/orders`                   | `GET /v2/orders`                   |
| Get balance, all accounts | `GET /v2/accounts`                 | `GET /v2/accounts`                 |
| Get balance, one account  | `GET /v2/accounts/:accountId`      | `GET /v2/accounts/:id`             |

路徑與動詞刻意維持不變。轉接器的重點是你的路由層不需要知道有任何改變。

### 欄位對應

仍以 Tango Card 為例：

| 你請求中的欄位              | Fluz 如何處理                                     |
| :------------------- | :-------------------------------------------- |
| `utid` / brand code  | **以 Fluz 型錄進行解析。請見下方警示**                      |
| `amount`             | 購買金額                                          |
| `externalRefID`      | 會接受。使用回應中的 `referenceOrderID` 進行訂單關聯          |
| `accountIdentifier`  | 訂單將由核發你 API 金鑰的帳戶出資。若你把資金分散到多個帳戶，請為每個帳戶申請一把金鑰 |
| `customerIdentifier` | 為相容你現有的請求格式而保留                                |

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

### 各供應商請求限制

會接受你供應商的請求格式，如實使用，但有些值是固定的。關閉寄送至收件人電子郵件，訂單為單一收件人且單一商品，且 Runa 訂單必須以 USD 帳戶餘額出資。違反其中任一點的請求將被拒絕。

完整清單見[連接器行為](/connector-behaviour)。切換前請與你連接器頁面的請求範例一併閱讀。

## 會變更的與不會變更的

|                                                      | 之前     | 之後                   |
| :--------------------------------------------------- | :----- | :------------------- |
| Request shapes                                       | 供應商的結構 | **不變**               |
| Successful response shapes                           | 供應商的結構 | **不變**               |
| Base URL                                             | 供應商的主機 | Fluz 轉接器主機           |
| Credential                                           | 供應商的金鑰 | 你的 Fluz API 金鑰       |
| Order status values                                  | 供應商的   | **Fluz 的。請更新你的狀態檢查** |
| Error responses                                      | 供應商的結構 | **Fluz 的外層包裝**       |
| Brand identifiers (`utid`, brand slug, product code) | 供應商型錄  | **Fluz 型錄——必須重新對應**  |
| Rates and discounts                                  | 供應商的   | Fluz 的               |
| Supplier of record, invoicing, reconciliation        | 供應商    | Fluz                 |

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

## 三個步驟完成切換

<Steps>
  <Step title="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`。每個連接器頁面皆列出兩個主機。
  </Step>

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

  <Step title="Remap your brand identifiers and send the same calls">
    將你供應商的產品代碼換成其對應的 Fluz 代碼。其他一切——路徑、動詞、請求本文、回應解析——都維持原樣。
  </Step>
</Steps>

## 可用的連接器

<CardGroup cols={3}>
  <Card title="Gift cards" icon="🎁" href="#pick-your-vendor">
    **已文件化且可用。** Tango Card、Runa、InComm——皆有公布端點對照與請求範例。
  </Card>

  <Card title="Payment processing" icon="💳">
    **Beta。** Stripe、Worldpay、TSYS、Checkout、Braintree、TabaPay、Finix、Authorize.net、Sola / Cardknox。請聯絡業務以取得搶先體驗與端點細節。
  </Card>

  <Card title="Wallet withdrawals" icon="💸">
    **Beta。** Venmo 與 PayPal。請聯絡業務以取得搶先體驗與端點細節。
  </Card>
</CardGroup>

禮品卡連接器是已成熟的系列，亦是目前唯一具備作業層級文件者。每個禮品卡連接器頁面都會列出實作的確切操作，並附上其對應的原供應商端點。

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

<Callout icon="📘">
  **轉接器只實作各連接器頁面所列的那些操作。** 每一個都是針對該操作量身打造的轉換，而非通用的全通透代理。
</Callout>

若某個操作未出現在連接器頁面的端點對照表中，表示尚未建置。

開始之前，請列出你現行整合所呼叫的每一個供應商端點，並逐一與連接器頁面比對。若缺少你所依賴的功能，請在開始前告知你的 Fluz 窗口——多數差距只是小幅補強，但仍需排期。

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

這點常讓人混淆，值得明白說清楚。Fluz 有兩個截然不同的開發介面，且不共用憑證。

|                   | API 連接器              | Fluz API                    |
| :---------------- | :------------------- | :-------------------------- |
| Protocol          | REST，外形與供應商一致        | GraphQL                     |
| Authentication    | Basic，使用 Fluz API 金鑰 | Bearer，使用 User Access Token |
| Credential source | 由 Fluz 應要求核發         | 在儀表板的 Developers 區自助產生      |
| Scope             | 你的舊供應商所支援的操作         | 完整的 Fluz 平台                 |

<Callout icon="🔑">
  **連接器金鑰不是儀表板金鑰。** 你在 Fluz 儀表板 Developers 區產生的 API 金鑰無法用於連接器認證，反之亦然。連接器憑證由 Fluz 配置。請聯絡你的 Fluz 代表申請。
</Callout>

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

<CardGroup cols={2}>
  <Card title="Use a connector when" icon="⚡">
    你已有可用的供應商整合在生產環境，想快速取得 Fluz 供應與 Fluz 費率，且不想花費工程週期來切換。上線時間以天計。
  </Card>

  <Card title="Use the Fluz API when" icon="🧩">
    你要完整平台：虛擬卡、錢包與消費帳戶、交易資料、webhooks、現金回饋費率、報價，以及完整商家型錄。這些皆非以供應商外形的介面可觸達。
  </Card>
</CardGroup>

常見的路徑是先用連接器讓交易量流入，接著在採用舊供應商沒有的能力時，遷移到 [Fluz API](/overview)。

## 取得存取

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

## 選擇你的供應商

<CardGroup cols={3}>
  <Card title="Tango Card" icon="🔌" href="/tango">
    訂單與帳戶餘額。Basic 認證、同步回應。
  </Card>

  <Card title="Runa" icon="🔌" href="/runa">
    訂單與幣別餘額。支援同步與非同步執行模式。
  </Card>

  <Card title="InComm" icon="🔌" href="/in-comm">
    即時訂單、訂單明細、卡片擷取與計畫餘額。
  </Card>
</CardGroup>
