文件介紹

你不需要另外建置獎勵入口網站，也不必手動協調供應商；可直接從既有企業系統（如 CRM、HRIS、內部營運平台）編排贈禮事件（gifting events）。API 讓你的應用程式能以程式方式觸發、管理與監控互動時刻，而 Giftpack 負責履約執行（fulfillment）、可用性、物流與合規。

Giftpack 並非傳統電商 API 的結構。它不是以商品目錄與結帳交易為中心，而是將贈禮流程（gifting）建模為關係事件。收件者身分、時機與商業情境會和寄送品項一樣被視為一等輸入。這使整合能自然對應真實業務觸發點，例如新進入職、週年節點、成交、留存活動或客戶互動里程碑。

API 提供贈禮流程各階段的生命週期可視性，包含 redemption 狀態、fulfillment 進度與配送追蹤（delivery tracking）。透過這些端點，你的系統可衡量成果、自動化後續動作，並將贈禮流程（gifting）納入報表與營運工作流程。

核心概念

在系統層級，Giftpack 依循以下生命週期模型：

Intent → Campaign → Recipient → Redemption → Fulfillment → Tracking

每個階段都代表互動生命週期中的狀態轉換：

• Intent 定義商業觸發或目的。
• Campaign 作為互動容器。
• Recipient 表示參與活動的對象身分。
• Redemption 記錄收件者行為。
• Fulfillment 處理營運履約流程。
• Tracking 提供後續可視性與分析。

生命週期

商業事件
    │
    ▼
[ Intent ]
    │
    │  (同步 API)
    ▼
[ Campaign Created ]
    │
    │  (同步 API)
    ▼
[ Recipient Attached ]
    │
    │  (同步 API)
    ▼
[ Redemption Link Issued ]
    │
    │  ────── 使用者行為（非同步） ──────
    ▼
[ Redemption Claimed ]
    │
    │  (Webhook: giftee.preparing)
    ▼
[ Shipment Processing ]
    │
    │  (Webhook: giftee.shipped)
    ▼
[ Tracking / Delivered ]
    │
    │  (Webhook: giftee.delivered / giftee.failed / giftee.returned)
    ▼
[ Final Tracking State ]
    │
    │  (Webhook: giftee.reviewed)
    ●

此模型可一致套用於智慧贈禮（smart gifting）AutoMatch™ 活動、商城訂單（marketplace orders）、品牌周邊流程（swag workflows）與企業自動化場景。特別在非同步與事件驅動環境中，理解此模型是建立可靠整合的關鍵。

名詞定義

這些定義說明了 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 Integration API 的請求，都必須使用有效的 API Key 進行驗證。

每個端點都強制執行驗證，且以 workspace 邊界進行存取控制。 未授權或驗證不正確的請求，會在進入業務邏輯前被拒絕。

API 金鑰

每個 Giftpack workspace 都可透過 Giftpack 後台建立一把或多把 API Key。

API Key 用於：

• 驗證 API 請求
• 識別來源 workspace
• 執行資源層級授權
• 套用使用控管與速率限制

API Key 為 workspace-scoped。 無法存取其來源 workspace 以外的資源。

Giftpack 不會在不同 workspace 之間共用 API Key。

取得 API Key

建立 API Key 的步驟：

1. 登入 Giftpack 後台
2. 前往 Integration Hub → API Keys
3. 在 Giftpack Integration 下建立新的 API Key

API Key 建立後會立即啟用。 系統會記錄金鑰建立事件以供稽核與追蹤。

使用 API Key

每次請求都必須在 X-API-KEY header 帶入 API Key。

GET /v1/recipients HTTP/1.1
Host: developer.giftpack.ai
X-API-KEY: YOUR_API_KEY

未提供有效 API Key 的請求會回傳驗證錯誤。 驗證會在請求處理與資源判斷前先執行。

授權模型

授權以 workspace 層級執行。 API Key 僅可存取：

