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
Adaptador de API de Fluz:
- Staging: 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

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

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:

{
  "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:

{
  "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:

Header: X-Idempotency-Key: your-unique-key

Ejemplo de uso con cURL

Ejemplo 1: Obtener una orden específica

# 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

# 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

# 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

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

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

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

Desarrolladores

Recetas

Runa

API original de Runa vs Adaptador de API de Fluz

URL base

Autenticación

Adaptador de API de Fluz

Comparación de endpoints de API

Ejemplos de solicitudes

Crear orden

Solicitud original de Runa:

Solicitud del Adaptador de API de Fluz:

Procesamiento en segundo plano para órdenes de Runa

Modos de procesamiento síncrono vs asíncrono

Compatibilidad con idempotencia

Ejemplo de uso con cURL

Ejemplo 1: Obtener una orden específica

Ejemplo 2: Obtener todas las órdenes

Ejemplo 3: Obtener saldo para todas las monedas

Ejemplo 4: Obtener saldo para la moneda USD

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

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

​API original de Runa vs Adaptador de API de Fluz

​URL base

​Autenticación

​Adaptador de API de Fluz

​Comparación de endpoints de API

​Ejemplos de solicitudes

​Crear orden

​Solicitud original de Runa:

​Solicitud del Adaptador de API de Fluz:

​Procesamiento en segundo plano para órdenes de Runa

​Modos de procesamiento síncrono vs asíncrono

​Compatibilidad con idempotencia

​Ejemplo de uso con cURL

​Ejemplo 1: Obtener una orden específica

​Ejemplo 2: Obtener todas las órdenes

​Ejemplo 3: Obtener saldo para todas las monedas

​Ejemplo 4: Obtener saldo para la moneda USD

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

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

API original de Runa vs Adaptador de API de Fluz

URL base

Autenticación

Adaptador de API de Fluz

Comparación de endpoints de API

Ejemplos de solicitudes

Crear orden

Solicitud original de Runa:

Solicitud del Adaptador de API de Fluz:

Procesamiento en segundo plano para órdenes de Runa

Modos de procesamiento síncrono vs asíncrono

Compatibilidad con idempotencia

Ejemplo de uso con cURL

Ejemplo 1: Obtener una orden específica

Ejemplo 2: Obtener todas las órdenes

Ejemplo 3: Obtener saldo para todas las monedas

Ejemplo 4: Obtener saldo para la moneda USD

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

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