從這裡開始

Giftpack API 可讓你的後端建立及執行獎勵、激勵、企業贈品與受贈者自主選擇等工作流程。你的系統負責管理業務觸發條件與客戶資料；Giftpack 則處理目錄供應狀態、受贈體驗、履約及配送進度更新。

正式環境的基礎 URL 為：

https://developer.giftpack.ai

如需完整的請求與回應 schema，請參閱 API Reference。本指南可協助你選擇正確的資源系列，並了解資源建立後的狀態演進。

選擇工作流程

資源模型

Smart Gifting 以 campaign 作為方案容器，並以 giftee 表示各受贈者的生命週期：

Campaign -> Giftee -> Redemption -> Fulfillment -> Delivery

直接目錄訂單以 marketplace order 作為訂單容器，並以 marketplace order receiver 表示各受贈者的生命週期：

Marketplace Order -> Receiver -> Claim or Selection -> Fulfillment -> Delivery

請勿將 giftee 與 marketplace_order_receiver 視為可互換的資源。即使兩者的履約狀態相似，其事件名稱仍代表不同的訂單系列。

請求生命週期

建立與更新請求會回傳資源的目前狀態。受贈者操作、履約、出貨與送達則會以非同步方式持續進行。

若要建立可靠的整合：

• 儲存回傳的資源 ID。
• 訂閱相符的 Webhook 事件系列。
• 使用 Webhook 事件的 id 作為去重鍵。
• 當系統偵測到事件遺漏或延遲時，透過 GET 端點核對資源狀態。
• 除非該 API 操作明確說明冪等性合約，否則請勿自動重試會變更狀態的請求。

第一個請求

在 Giftpack 建立 API key 後，可透過 Webhook 事件目錄驗證存取權限：

curl https://developer.giftpack.ai/v1/webhookeventtypes \
  --header 'Accept: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY'

回應會列出 API 目前支援的 Webhook 事件類型。此端點才是事件目錄的權威來源，請勿依賴寫死在客戶端的清單。

後續步驟

1. 儲存或使用 API key 前，請先閱讀身分驗證與安全性。
2. 在實作指南中選擇一種工作流程。
3. 正式上線前，先設定並驗證 Webhook。
4. 使用 API Reference 查閱各端點的必填欄位與回應模型。

名詞定義

這些定義說明了 Giftpack API 整合中使用的核心領域物件。 在建立工作流程前，理解這些物件之間的關係非常重要。 Giftpack 主要運作於三個層次：

1. 互動層 (Engagement Layer)
2. 商務層 (Commerce Layer)
3. 供應與營運層 (Supply & Operations Layer)

Recipient
  └─ may belong to Recipient Group
  └─ becomes Giftee when attached to Campaign

Campaign (Engagement Container)
  ├─ defines Redemption rules
  ├─ manages Giftee states
  └─ may generate Fulfillment Orders

Commerce Layer
  ├─ Marketplace Order (direct transaction)
  └─ Swag Order (inventory-based transaction)

Redemption
  ├─ Link-based
  ├─ Email-based
  └─ Transitions state before fulfillment

身分驗證與安全性

Giftpack 核心 /v1 操作使用限定於工作區的 API key，並透過 X-API-KEY header 傳送。API key 只能由可信任的伺服器端應用程式使用。

存取需求

API key 可在開發者設定中管理。工作區與目前使用者必須具備 Giftpack Open API 功能的存取權，以及開發者設定所需的權限。

如果無法開啟「開發者」頁面，請先請工作區管理員確認工作區方案及你的角色，再開始建立整合。

建立及儲存 Key

1. 登入 Giftpack。
2. 開啟開發者設定。
3. 為預定使用的環境建立 API key。
4. 將 key 儲存在伺服器端的秘密管理工具中。

絕對不要將 API key 放在瀏覽器 JavaScript、行動應用程式、log、螢幕截圖、客服工單或原始碼版本控制中。

測試環境與正式環境應使用不同的憑證。若 key 可能已外洩，請立即撤銷。

驗證請求

curl https://developer.giftpack.ai/v1/webhookeventtypes \
  --header 'Accept: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY'

API key 用於識別工作區。資源授權會在伺服器端強制執行，因此即使取得其他工作區的 ID，也不代表能存取該資源。

環境與傳輸