• Recipients
• Campaigns
• Marketplace Orders
• Swag Orders
• Credits
• Providers
• 其他屬於該 workspace 的資源

嚴格禁止跨 workspace 存取。 授權決策由伺服器端執行，無法透過客戶端參數覆寫。

金鑰生命週期管理

企業整合應建立完整的金鑰生命週期管理機制。

建議做法：

• 區分 staging 與 production 使用不同 API Key
• 定期輪替 API Key
• 若疑似外洩，立即撤銷 API Key
• 避免在不同團隊或系統間共用 API Key

若 API Key 被撤銷，後續使用該金鑰的請求都會被拒絕。

Giftpack 不會自動輪替 API Key。金鑰管理責任由整合方負責。

傳輸安全

所有 API 請求都必須使用 HTTPS。

• 最低 TLS 版本：TLS 1.2
• 純 HTTP 請求會被拒絕

所有傳輸中資料均以業界標準 TLS 加密。

包含：

• Recipient 資料
• 收件/運送資訊
• 訂單中繼資料
• 驗證 headers

Giftpack 不支援未加密傳輸連線。

速率限制

為確保平台穩定與公平使用，API 請求會受到速率限制。 若超過限制，API 會回傳：

• HTTP 狀態 429
• RATE_LIMIT_EXCEEDED 錯誤碼

整合端應：

• 實作重試邏輯
• 使用 exponential backoff
• 避免過度輪詢

若為高流量或突發型企業工作負載，請聯絡 Giftpack 討論速率設定。

資料隱私與 PII 處理

Giftpack API 可能處理個人可識別資訊（PII），包含：

• 收件者姓名
• Email 地址
• 收件/運送地址

開發者需負責：

• 確保資料處理具合法依據
• 在需要時取得收件者同意
• 符合相關法規（如 GDPR、CCPA）
• 降低不必要的資料儲存

Giftpack 僅為執行贈禮與獎勵流程而處理資料。 Giftpack 不會將收件者資料用於廣告或無關的個人化分析。

日誌與稽核建議

企業環境建議整合端：

• 記錄 outbound API requests
• 記錄回應碼與錯誤狀態
• 監控異常驗證失敗
• 監控異常 rate-limit 事件

Giftpack 內部會記錄：

• 驗證嘗試
• 金鑰使用情況
• 安全相關事件

驗證錯誤回應

驗證與授權錯誤採一致格式。

{
  "error_code": "UNAUTHORIZED",
  "message": "Invalid or missing API key",
  "action": "Verify your API key and include it in the X-API-KEY header"
}

常見驗證相關錯誤碼包含：

• UNAUTHORIZED
• FORBIDDEN
• RATE_LIMIT_EXCEEDED

安全最佳實務

正式環境部署建議：

• 將 API Key 儲存在安全的環境變數
• 不要在前端或 client-side 應用暴露 API Key
• 不要將 API Key 提交到版本控制
• 限制內部對 production key 的存取權
• 優先採用 server-to-server 整合

若懷疑 API Key 已外洩：

1. 立即撤銷該金鑰
2. 建立替代金鑰
3. 檢查近期 API 日誌是否有異常使用

錯誤處理與狀態對照

Giftpack API 採用標準 HTTP 狀態碼，並回傳結構化錯誤 payload。

所有錯誤回應都包含機器可讀的錯誤碼與 request_id。 與支援團隊聯繫時，請務必提供 request_id。

錯誤回應格式

所有錯誤遵循以下結構：

{
  "error": {
    "code": "invalid_request",
    "message": "Recipient email is required.",
    "request_id": "req_123"
  }
}

欄位說明

• code – 機器可讀的錯誤識別碼
• message – 人類可讀的錯誤說明
• request_id – 供除錯追蹤的唯一請求識別碼

建議在系統日誌中保留 request_id，以利營運與故障排查。

