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

原始 Incomm API 與 Fluz API Adapter

Base URL

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

原始 Incomm

使用 Authorization 標頭的 Bearer Authentication —— 需先產生授權權杖。

Authorization: Bearer <INCOMM-AUTH-TOKEN>

要產生 AuthToken，請以以下內容呼叫 /auth/token 端點：

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

Fluz API Adapter

使用 Authorization 標頭的 Basic Authentication（與所有供應商整合同步）。

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 Adapter 請求：

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

Base URL

原始 Incomm

Fluz API Adapter

API 端點比較

請求範例

建立訂單

原始 Incomm 請求：

Fluz API Adapter 請求：

回應時間

使用 cURL 的範例

範例 1：取得含禮品卡的特定訂單

範例 2：取得訂單詳細資料

範例 3：取得餘額

範例 4：建立新訂單

​原始 Incomm API 與 Fluz API Adapter

​Base URL

​原始 Incomm

​Fluz API Adapter

​API 端點比較

​請求範例

​建立訂單

​原始 Incomm 請求：

​Fluz API Adapter 請求：

​回應時間

​使用 cURL 的範例

​範例 1：取得含禮品卡的特定訂單

​範例 2：取得訂單詳細資料

​範例 3：取得餘額

​範例 4：建立新訂單

原始 Incomm API 與 Fluz API Adapter

Base URL

原始 Incomm

Fluz API Adapter

API 端點比較

請求範例

建立訂單

原始 Incomm 請求：

Fluz API Adapter 請求：

回應時間

使用 cURL 的範例

範例 1：取得含禮品卡的特定訂單

範例 2：取得訂單詳細資料

範例 3：取得餘額

範例 4：建立新訂單