• 將正式環境請求傳送至 https://developer.giftpack.ai。
• 所有請求都必須使用 HTTPS。
• 將憑證保存在各環境專用的秘密儲存空間。
• 請勿在本機開發環境重複使用正式環境的 key。

API Reference 中的部分 connector 操作會使用 bearer token 或供應商專用的驗證方式。請依照個別操作所列的 security scheme 執行，不要假設 Giftpack API key 能呼叫 connector 端點。

維運實務

• 依照組織的安全政策定期輪替憑證。
• 僅允許確實需要的服務存取 key。
• 從請求與錯誤 log 中遮蔽 X-API-KEY。
• 記錄操作、資源 ID、HTTP 狀態及時間戳記，以供支援診斷使用。
• Webhook 簽章必須獨立於 API 請求驗證進行檢查。

公開合約並未承諾所有操作共用單一 rate limit 或重試政策。若個別端點提供相關 header 或 API Reference 說明，請以該資訊為準；規劃高流量突發請求前，請先聯絡 Giftpack。

錯誤與復原

Giftpack 操作使用標準 HTTP 狀態碼。API Reference 所記載的錯誤回應使用 application/problem+json。

問題回應

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Property email is required but is missing.",
  "instance": "https://developer.giftpack.ai/errors/example",
  "errors": [
    {
      "location": "body.email",
      "message": "The email field is required.",
      "value": null
    }
  ]
}

欄位

• type：識別問題類型的 URI，可能為 about:blank。
• title：穩定且易於理解的問題摘要。
• status：此回應所對應的 HTTP 狀態。
• detail：本次特定失敗的說明。
• instance：如有提供，用於識別本次問題實例的 URI。
• errors：選填的欄位級錯誤明細，包含 location、message 與 value。

並非每個錯誤都保證包含所有欄位。剖析器應能容許選填欄位缺漏，以及未來新增的未知欄位。

依狀態復原

各操作所記載的回應，以 API Reference 為權威來源。

安全重試

GET 請求通常可使用設有上限的指數退避策略重試。會變更狀態的請求則需要更審慎處理：

• POST 或 PATCH 請求逾時後，請勿直接重試。
• 先確認該操作是否記載冪等性，或是否會回傳可供核對的資源。
• 開始下一個步驟前，先持久化儲存回傳的 ID。
• 若端點支援，請使用自有的業務參照欄位。
• 避免多個並行 worker 提交同一筆邏輯操作。

傳輸逾時只代表客戶端未收到回應，無法證明伺服器未完成該請求。

支援診斷

回報問題時，請提供端點、method、UTC 時間戳記、HTTP 狀態、相關資源 ID，以及已遮蔽敏感資訊的問題回應。絕對不要附上 API key 或未遮蔽的受贈者資料。

Webhook 與非同步事件

Webhook 會回報 API 請求回傳後發生的受贈者與履約狀態轉換。請將 Webhook 作為生命週期的主要訊號，並使用 GET 操作核對狀態。

事件目錄

請取得最新目錄，不要寫死舊版清單：

curl https://developer.giftpack.ai/v1/webhookeventtypes \
  --header 'Accept: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY'

目前的目錄包含兩個資源系列。

giftee

Smart Gifting 訂單的受贈者生命週期事件，包括透過整合啟動的 campaign、排程方案及自動化獎勵工作流程。

• giftee.created
• giftee.launched
• giftee.preparing
• giftee.shipped
• giftee.delivered
• giftee.failed
• giftee.returned
• giftee.reviewed
• giftee.cancel
• giftee.resume
• giftee.delete

marketplace_order_receiver

直接透過 Gift Mall 或 Merchandise Catalog 建立、且不屬於 Smart Gifting campaign 工作流程之訂單的受贈者生命週期事件。

• marketplace_order_receiver.created
• marketplace_order_receiver.launched
• marketplace_order_receiver.shipped
• marketplace_order_receiver.delivered
• marketplace_order_receiver.failed
• marketplace_order_receiver.returned
• marketplace_order_receiver.reviewed
• marketplace_order_receiver.delete

Payload 合約

