> ## 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.

# Runa

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

## 原生 Runa API 與 Fluz API Adapter 比較

### Base URL

* **原生 Runa API：** [https://playground.runa.io](https://playground.runa.io)
* **Fluz API Adapter：**
  * Staging： [https://api-adapter.staging.fluzapp.com/runa](https://api-adapter.staging.fluzapp.com/runa)

### 驗證機制

**Runa Base URL**

* 透過 API Key Authentication，使用 `X-Api-Key` 標頭

```text theme={null}
X-Api-Key: XXxxq8Vl.5fx~8r_dS7LGJ*HdEeGd^P9pQwi4cV_7
```

### Fluz API Adapter

* 使用 Basic Authentication，於 `Authorization` 標頭中提供（與所有 vendor 整合相同）。

```text theme={null}
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`                | 取得所有訂單               |
| Create Order                  | `GET /v2/order`                | `GET /v2/order`                | 建立新的禮品卡訂單（以背景作業方式處理） |
| Get Balance (All Accounts)    | `GET /v2/balance`              | `GET /v2/balance`              | 取得所有幣別的餘額            |
| Get Balance (Single Currency) | `GET /v2/balance?currency=USD` | `GET /v2/balance?currency=USD` | 取得特定幣別的餘額            |

# 請求範例

## 建立訂單

### 原生 Runa 請求：

```text theme={null}
{
  "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 請求：

```text theme={null}
{
  "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 整合進行的所有購買操作皆以背景作業方式處理。Fluz API Adapter 為 Runa 提供兩種回應模式：

### 同步與非同步處理模式

* **同步模式：**
  * 加上標頭 X-Execution-Mode: sync 以等待背景作業完成
  * API 呼叫會等待直到背景購買作業完成
  * 回應中會返回完整的作業結果
  * 適合測試情境，但複雜購買可能會發生逾時
* **非同步模式（預設）：**
  * 立即回應一個作業參考 ID
  * 購買會在背景持續處理
  * 之後可使用該參考 ID 查詢訂單端點以檢查狀態
  * 建議用於生產環境以避免逾時

兩種模式都依賴背景處理，但在 API 對客戶端的回應方式上有所不同。

### 冪等性支援

原生 Runa API 與 Fluz 的實作皆支援冪等性鍵以防止重複操作：

```text theme={null}
Header: X-Idempotency-Key: your-unique-key
```

## 使用 cURL 的範例

### 範例 1：取得特定訂單

```text theme={null}
# 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>" \
  -H "X-Idempotency-Key: 123"
```

### 範例 2：取得所有訂單

```text theme={null}
# 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：取得所有幣別的餘額

```text theme={null}
# Get Balance for all currencies 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：取得 USD 幣別的餘額

```text theme={null}
# Get Balance for USD currency with Runa via Fluz API Adapter
curl -X GET "https://api-adapter.staging.fluzapp.com/runa/v2/balance?currency=USD" \
  -H "Authorization: Basic <FLUZ-API-Key>"
```

### 範例 5：建立訂單（非同步模式 - 預設）

```text theme={null}
# 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" \
  -H "X-Idempotency-Key: unique-key-123456" \
  -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：建立訂單（同步模式）

```text theme={null}
# 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" \
  -H "X-Idempotency-Key: unique-key-789012" \
  -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"
  }'
```