HTTP 狀態碼

Giftpack 採用標準 HTTP 狀態語義：

• 200 / 201 – 請求成功
• 400 – 驗證失敗或請求格式錯誤
• 401 – API Key 缺失或無效
• 403 – 權限不足
• 404 – 資源不存在
• 409 – 衝突（例如重複資源或狀態違規）
• 429 – 超過速率限制
• 5xx – 伺服器內部錯誤

重試指引

不是所有錯誤都適合重試。

可安全重試

• 429（超過速率限制）
• 5xx（伺服器錯誤）

重試時請使用 exponential backoff。 避免密集、立即且連續的重試。

不建議重試

• 400（驗證錯誤）
• 401 / 403（驗證或權限失敗）
• 404（資源參照無效）
• 409（業務邏輯衝突）

此類錯誤通常代表客戶端需先修正資料或流程，再重新送出。

非同步狀態與 HTTP 狀態差異

HTTP 成功回應不代表履約已完成。

例如：

• 201 Created 只代表 campaign 建立成功
• 不代表 redemption 已完成
• 不代表 shipment 已完成
• 不代表 delivery 已完成

Giftpack 的多數流程為非同步推進。

要判斷生命週期狀態，請：

• 透過 GET 端點查詢資源狀態
• 或監聽 webhook 事件

請將 HTTP 成功視為「請求已受理」，而非「業務流程已完成」。

冪等性考量

若整合端會重試請求，請確保重複請求不會造成非預期副作用。

適用情境下建議：

• 使用唯一 external identifier
• 保存自有 request tracking ID
• 避免對 4xx 盲目重試

Giftpack 可能依端點邏輯拒絕重複建立資源的請求。

速率限制行為

當超過速率限制時：

• 會回傳 HTTP 狀態 429
• 請延遲後再重試

整合端應：

• 實作 exponential backoff
• 避免高頻輪詢
• 優先使用 webhook 更新，而非頻繁 GET 輪詢

支援與診斷

若遇到非預期錯誤：

• 記錄完整錯誤 payload
• 記錄 request_id
• 聯繫 Giftpack 支援時提供 request_id

這可協助快速在伺服器日誌中完成追蹤。

Webhooks 與非同步事件

Giftpack 工作流程是非同步的。

API 成功回應只代表請求已被受理。 如 redemption、fulfillment、shipping、delivery 等生命週期更新，會透過 webhook 事件通知。

正式環境整合 必須將 webhook 視為主要狀態更新機制。 狀態端點輪詢只應用於對帳或補償。

支援事件類型

Webhook 事件類型由 Giftpack 後台直接管理與顯示。 若要查看或設定可用事件觸發器：

https://giftpack.ai/app/developer/webhooks

後台 UI 反映目前已支援、可正式使用的事件類型。 可用事件以 UI 顯示為準。

目前支援事件範例：

• giftee.created
• giftee.launched
• giftee.preparing
• giftee.shipped
• giftee.delivered
• giftee.failed
• giftee.returned
• giftee.reviewed

事件可用性可能隨時間演進。正式環境設定時請以後台為準。

Webhook 設定

Webhook 以 workspace 為單位透過後台設定。 每筆設定包含：

• name
• endpoint
• event_types
• active 開關
• workspace 範圍的 secret key

範例設定：

{
  "name": "Giftpack Delivery Updates",
  "endpoint": "https://example.com/webhooks/giftpack",
  "event_types": [
    "giftee.created",
    "giftee.shipped",
    "giftee.delivered"
  ]
}

每個 workspace 可建立多筆 webhook 設定。

投遞模型

Webhook 投遞採 at-least-once delivery 模型。

這代表：

• 同一事件可能被重送多次
• 事件順序不保證絕對一致
• 整合端必須實作冪等處理

當你的端點回傳任一 2xx HTTP 狀態碼，即視為投遞成功。

非 2xx 回應會觸發後續重試。