每次投遞的內容都是 JSON object。data 是結構化的資源快照，不是經過跳脫的 JSON string。

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "type": "giftee.shipped",
  "data": {
    "id": "23e4567-e89b-12d3-a456-426655440000",
    "type": "giftee",
    "email": "recipient@example.com",
    "status": 12,
    "delivery_status": 2,
    "budget": 100,
    "campaign": {
      "id": "323e4567-e89b-12d3-a456-426655440000"
    },
    "recipient": {
      "id": "423e4567-e89b-12d3-a456-426655440000"
    },
    "delivery_tracking_code": "TRACKING-CODE"
  },
  "created_at": "2026-09-01 15:23:33"
}

• id 是永久保留的事件實例 ID，應作為去重鍵。
• type 用於識別資源系列與狀態轉換。
• data 擷取事件發生當下的資源狀態。欄位會依資源系列及生命週期階段而異。
• created_at 是事件發生時間。投遞順序可能與事件發生順序不同，因此排序狀態轉換時請使用此值。
• 資源從線上資料中移除後，delete 事件仍會保留最後一次儲存的快照。

簽章驗證

Giftpack 會將原始 request body 的 HMAC-SHA256 digest，以小寫十六進位格式放在 X-Giftpack-Signature 中傳送。

const crypto = require('crypto');

function verifyGiftpackWebhook(rawBody, signature, secret) {
  if (!signature) return false;

  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const actualBuffer = Buffer.from(signature, 'utf8');
  const expectedBuffer = Buffer.from(expected, 'utf8');

  return (
    actualBuffer.length === expectedBuffer.length &&
    crypto.timingSafeEqual(actualBuffer, expectedBuffer)
  );
}

請在剖析或處理 payload 前驗證簽章。Webhook secret 應儲存在伺服器端的秘密儲存空間。

投遞與重試行為

• Giftpack 會使用 HTTP POST 傳送 JSON body。
• 任何 2xx 回應都表示投遞成功。
• 每次請求最長可維持開啟 60 秒。
• 投遞失敗後，會約在 1、5 及 15 分鐘後重試；包含首次請求在內，最多嘗試投遞四次。
• 事件可能重複投遞。請以冪等方式處理 id。
• 不保證投遞順序。

驗證並可靠接收事件後，請儘快回傳 2xx。將耗時的工作移至 queue 執行。

事件 Log 狀態

Webhook event 與 request log 使用以下數值狀態：

• -1：失敗
• 0：處理中
• 1：成功

事件詳細資料回應包含結構化的 webhook_event_data、嘗試次數，以及各次 request record，供疑難排解使用。

正式環境檢查清單

• 僅訂閱你的工作流程會產生的事件系列。
• 使用未經修改的 raw body 驗證 X-Giftpack-Signature。
• 以事件 id 去重。
• 儲存 created_at，並容許事件未依順序抵達。
• 僅在事件已安全接收後回傳 2xx。
• 監控進入失敗狀態的事件。
• 啟用正式環境端點前，先使用 dashboard 測試操作。

實作指南

請依受贈者取得獎勵的方式選擇相符的資源系列。每個必填欄位與回應模型仍以 API Reference 為權威來源。

curl https://developer.giftpack.ai/v1/marketplaceorders \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "marketplace_order_name": "September employee rewards",
    "marketplace_order_start_date": "2026-09-01",
    "marketplace_order_end_date": "2026-09-30",
    "marketplace_order_type": "Normal",
    "submit": false,
    "receivers": [
      {
        "member_id": "9a1232aa-238f-421c-82e7-45693d1b25b4",
        "country": "US",
        "gift_message": "Thank you for your contribution.",
        "email_notification": true,
        "sms_notification": false,
        "marketplace_feature": false,
        "donation_feature": false,
        "products": [
          {
            "marketplace_product_id": "961be65a-88d8-4040-8808-843ccf5da624",
            "marketplace_product_variant_id": "961be65a-a96a-412d-b22a-325f07d85647",
            "product_quantity": 1
          }
        ]
      }
    ]
  }'

curl https://developer.giftpack.ai/v1/pointrecipients/MEMBER_ID/points \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "credits": 1,
    "points": 100,
    "expired_at": "2027-09-01",
    "notes": "Annual recognition allocation"
  }'

正式上線前

• 依照目前的 API Reference 驗證必填欄位。
• 使用非正式環境的受贈者資料與憑證進行測試。
• 持久化儲存每個回傳的資源 ID。
• 設定相符的 Webhook 事件系列。
• 驗證簽章並對事件去重。
• 在重試會變更狀態的請求前，先定義系統核對逾時結果的方式。