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

Este documento proporciona detalles específicos para usar el Conector de API de Proveedor de Tarjetas de Regalo de Fluz con Runa como proveedor.

## API original de Runa vs Adaptador de API de Fluz

### URL base

* **API original de Runa:** [https://playground.runa.io](https://playground.runa.io)
* **Adaptador de API de Fluz:**
  * Staging: [https://api-adapter.staging.fluzapp.com/runa](https://api-adapter.staging.fluzapp.com/runa)

### Autenticación

**URL base de Runa**

* Usa autenticación con API Key mediante el header `X-Api-Key`

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

### Adaptador de API de Fluz

* Usa Autenticación Basic con el header `Authorization` (igual que todas las integraciones de proveedores).

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

## Comparación de endpoints de API

| Operación                         | Endpoint de Runa               | Endpoint de Fluz               | Notas                                                                                     |
| :-------------------------------- | :----------------------------- | :----------------------------- | :---------------------------------------------------------------------------------------- |
| Obtener orden                     | `GET /v2/order/:id`            | `GET /v2/order/:id`            | Recupera los detalles de una orden específica                                             |
| Obtener todas las órdenes         | `GET /v2/order`                | `GET /v2/order`                | Recupera todas las órdenes                                                                |
| Crear orden                       | `GET /v2/order`                | `GET /v2/order`                | Crea una nueva orden de tarjeta de regalo (procesada como una operación en segundo plano) |
| Obtener saldo (todas las cuentas) | `GET /v2/balance`              | `GET /v2/balance`              | Obtiene el saldo para todas las monedas                                                   |
| Obtener saldo (moneda única)      | `GET /v2/balance?currency=USD` | `GET /v2/balance?currency=USD` | Obtiene el saldo para una moneda específica                                               |

# Ejemplos de solicitudes

## Crear orden

### **Solicitud original de 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"
}
```

### Solicitud del Adaptador de API de Fluz:

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

## Procesamiento en segundo plano para órdenes de Runa

Todas las operaciones de compra a través de la integración con Runa se procesan como operaciones en segundo plano. El Adaptador de API de Fluz proporciona dos modos de respuesta para Runa:

### Modos de procesamiento síncrono vs asíncrono

* **Modo síncrono:**
  * Agrega el header X-Execution-Mode: sync para esperar a que la operación en segundo plano se complete
  * La llamada a la API esperará hasta que la operación de compra en segundo plano se complete
  * Los resultados completos de la operación se devuelven en la respuesta
  * Útil para escenarios de prueba, pero puede experimentar timeouts en compras complejas
* **Modo asíncrono (predeterminado):**
  * Devuelve inmediatamente con un ID de referencia de operación
  * La compra continúa procesándose en segundo plano
  * Revisa el estado más tarde consultando el endpoint de orden con el ID de referencia
  * Recomendado para producción para evitar timeouts

Ambos modos dependen del procesamiento en segundo plano, pero difieren en cómo responde la API al cliente.

### Compatibilidad con idempotencia

Tanto la API original de Runa como la implementación de Fluz admiten keys de idempotencia para evitar operaciones duplicadas:

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

## Ejemplo de uso con cURL

### Ejemplo 1: Obtener una orden específica

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

### Ejemplo 2: Obtener todas las órdenes

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

### Ejemplo 3: Obtener saldo para todas las monedas

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

### Ejemplo 4: Obtener saldo para la moneda 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>"
```

### Ejemplo 5: Crear orden con Runa (modo asíncrono - predeterminado)

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

### Ejemplo 6: Crear orden con Runa (modo síncrono)

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