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

本文件提供使用 Fluz Gift Card Vendor API Connector 並以 Incomm 作為供應商時的特定細節。

# 原始 Incomm API 與 Fluz API Adapter

### Base URL

* 原始 Incomm API: [https://app.giftango.com](https://app.giftango.com)
* Fluz API Adapter:
  * 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 Adapter

* 使用帶有 `Authorization` 標頭的 Basic 驗證（與所有供應商整合相同）。

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

## API 端點比較

| Operation         | Incomm Endpoint                                    | Fluz Endpoint                                      | Notes         |
| :---------------- | :------------------------------------------------- | :------------------------------------------------- | :------------ |
| Get Order Details | `GET /orders/:orderId/cards`                       | `GET /orders/:orderId/cards`                       | 取得特定訂單的卡片詳細資料 |
| Get Order         | `GET /orders/:orderId`                             | `GET /orders/:orderId`                             | 取得特定訂單的詳細資料   |
| Create Order      | `POST /orders/immediate`                           | `POST /orders/immediate`                           | 建立新的禮品卡訂單     |
| Get Balance       | `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 Adapter 請求：

```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 Adapter 可能會預設同步回傳完整結果。

<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
        }
      ]
    }
  ]
}'
```