本文件提供使用 Fluz Gift Card Vendor API Connector 並以 Runa 作為供應商的特定細節。

原始 Runa API 與 Fluz API Adapter

Base URL

原始 Runa API： https://playground.runa.io
Fluz API Adapter：
- Staging： https://api-adapter.staging.fluzapp.com/runa
- Production： https://api-adapter.fluzapp.com/runa

驗證機制

Runa Base URL

使用帶有標頭 X-Api-Key 的 API Key 驗證

X-Api-Key: <RUNA-API-KEY>

Fluz API Adapter

使用帶有 Authorization 標頭的基本驗證（與所有供應商整合相同）。

Authorization: Basic <FLUZ-API-Key>

API 端點比較

Operation	Runa Endpoint	Fluz Endpoint	Notes
Get Order	`GET /v2/order/:id`	`GET /v2/order/:id`	取得特定訂單的詳細資訊
Get All Orders	`GET /v2/order`	`GET /v2/order`	取得最近 100 筆訂單
Create Order	`POST /v2/order`	`POST /v2/order`	建立新的禮品卡訂單
Get Balance	`GET /v2/balance`	`GET /v2/balance`	取得你的帳戶餘額。回傳含單一元素的陣列
Get Balance (single object)	`GET /v2/balance?currency=USD`	`GET /v2/balance?currency=USD`	相同餘額，但以單一物件而非陣列回傳。餘額為 USD

請求範例

建立訂單

原始 Runa 請求：

{
  "payment_method": {
    "type": "ACCOUNT_BALANCE",
    "currency": "USD"
  },
  "items": [
    {
      "distribution_method": {
        "type": "PAYOUT_LINK"
      },
      "products": {
        "type": "SINGLE",
        "value": "1800FL-US"
      },
      "face_value": 10
    }
  ],
  "description": "string"
}

Fluz API Adapter 請求：

{
  "payment_method": {
    "type": "ACCOUNT_BALANCE",
    "currency": "USD"
  },
  "items": [
    {
      "distribution_method": {
        "type": "PAYOUT_LINK"
      },
      "products": {
        "type": "SINGLE",
        "value": "1800FL-US"
      },
      "face_value": 10
    }
  ],
  "description": "d8e118ab-732b-4884-8e8a-70746b5f359e"
}

請求格式與 Runa 相同。只有 products.value 的品牌代碼需要更改，因為它會對應至 Fluz 的型錄。使用回應中的 id 來關聯訂單。

Runa 訂單的背景處理

透過 Runa 整合進行的所有購買操作皆以背景作業處理。Fluz API Adapter 為 Runa 提供兩種回應模式：

同步與非同步處理模式

同步模式：
- 加上標頭 X-Execution-Mode: sync 以等待背景作業完成
- API 呼叫會等到背景購買作業完成
- 回應中會回傳完整的作業結果
- 適合測試與低量流程，因為呼叫會在購買期間保持連線
非同步模式（預設）：
- 立即回傳作業參考 ID
- 購買會在背景持續處理
- 稍後以該參考 ID 查詢訂單端點以檢查狀態
- 建議用於生產環境，因為無論購買花費多久，你的呼叫都會立即返回

兩種模式皆依賴背景處理，只是 API 對用戶端的回應方式不同。

訂單在購買完成後才可讀取。 在此之前讀取參考 ID 會回傳錯誤而非擱置狀態，因此請將剛建立的訂單出現錯誤視為仍在處理中，並稍後再讀取。訂單狀態值為 Fluz 的定義：PENDING、IN_PROGRESS、COMPLETED、FAILED、CANCELED。請參閱 Connector behaviour 以取得狀態值、錯誤回應、限制與請求約束。

使用 cURL 的範例

範例 1：取得特定訂單

# Get a specific order with Runa via Fluz API Adapter
curl -X GET "https://api-adapter.staging.fluzapp.com/runa/v2/order/df263170-1c87-4e53-baf5-96258c3dd6b9" \
  -H "Authorization: Basic <FLUZ-API-Key>"

