本文档提供了将 Fluz 礼品卡供应商 API 连接器与 Incomm 作为供应商一起使用的具体细节。

原始 Incomm API 与 Fluz API 适配器

基础 URL

原始 Incomm API: https://app.giftango.com
Fluz API 适配器：
- Staging: https://api-adapter.staging.fluzapp.com/incomm
- Production: https://api-adapter.fluzapp.com/incomm

原始 Incomm

使用 Authorization 头中的 Bearer 身份验证——需要先生成授权令牌。

Authorization: Bearer <INCOMM-AUTH-TOKEN>

要生成 AuthToken，请向 /auth/token 端点发送带有以下请求体的请求：

{
  grant_type: 'client_credentials',
  client_id: INCOMM_CLIENT_ID,
  client_secret: INCOMM_SECRET_KEY,
}

Fluz API 适配器

使用 Authorization 头中的 Basic 身份验证（与所有供应商集成相同）。

Authorization: Basic <FLUZ-API-Key>

API 端点对比

Operation	Incomm Endpoint	Fluz Endpoint	Notes
Get Order Details	`GET /orders/:orderId/cards`	`GET /v1/orders/:orderId/cards`	检索特定订单的卡片详情
Get Order	`GET /orders/:orderId`	`GET /v1/orders/:orderId`	检索特定订单的详细信息
Create Order	`POST /orders/immediate`	`POST /v1/orders/immediate`	创建新的礼品卡订单
Get Balance	`GET /programs/programs/:programId/programbalance`	`GET /v1/programs/programs/:programId/programbalance`	获取你的账户余额。限定于颁发给你密钥的账户

请求示例

创建订单

原始 Incomm 请求：

{
  "PurchaseOrderNumber": "cddabd6d-1f7a-483d-8126-8bc676f7bd63",
  "CustomerOrderId": "cddabd6d-1f7a-483d-8126-8bc676f7bd63",
  "Recipients": [
    {
      "FirstName": "testFirstName",
      "LastName": "testLastName",
      "EmailAddress": "testEmail@test.com",
      "DeliverEmail": false,
      "Products": [
        {
          "Sku": "VUSA-D-2500-00",
          "Quantity": 1,
          "Value": 25
        }
      ]
    }
  ]
}

Fluz API 适配器请求：

{
  "PurchaseOrderNumber": "cddabd6d-1f7a-483d-8126-8bc676f7bd63",
  "CustomerOrderId": "cddabd6d-1f7a-483d-8126-8bc676f7bd63",
  "Recipients": [
    {
      "FirstName": "testFirstName",
      "LastName": "testLastName",
      "EmailAddress": "testEmail@test.com",
      "DeliverEmail": false,
      "Products": [
        {
          "Sku": "VUSA-D-2500-00",
          "Quantity": 1,
          "Value": 25
        }
      ]
    }
  ]
}

一个订单涵盖一位收件人和一个产品。DeliverEmail 不能为 true，因为 Fluz 会在订单响应中返回礼品卡凭据，而不是向收件人发送电子邮件，从而使交付受你控制。PurchaseOrderNumber 和 CustomerOrderId 保留用于与你现有的请求结构兼容；请使用 Fluz 返回的标识符来关联订单。

响应时机

创建订单是同步的，始终运行至完成。调用在购买完成之前不会返回，可能需要长达 150 秒，因此请将你的客户端读取超时时间设置在此之上。

订单状态值是 Fluz 的，而非 Incomm 的。 OrderStatus 返回 PENDING、IN_PROGRESS、COMPLETED、FAILED 或 CANCELED。参见 Connector behaviour 了解状态值、错误响应、限制以及请求约束。

使用 cURL 的示例

示例 1：获取包含礼品卡的特定订单

# Get gift cards from order with Incomm via Fluz API Adapter
curl -X GET "https://api-adapter.staging.fluzapp.com/incomm/v1/orders/353a4151-2d51-48b6-81c9-90fd6815f12b/cards" \
  -H "Authorization: Basic <FLUZ-API-Key>"

示例 2：获取订单详情

# Get order details with Incomm via Fluz API Adapter
curl -X GET "https://api-adapter.staging.fluzapp.com/incomm/v1/orders/353a4151-2d51-48b6-81c9-90fd6815f12b" \
  -H "Authorization: Basic <FLUZ-API-Key>"

示例 3：获取余额

# Get Balance with Incomm via Fluz API Adapter
# The balance is scoped to your key's account, so any :programId value works
curl -X GET "https://api-adapter.staging.fluzapp.com/incomm/v1/programs/programs/0/programbalance" \
  -H "Authorization: Basic <FLUZ-API-Key>"

示例 4：创建新订单

# Create Order with Incomm via Fluz API Adapter
# Note: this call blocks until the purchase completes. Allow up to 150 seconds.
curl -X POST "https://api-adapter.staging.fluzapp.com/incomm/v1/orders/immediate" \
  -H "Authorization: Basic <FLUZ-API-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "PurchaseOrderNumber": "cddabd6d-1f7a-483d-8126-8bc676f7bd63",
  "CustomerOrderId": "cddabd6d-1f7a-483d-8126-8bc676f7bd63",
  "Recipients": [
    {
      "FirstName": "testFirstName",
      "LastName": "testLastName",
      "EmailAddress": "testEmail@test.com",
      "DeliverEmail": false,
      "Products": [
        {
          "Sku": "VUSA-D-2500-00",
          "Quantity": 1,
          "Value": 25
        }
      ]
    }
  ]
}'

开发者

实用示例

Incomm

原始 Incomm API 与 Fluz API 适配器

基础 URL

原始 Incomm

Fluz API 适配器

API 端点对比

请求示例

创建订单

原始 Incomm 请求：

Fluz API 适配器请求：

响应时机

使用 cURL 的示例

示例 1：获取包含礼品卡的特定订单

示例 2：获取订单详情

示例 3：获取余额

示例 4：创建新订单

​原始 Incomm API 与 Fluz API 适配器

​基础 URL

​原始 Incomm

​Fluz API 适配器

​API 端点对比

​请求示例

​创建订单

​原始 Incomm 请求：

​Fluz API 适配器请求：

​响应时机

​使用 cURL 的示例

​示例 1：获取包含礼品卡的特定订单

​示例 2：获取订单详情

​示例 3：获取余额

​示例 4：创建新订单

原始 Incomm API 与 Fluz API 适配器

基础 URL

原始 Incomm

Fluz API 适配器

API 端点对比

请求示例

创建订单

原始 Incomm 请求：

Fluz API 适配器请求：

响应时机

使用 cURL 的示例

示例 1：获取包含礼品卡的特定订单

示例 2：获取订单详情

示例 3：获取余额

示例 4：创建新订单