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

# Incomm

本文档提供了在供应商为 Incomm 的情况下，使用 Fluz 礼品卡供应商 API 连接器的具体细节。

# 原生 Incomm API 与 Fluz API 适配器

### 基础 URL

* 原生 Incomm API: [https://app.giftango.com](https://app.giftango.com)
* Fluz API 适配器：
  * Staging: [https://api-adapter.staging.fluzapp.com/incomm](https://api-adapter.staging.fluzapp.com/incomm)

### 原生 Incomm

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

```text theme={null}
Authorization: Bearer <INCOMM-AUTH-TOKEN>
```

要生成 AuthToken，请向 `/auth/token` 端点发送如下请求体：

```text theme={null}
{
  grant_type: 'client_credentials',
  client_id: INCOMM_CLIENT_ID,
  client_secret: INCOMM_SECRET_KEY,
}
```

### Fluz API 适配器

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

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

## API 端点对比

| 操作        | Incomm 端点                                          | Fluz 端点                                            | 备注          |
| :-------- | :------------------------------------------------- | :------------------------------------------------- | :---------- |
| 获取订单礼品卡详情 | `GET /orders/:orderId/cards`                       | `GET /orders/:orderId/cards`                       | 获取指定订单的卡片详情 |
| 获取订单      | `GET /orders/:orderId`                             | `GET /orders/:orderId`                             | 获取指定订单详情    |
| 创建订单      | `POST /orders/immediate`                           | `POST /orders/immediate`                           | 创建新的礼品卡订单   |
| 获取余额      | `GET /programs/programs/:programId/programbalance` | `GET /programs/programs/:programId/programbalance` | 获取所有币种的余额   |

# 请求示例

## 创建订单

### 原生 Incomm 请求：

```text theme={null}
{
  "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 适配器请求：

```text theme={null}
{
  "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 集成进行的所有购买操作都会作为后台操作处理。然而，为了兼容 Incomm API 的行为，Fluz API 适配器默认情况下可能会同步返回完整结果。

<Callout icon="📘">
  **注意：** 即使结果看起来是同步的，所有购买在内部仍会被安排并作为后台操作进行跟踪，以提高可靠性并更好地处理重试。
</Callout>

# 使用 cURL 的示例

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

```text theme={null}
# 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：获取订单详情

```text theme={null}
# 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：获取余额

```text theme={null}
# Get Balance with Incomm via Fluz API Adapter
curl -X GET "https://api-adapter.staging.fluzapp.com/incomm/v1/balance" \
  -H "Authorization: Basic <FLUZ-API-Key>"
```

## 示例 4：创建新订单

```text theme={null}
# Create Order with Incomm via Fluz API Adapter
# Note: This operation runs as a background process but may return complete results
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
        }
      ]
    }
  ]
}'
```