本文件提供使用 Fluz Gift Card Vendor API Adapter，並以 TangoCard 作為供應商時的具體細節。

原生 TangoCard API 與 Fluz API Adapter

Base URL

原生 TangoCard API: https://integration-api.tangocard.com/rass
Fluz API Adapter:
- Staging: https://api-adapter.staging.fluzapp.com/tangocard
- Production: https://api-adapter.fluzapp.com/tangocard

Authentication

原生 TangoCard

使用以使用者名稱與密碼的 Basic Authentication。

Username: <TANGOCARD-USERNAME>
Password: <TANGOCARD-PASSWORD>

Fluz API Adapter

使用 Authorization 標頭的 Basic Authentication（與所有供應商整合相同）。

Authorization: Basic <FLUZ-API-Key>

API 端點比較

Operation	TangoCard Endpoint	Fluz Endpoint	Notes
Get Order	`GET /v2/orders/:referenceOrderID`	`GET /v2/orders/:referenceOrderID`	取得特定訂單的詳細資訊
Get All Orders	`GET /v2/orders/`	`GET /v2/orders`	取得最近 100 筆訂單
Create Order	`POST /v2/orders/`	`POST /v2/orders/`	建立新的禮品卡訂單
Get Balance (All Accounts)	`GET /v2/accounts`	`GET /v2/accounts`	取得所有帳戶的餘額資訊
Get Balance (By Account)	`GET /v2/accounts/:accountId`	`GET /v2/accounts/:id`	取得特定帳戶的餘額

請求範例

建立訂單

原生 TangoCard 請求：

{
  "sendEmail": false,
  "accountIdentifier": "testing1234account",
  "customerIdentifier": "johnr002",
  "utid": "U561593",
  "amount": 50
}

Fluz API Adapter 請求：

{
  "sendEmail": false,
  "accountIdentifier": "testing1234account",
  "customerIdentifier": "johnr002",
  "utid": "1800FL-US",
  "amount": 40,
  "externalRefID": "d8e118ab-732b-4884-8e8a-70746b5f359e"
}

訂單是從發給你 Fluz API 金鑰所屬的帳戶撥款，因此 accountIdentifier 與 customerIdentifier 僅為了與你現有的請求格式相容而保留。請使用回應中的 referenceOrderID 來關聯訂單。

回應時間

建立訂單為同步作業，始終會執行至完成。此呼叫在購買完成前不會回傳，可能需要長達 150 秒，請將用戶端的讀取逾時設定高於此值。

訂單狀態值為 Fluz 的定義，而非 TangoCard 的。 status 欄位會回傳 PENDING、IN_PROGRESS、COMPLETED、FAILED 或 CANCELED。若以 TangoCard 的值如 COMPLETE 進行比對將不會相符。請參閱 Connector behaviour 以取得狀態值、錯誤回應、限制與請求約束。

使用 cURL 的範例

範例 1：取得特定訂單

# Get a specific order with TangoCard via Fluz API Adapter
curl -X GET "https://api-adapter.staging.fluzapp.com/tangocard/v2/orders/72991f5a-b389-404e-98b0-ac5444839ca9" \
  -H "Authorization: Basic <FLUZ-API-Key>"

範例 2：取得所有訂單

# Get all orders with TangoCard via Fluz API Adapter
curl -X GET "https://api-adapter.staging.fluzapp.com/tangocard/v2/orders" \
  -H "Authorization: Basic <FLUZ-API-Key>"

範例 3：取得所有帳戶餘額

# Get Balance for all accounts with TangoCard via Fluz API Adapter
curl -X GET "https://api-adapter.staging.fluzapp.com/tangocard/v2/accounts" \
  -H "Authorization: Basic <FLUZ-API-Key>"

範例 4：取得特定帳戶餘額

# Get Balance for a specific account with TangoCard via Fluz API Adapter
curl -X GET "https://api-adapter.staging.fluzapp.com/tangocard/v2/accounts/testing1234account" \
  -H "Authorization: Basic <FLUZ-API-Key>"

範例 5：建立新訂單

# Create Order with TangoCard via Fluz API Adapter
# Note: this call blocks until the purchase completes. Allow up to 150 seconds.
curl -X POST "https://api-adapter.staging.fluzapp.com/tangocard/v2/orders" \
  -H "Authorization: Basic <FLUZ-API-Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "sendEmail": false,
    "accountIdentifier": "testing1234account",
    "customerIdentifier": "johnr002",
    "utid": "1800FL-US",
    "amount": 40,
    "externalRefID": "d8e118ab-732b-4884-8e8a-70746b5f359e"
  }'

開發者

實用範例

Tango Card

原生 TangoCard API 與 Fluz API Adapter

Base URL

Authentication

原生 TangoCard

Fluz API Adapter

API 端點比較

請求範例

建立訂單

原生 TangoCard 請求：

Fluz API Adapter 請求：

回應時間

使用 cURL 的範例

範例 1：取得特定訂單

範例 2：取得所有訂單

範例 3：取得所有帳戶餘額

範例 4：取得特定帳戶餘額

範例 5：建立新訂單

​原生 TangoCard API 與 Fluz API Adapter

​Base URL

​Authentication

​原生 TangoCard

​Fluz API Adapter

​API 端點比較

​請求範例

​建立訂單

​原生 TangoCard 請求：

​Fluz API Adapter 請求：

​回應時間

​使用 cURL 的範例

​範例 1：取得特定訂單

​範例 2：取得所有訂單

​範例 3：取得所有帳戶餘額

​範例 4：取得特定帳戶餘額

​範例 5：建立新訂單

原生 TangoCard API 與 Fluz API Adapter

Base URL

Authentication

原生 TangoCard

Fluz API Adapter

API 端點比較

請求範例

建立訂單

原生 TangoCard 請求：

Fluz API Adapter 請求：

回應時間

使用 cURL 的範例

範例 1：取得特定訂單

範例 2：取得所有訂單

範例 3：取得所有帳戶餘額

範例 4：取得特定帳戶餘額

範例 5：建立新訂單