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

本文档提供了在将 Runa 作为供应商时，使用 Fluz 礼品卡供应商 API 连接器的具体细节。

## 原始 Runa API 与 Fluz API 适配器

### 基础 URL

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

### 认证

**Runa 基础 URL**

* 使用带有 `X-Api-Key` 请求头的 API Key 认证

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

### Fluz API 适配器

* 使用带有 `Authorization` 请求头的基本认证（与所有供应商集成相同）。

```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 适配器请求：

```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 适配器为 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"
  }'
```