接收端點契約

你的 webhook 端點必須：

• 接收 POST 與 JSON payload
• 回傳 2xx HTTP 狀態表示成功
• 在合理 timeout 內完成回應
• 安全處理重複事件

回應範例：

HTTP/1.1 200 OK
Content-Type: application/json

{"ok": true}

建議以 webhook event ID 作為去重鍵。

事件日誌與投遞嘗試

Giftpack 後台提供完整 webhook 事件日誌。 每筆事件包含：

• 事件中繼資料
• 原始 payload
• 投遞狀態
• 嘗試次數
• 每次嘗試的 request/response 診斷資料

日誌狀態碼：

• 0 – failed
• 1 – processing
• 2 – success

事件明細 API 同時提供：

• Webhook event（邏輯事件）
• Webhook event requests（每次投遞嘗試）

事件明細範例：

{
  "webhook_event_id": "wev_01H...",
  "webhook_setting_id": "whs_01H...",
  "webhook_event_type": "giftee.shipped",
  "webhook_event_resource_type": "giftee",
  "webhook_event_resource_id": "gft_01H...",
  "webhook_event_status": 2,
  "webhook_event_attempts": 1,
  "webhook_event_data": "{...raw payload...}",
  "webhook_event_created_at": "2026-02-20T02:00:00.000Z",
  "webhook_event_updated_at": "2026-02-20T02:00:01.000Z"
}

每次嘗試紀錄包含：

• 目標端點
• HTTP 回應狀態
• 回應 headers
• 回應 body
• 時間戳

此日誌可提供完整投遞可追蹤性，並降低整合除錯成本。

Webhook 測試主控台

Giftpack 後台提供內建 Webhook 測試主控台。 你可以：

• 選擇 webhook 端點
• 選擇事件類型
• 發送模擬事件 payload
• 查看端點即時回應

可用於：

• 端到端驗證
• payload 檢視
• 即時回應診斷

測試回應範例：

{
  "event_data": {
    "type": "giftee.created",
    "resource_type": "giftee",
    "resource_id": "gft_01H..."
  },
  "response_http_status": "200",
  "response_http_headers": {"content-type": "application/json"},
  "response_http_body": "{\"ok\":true}"
}

測試主控台用於正式啟用前的開發與驗證。

傳輸需求

雖然目前 UI 可能允許設定 http 與 https，正式整合請一律使用 HTTPS。

使用 HTTPS 可確保：

• 傳輸加密
• 降低攔截風險
• 符合企業資安要求

整合最佳實務

為確保 webhook 穩定處理：

• 使用冪等事件處理
• 記錄所有入站事件
• 儲存 event IDs 以去重
• 避免在 handler 內做長時間同步處理
• 將重工作業下放 background jobs
• 監控投遞失敗嘗試

Webhook 應作為生命週期更新的權威來源。 不要將同步 API 回應視為最終狀態。

Webhook 簽章驗證

為確保 webhook 事件確實來自 Giftpack 且未被竄改，每次 webhook 請求都會使用 workspace 專屬 secret 簽章。

正式整合 必須驗證 webhook 簽章。

簽章 Header 格式

每次 webhook 請求都會包含：

X-GIFTPACK-SIGNATURE: t=1708459200,v1=abcdef1234567890...

欄位說明

• t — Unix timestamp（秒）
• v1 — HMAC SHA-256 簽章

簽章計算方式：

HMAC_SHA256(secret, `${timestamp}.${raw_body}`)

raw_body 必須使用收到的原始內容，不可修改。

驗證流程

驗證 webhook 請求步驟：

1. 讀取 X-GIFTPACK-SIGNATURE header
2. 解析 timestamp（t）與 signature（v1）
3. 取得原始 request body（JSON parse 前）
4. 計算：

expected_signature = HMAC_SHA256(secret, `${timestamp}.${raw_body}`)