範例 2：取得所有訂單

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

範例 3：取得餘額

# Get your account balance with Runa via Fluz API Adapter
curl -X GET "https://api-adapter.staging.fluzapp.com/runa/v2/balance" \
  -H "Authorization: Basic <FLUZ-API-Key>"

範例 4：以單一物件取得餘額

# Same balance as Example 3, returned as an object rather than an array
curl -X GET "https://api-adapter.staging.fluzapp.com/runa/v2/balance?currency=USD" \
  -H "Authorization: Basic <FLUZ-API-Key>"

範例 5：以 Runa 建立訂單（非同步模式－預設）

# Create Order with Runa via Fluz API Adapter (Asynchronous mode - default)
# This will return quickly with a reference ID while processing continues in the background
curl -X POST "https://api-adapter.staging.fluzapp.com/runa/v2/order" \
  -H "Authorization: Basic <FLUZ-API-Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": {
      "type": "ACCOUNT_BALANCE",
      "currency": "USD"
    },
    "items": [
      {
        "distribution_method": {
          "type": "PAYOUT_LINK"
        },
        "products": {
          "type": "SINGLE",
          "value": "1800FL-US"
        },
        "face_value": 10
      }
    ],
    "description": "d8e118ab-732b-4884-8e8a-70746b5f359e"
  }'

範例 6：以 Runa 建立訂單（同步模式）

# Create Order with Runa via Fluz API Adapter (Synchronous mode)
# This will wait for the background process to complete before responding
curl -X POST "https://api-adapter.staging.fluzapp.com/runa/v2/order" \
  -H "Authorization: Basic <FLUZ-API-Key>" \
  -H "Content-Type: application/json" \
  -H "X-Execution-Mode: sync" \
  -d '{
    "payment_method": {
      "type": "ACCOUNT_BALANCE",
      "currency": "USD"
    },
    "items": [
      {
        "distribution_method": {
          "type": "PAYOUT_LINK"
        },
        "products": {
          "type": "SINGLE",
          "value": "1800FL-US"
        },
        "face_value": 10
      }
    ],
    "description": "d8e118ab-732b-4884-8e8a-70746b5f359e"
  }'

開發者

實用範例

Runa

原始 Runa API 與 Fluz API Adapter

Base URL

驗證機制

Fluz API Adapter

API 端點比較

請求範例

建立訂單

原始 Runa 請求：

Fluz API Adapter 請求：

Runa 訂單的背景處理

同步與非同步處理模式

使用 cURL 的範例

範例 1：取得特定訂單

範例 2：取得所有訂單

範例 3：取得餘額

範例 4：以單一物件取得餘額

範例 5：以 Runa 建立訂單（非同步模式－預設）

範例 6：以 Runa 建立訂單（同步模式）

​原始 Runa API 與 Fluz API Adapter

​Base URL

​驗證機制

​Fluz API Adapter

​API 端點比較

​請求範例

​建立訂單

​原始 Runa 請求：

​Fluz API Adapter 請求：

​Runa 訂單的背景處理

​同步與非同步處理模式

​使用 cURL 的範例

​範例 1：取得特定訂單

​範例 2：取得所有訂單

​範例 3：取得餘額

​範例 4：以單一物件取得餘額

​範例 5：以 Runa 建立訂單（非同步模式－預設）

​範例 6：以 Runa 建立訂單（同步模式）

原始 Runa API 與 Fluz API Adapter

Base URL

驗證機制

Fluz API Adapter

API 端點比較

請求範例

建立訂單

原始 Runa 請求：

Fluz API Adapter 請求：

Runa 訂單的背景處理

同步與非同步處理模式

使用 cURL 的範例

範例 1：取得特定訂單

範例 2：取得所有訂單

範例 3：取得餘額

範例 4：以單一物件取得餘額

範例 5：以 Runa 建立訂單（非同步模式－預設）

範例 6：以 Runa 建立訂單（同步模式）