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

This document provides specific details for using the Fluz Gift Card Vendor API Connector with Runa as the vendor.

## Original Runa API vs Fluz API Adapter

### Base URL

* **Original 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)

### Authentication

**Runa Base URL**

* Uses API Key Authentication with the header `X-Api-Key`

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

### Fluz API Adapter

* Uses Basic Authentication with the `Authorization` header (same as all vendor integrations).

```text theme={null}
Authorization: Basic <FLUZ-API-Key>
```

## API Endpoint Comparison

| Operation                     | Runa Endpoint                  | Fluz Endpoint                  | Notes                                                              |
| :---------------------------- | :----------------------------- | :----------------------------- | :----------------------------------------------------------------- |
| Get Order                     | `GET /v2/order/:id`            | `GET /v2/order/:id`            | Retrieve details for a specific order                              |
| Get All Orders                | `GET /v2/order`                | `GET /v2/order`                | Retrieve all orders                                                |
| Create Order                  | `GET /v2/order`                | `GET /v2/order`                | Create a new gift card order (processed as a background operation) |
| Get Balance (All Accounts)    | `GET /v2/balance`              | `GET /v2/balance`              | Get balance for all currencies                                     |
| Get Balance (Single Currency) | `GET /v2/balance?currency=USD` | `GET /v2/balance?currency=USD` | Get balance for a specific currency                                |

# Request Examples

## Create Order

### **Original Runa Request:**

```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 Request:

```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"
}
```

## Background Processing for Runa Orders

All purchase operations through the Runa integration are processed as background operations. The Fluz API Adapter provides two response modes for Runa:

### Synchronous vs Asynchronous Processing Modes

* **Synchronous Mode:**
  * Add header X-Execution-Mode: sync to wait for the background operation to complete
  * The API call will wait until the background purchase operation completes
  * Full operation results are returned in the response
  * Good for testing scenarios but may experience timeouts for complex purchases
* **Asynchronous Mode (Default):**
  * Returns immediately with an operation reference ID
  * The purchase continues processing in the background
  * Check the status later by querying the order endpoint with the reference ID
  * Recommended for production to avoid timeouts

Both modes rely on background processing, but they differ in how the API responds to the client.

### Idempotency Support

Both the original Runa API and Fluz's implementation support idempotency keys to prevent duplicate operations:

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

## Example Usage with cURL

### Example 1: Get a Specific Order

```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"
```

### Example 2: Get All Orders

```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>"
```

### Example 3: Get Balance for All Currencies

```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>"
```

### Example 4: Get Balance for USD Currency

```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>"
```

### Example 5: Create Order with Runa (Asynchronous Mode - Default)

```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"
  }'
```

### Example 6: Create Order with Runa (Synchronous Mode)

```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"
  }'
```