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

原生 Runa API 与 Fluz API 适配器

基础 URL

原生 Runa API： https://playground.runa.io
Fluz API 适配器：
- Staging 环境: https://api-adapter.staging.fluzapp.com/runa
- Production 环境: https://api-adapter.fluzapp.com/runa

认证

Runa 基础 URL

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

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

Fluz API 适配器

使用带有 Authorization 请求头的 Basic Authentication（与所有供应商集成相同）。

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`	获取最近的 100 个订单
Create Order	`POST /v2/order`	`POST /v2/order`	创建新的礼品卡订单
Get Balance	`GET /v2/balance`	`GET /v2/balance`	获取你的账户余额。返回一个只有一个元素的数组
Get Balance (single object)	`GET /v2/balance?currency=USD`	`GET /v2/balance?currency=USD`	相同余额，以单个对象而非数组形式返回。余额为 USD

请求示例

创建订单

原生 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"
}

Fluz API 适配器请求：

{
  "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 的保持不变。只有 products.value 中的品牌代码需要变更，因为它会基于 Fluz 目录进行解析。使用响应中的 id 来关联订单。

Runa 订单的后台处理

通过 Runa 集成进行的所有购买操作都作为后台操作处理。Fluz API 适配器为 Runa 提供两种响应模式：

同步与异步处理模式

同步模式：
- 添加请求头 X-Execution-Mode: sync 以等待后台操作完成
- API 调用会一直等待，直到后台购买操作完成
- 响应中返回完整的操作结果
- 适用于测试和低并发流程，因为调用会按购买耗时保持连接
异步模式（默认）：
- 立即返回一个操作引用 ID
- 购买会在后台继续处理
- 之后使用该引用 ID 查询订单端点以检查状态
- 建议用于生产环境，因为无论购买耗时多久，你的调用都会立即返回

两种模式都依赖后台处理，但它们在 API 对客户端的响应方式上有所不同。

订单在其购买完成后才可读取。 在此之前读取引用 ID 会返回错误而非挂起状态，因此将新创建订单上的错误视为“仍在处理”，并稍后再次读取。订单状态值为 Fluz 的：PENDING、IN_PROGRESS、COMPLETED、FAILED、CANCELED。查看连接器行为以了解状态值、错误响应、限制和请求约束。

使用 cURL 的示例

示例 1：获取特定订单

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

示例 2：获取所有订单

# 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：获取余额

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

示例 4：以单个对象形式获取余额

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

示例 5：创建订单（异步模式 - 默认）

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

示例 6：创建订单（同步模式）

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

开发者

实用示例

Runa

原生 Runa API 与 Fluz API 适配器

基础 URL

认证

Fluz API 适配器

API 端点对比

请求示例

创建订单

原生 Runa 请求：

Fluz API 适配器请求：

Runa 订单的后台处理

同步与异步处理模式

使用 cURL 的示例

示例 1：获取特定订单

示例 2：获取所有订单

示例 3：获取余额

示例 4：以单个对象形式获取余额

示例 5：创建订单（异步模式 - 默认）

示例 6：创建订单（同步模式）

​原生 Runa API 与 Fluz API 适配器

​基础 URL

​认证

​Fluz API 适配器

​API 端点对比

​请求示例

​创建订单

​原生 Runa 请求：

​Fluz API 适配器请求：

​Runa 订单的后台处理

​同步与异步处理模式

​使用 cURL 的示例

​示例 1：获取特定订单

​示例 2：获取所有订单

​示例 3：获取余额

​示例 4：以单个对象形式获取余额

​示例 5：创建订单（异步模式 - 默认）

​示例 6：创建订单（同步模式）

原生 Runa API 与 Fluz API 适配器

基础 URL

认证

Fluz API 适配器

API 端点对比

请求示例

创建订单

原生 Runa 请求：

Fluz API 适配器请求：

Runa 订单的后台处理

同步与异步处理模式

使用 cURL 的示例

示例 1：获取特定订单

示例 2：获取所有订单

示例 3：获取余额

示例 4：以单个对象形式获取余额

示例 5：创建订单（异步模式 - 默认）

示例 6：创建订单（同步模式）