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
- Producción: https://api-adapter.fluzapp.com/runa

Autenticación

URL base de Runa

Usa Autenticación por API Key con el header X-Api-Key

X-Api-Key: <RUNA-API-KEY>

Adaptador de API de Fluz

Usa Autenticación Básica con el header Authorization (igual que en 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 las 100 órdenes más recientes
Crear Orden	`POST /v2/order`	`POST /v2/order`	Crea una nueva orden de tarjeta de regalo
Obtener Balance	`GET /v2/balance`	`GET /v2/balance`	Obtén el balance de tu cuenta. Devuelve un arreglo de uno
Obtener Balance (objeto único)	`GET /v2/balance?currency=USD`	`GET /v2/balance?currency=USD`	El mismo balance, devuelto como un solo objeto en lugar de un arreglo. Los balances son en USD

Ejemplos de solicitud

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 con el 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"
}

La forma de la solicitud no cambia con respecto a la de Runa. Solo debe cambiar el código de marca en products.value, porque se resuelve contra el catálogo de Fluz. Correlaciona una orden usando el id de la respuesta.

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 ofrece dos modos de respuesta para Runa:

Modos de procesamiento sincrónico vs asincrónico

Modo sincrónico:
- Agrega el header X-Execution-Mode: sync para esperar a que la operación en segundo plano termine
- 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
- Ideal para pruebas y flujos de bajo volumen, ya que la llamada permanece abierta durante la compra
Modo asincrónico (Predeterminado):
- Devuelve de inmediato con un ID de referencia de la 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, ya que tu llamada regresa inmediatamente sin importar cuánto tarde la compra

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

Una orden es legible una vez que su compra ha finalizado. Leer un ID de referencia antes de eso devuelve un error en lugar de un estado pendiente, así que trata un error en una orden recién creada como aún en proceso y vuelve a leer en breve. Los valores de estado de la orden son los de Fluz: PENDING, IN_PROGRESS, COMPLETED, FAILED, CANCELED. Consulta Comportamiento del conector para valores de estado, respuestas de error, límites y restricciones de solicitud.

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

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 balance

# Get your account balance 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 balance como un objeto único

# Same balance as Example 3, returned as an object rather than an array
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 asincrónico - 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" \
  -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 sincrónico)

# 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" \
  -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 solicitud

Crear Orden

Solicitud original de Runa:

Solicitud con el Adaptador de API de Fluz:

Procesamiento en segundo plano para órdenes de Runa

Modos de procesamiento sincrónico vs asincrónico

Ejemplo de uso con cURL

Ejemplo 1: Obtener una orden específica

Ejemplo 2: Obtener todas las órdenes

Ejemplo 3: Obtener balance

Ejemplo 4: Obtener balance como un objeto único

Ejemplo 5: Crear orden con Runa (Modo asincrónico - Predeterminado)

Ejemplo 6: Crear orden con Runa (Modo sincrónico)

​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 solicitud

​Crear Orden

​Solicitud original de Runa:

​Solicitud con el Adaptador de API de Fluz:

​Procesamiento en segundo plano para órdenes de Runa

​Modos de procesamiento sincrónico vs asincrónico

​Ejemplo de uso con cURL

​Ejemplo 1: Obtener una orden específica

​Ejemplo 2: Obtener todas las órdenes

​Ejemplo 3: Obtener balance

​Ejemplo 4: Obtener balance como un objeto único

​Ejemplo 5: Crear orden con Runa (Modo asincrónico - Predeterminado)

​Ejemplo 6: Crear orden con Runa (Modo sincrónico)

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 solicitud

Crear Orden

Solicitud original de Runa:

Solicitud con el Adaptador de API de Fluz:

Procesamiento en segundo plano para órdenes de Runa

Modos de procesamiento sincrónico vs asincrónico

Ejemplo de uso con cURL

Ejemplo 1: Obtener una orden específica

Ejemplo 2: Obtener todas las órdenes

Ejemplo 3: Obtener balance

Ejemplo 4: Obtener balance como un objeto único

Ejemplo 5: Crear orden con Runa (Modo asincrónico - Predeterminado)

Ejemplo 6: Crear orden con Runa (Modo sincrónico)