1. 使用 timing-safe comparison 比對 expected_signature 與 v1
2. 以下任一情況拒絕請求：

• 簽章不一致
• timestamp 過舊（建議：超過 5 分鐘）

防止 Replay Attack

為防止 replay attack：

• 驗證 timestamp 在允許範圍內（±300 秒）
• 儲存已處理 event IDs 並拒絕重複
• 不接受未簽章 payload

時間視窗範例：

current_time - timestamp <= 300 seconds

範例（Node.js）

const crypto = require('crypto');

function verifySignature(rawBody, signatureHeader, secret) {
  if (!signatureHeader) return false;

  const elements = signatureHeader.split(',');
  const timestamp = elements.find(e => e.startsWith('t='))?.split('=')[1];
  const signature = elements.find(e => e.startsWith('v1='))?.split('=')[1];

  if (!timestamp || !signature) return false;

  const payload = `${timestamp}.${rawBody}`;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

  const isValid = crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );

  const currentTime = Math.floor(Date.now() / 1000);
  const tolerance = 300; // 5 minutes

  if (Math.abs(currentTime - Number(timestamp)) > tolerance) {
    return false;
  }

  return isValid;
}

Express 範例：

app.post('/webhooks/giftpack',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-giftpack-signature'];
    const isValid = verifySignature(
      req.body.toString(),
      signature,
      process.env.GIFTPACK_WEBHOOK_SECRET
    );

    if (!isValid) {
      return res.status(400).send('Invalid signature');
    }

    const event = JSON.parse(req.body.toString());

    // Process event safely

    res.status(200).json({ ok: true });
});

Secret 管理

Webhook secrets：

• 每筆 webhook 設定皆為唯一
• 必須安全儲存（環境變數）
• 不可暴露於 client-side 程式碼
• 若疑似外洩應立即輪替

若 secret 已輪替，請立即同步更新整合端。

驗證失敗處理

若簽章驗證失敗：

• 回傳非 2xx HTTP 狀態
• 不要處理 payload
• 記錄失敗事件做資安監控

重複簽章失敗可能代表：

• secret 不一致
• 端點設定錯誤
• 惡意流量

投遞模型提醒

Webhook 投遞模型為 at-least-once。 可能出現重複事件。

依案例建置

Giftpack API 以真實商業工作流程為設計核心。

與其直接逐一查找端點，建議先選擇你要實作的業務案例。以下每個案例都說明：

• 業務目的
• API 呼叫順序
• 預期生命週期
• 相關 webhook 事件

Webhook 驗證與簽章處理細節，請參考 Webhooks 與非同步事件 章節。

Create Campaign
      ↓
Add Giftee
      ↓
Generate Redemption Link
      ↓
Recipient Claims
      ↓
Order Processing
      ↓
Shipped
      ↓
Delivered / Failed / Returned

POST /v1/campaigns

POST /v1/giftees

POST /v1/campaigns/{campaignId}/giftees/{gifteeId}/redeemlink

giftee.created
giftee.launched
giftee.preparing
giftee.shipped
giftee.delivered
giftee.failed
giftee.returned
giftee.reviewed

Select Product
      ↓
Create Marketplace Order
      ↓
Preparing
      ↓
Shipped
      ↓
Delivered / Failed / Returned

GET /v1/providers/{providerCode}/products

GET /v1/providers/{providerCode}/products/{productId}

POST /v1/marketplaceorders

giftee.preparing
giftee.shipped
giftee.delivered
giftee.failed
giftee.returned

Enable Points
      ↓
Allocate Points
      ↓
Recipient Redeems
      ↓
Giftee Created
      ↓
Fulfillment Lifecycle

POST /v1/pointrecipients/{memberId}/enablepointfeature

PATCH /v1/pointrecipients/{memberId}/points

giftee.created
giftee.preparing
giftee.shipped
giftee.delivered
giftee.failed
giftee.returned