ドキュメント紹介

個別のリワードポータルを新規構築したり、ベンダーを手作業で調整したりする代わりに、既存の CRM、HRIS、社内オペレーション基盤から贈答イベント（gifting events）を直接オーケストレーションできます。API により、アプリケーションはエンゲージメントの瞬間をプログラムでトリガー・管理・監視でき、Giftpack は業務実行（fulfillment）、在庫可用性、物流、コンプライアンスを担います。

Giftpack は従来の EC API のような構造ではありません。商品カタログとチェックアウト中心ではなく、贈答（gifting）を関係イベントとしてモデル化します。受取人の属性、タイミング、ビジネスコンテキストは、送付アイテムと同等に重要な入力として扱われます。これにより、オンボーディング、記念日、商談成約、リテンション施策、顧客エンゲージメントのマイルストーンなどの実業務トリガーに自然にマッピングできます。

API は redemption ステータス、fulfillment 進行、配送トラッキング（delivery tracking）を含む各段階のライフサイクル可視性を提供します。これらのエンドポイントにより、成果測定、フォローアップ自動化、レポーティングや業務フローへの贈答（gifting）組み込みが可能になります。

コアコンセプト

システムレベルでは、Giftpack は次のライフサイクルモデルに従います。

Intent → Campaign → Recipient → Redemption → Fulfillment → Tracking

各ステージはエンゲージメントライフサイクルにおける状態遷移を表します。

• Intent はビジネストリガーまたは目的を定義します。
• Campaign はエンゲージメントのコンテナとして機能します。
• Recipient はキャンペーンに参加する対象を表します。
• Redemption は受取人のアクションを捉えます。
• Fulfillment は業務実行プロセスを処理します。
• Tracking は事後の可視化と分析を提供します。

ライフサイクル

BUSINESS EVENT
    │
    ▼
[ 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 は次の 3 つの主要レイヤーで構成されます。

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 ダッシュボードで 1 つ以上の 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 リクエストにはレート制限が適用されます。 上限超過時の応答：

• HTTP ステータス 429
• RATE_LIMIT_EXCEEDED エラーコード

連携側は以下を実装してください：

• リトライロジック
• exponential backoff
• 過度なポーリングの回避

高トラフィックまたはバースト型ワークロードについては Giftpack へご相談ください。

データプライバシーと PII 取り扱い

Giftpack API は個人識別情報（PII）を処理する場合があります。例：

• 受信者氏名
• メールアドレス
• 配送先住所

開発者の責任：

• データ処理の法的根拠を確保する
• 必要に応じて受信者同意を取得する
• 関連法規（GDPR、CCPA など）に準拠する
• 不要なデータ保存を最小化する

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 – デバッグ追跡用の一意なリクエスト 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 成功レスポンスは、fulfillment 完了を保証しません。

例：

• 201 Created は campaign 作成成功を示すのみ
• redemption 完了は保証しない
• shipment 完了は保証しない
• delivery 完了は保証しない

Giftpack の多くの処理は非同期に進行します。

ライフサイクル状態を判断するには：

• GET エンドポイントで状態を確認する
• または webhook イベントを購読する

HTTP 成功は「受理」、業務完了ではないと扱ってください。

冪等性の考慮

連携でリトライを行う場合、重複リクエストによる副作用を防いでください。

該当する場合：

• 一意な external identifier を使用する
• 独自の request tracking ID を保存する
• 4xx への盲目的リトライを避ける

Giftpack はエンドポイント仕様に応じて重複作成を拒否する場合があります。

レート制限の挙動

レート制限超過時：

• HTTP ステータス 429 を返却
• 一定時間後に再試行

連携側の推奨：

• exponential backoff を実装
• 高頻度ポーリングを避ける
• 頻繁な GET ポーリングより webhook 更新を優先

サポートと診断

想定外エラーが発生した場合：

• 完全なエラー payload を記録
• request_id を記録
• Giftpack サポートへ request_id を共有

これによりサーバーログ上で迅速に追跡できます。

Webhook と非同期イベント

Giftpack のワークフローは非同期です。

API 成功レスポンスは、リクエストが受理されたことのみを示します。 redemption、fulfillment、shipping、delivery などのライフサイクル更新は webhook イベントで通知されます。

本番連携では webhook を主要な状態更新手段として扱う必要があります。 ステータス API のポーリングは整合性確認やリカバリー用途に限定してください。

サポートされるイベントタイプ

Webhook イベントタイプは Giftpack ダッシュボードで管理・表示されます。 利用可能なイベントトリガーの確認・設定：

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

ダッシュボード 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"
  ]
}

1 つの workspace に複数の webhook 設定を作成できます。

配信モデル

Webhook 配信は at-least-once delivery モデルです。

つまり：

• 同一イベントが複数回配信される可能性がある
• 配信順序は厳密保証されない
• 連携側で冪等なハンドラ実装が必要

エンドポイントが 2xx HTTP ステータスを返せば配信成功とみなされます。

2xx 以外は追加リトライの対象です。

受信エンドポイント契約

Webhook 受信側は以下を満たしてください：

• POST + JSON payload を受け取る
• 成功時に 2xx HTTP ステータスを返す
• 適切なタイムアウト内に処理を完了する
• 重複イベントを安全に扱う

応答例：

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"
}

各試行レコードには以下を含みます：

• 送信先 endpoint
• HTTP レスポンスステータス
• レスポンス headers
• レスポンス body
• タイムスタンプ

このログにより配信トレーサビリティが確保され、デバッグが容易になります。

Webhook テストコンソール

Giftpack にはダッシュボード内蔵の Webhook テストコンソールがあります。 可能な操作：

• webhook endpoint の選択
• イベントタイプの選択
• 模擬イベント payload の送信
• endpoint のライブレスポンス確認

用途：

• エンドツーエンド検証
• 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 ID を保存して重複排除する
• handler 内で長時間の同期処理を避ける
• 重い処理はバックグラウンドジョブに委譲する
• 配信失敗を監視する

Webhook はライフサイクル更新の権威ソースです。 同期 API 成功を最終状態と見なさないでください。

Webhook 署名検証

Webhook が Giftpack 由来で改ざんされていないことを保証するため、各リクエストは workspace ごとの secret で署名されます。

本番連携では 署名検証が必須 です。

署名ヘッダー形式

各 webhook リクエストには次のヘッダーが含まれます：

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

構成要素

• t — Unix timestamp（秒）
• v1 — HMAC SHA-256 署名

署名生成式：

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

raw_body は受信した生データをそのまま使う必要があります。

検証プロセス

検証手順：

1. X-GIFTPACK-SIGNATURE を取得
2. t と v1 を解析
3. JSON 解析前の raw body を取得
4. 次を計算：

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

1. timing-safe comparison で v1 と比較
2. 以下の場合は拒否：

• 署名不一致
• timestamp が古すぎる（推奨: 5 分超）

リプレイ攻撃対策

リプレイ攻撃防止のため：

• timestamp が許容範囲内（±300 秒）であることを検証
• 処理済み event ID を保存し重複拒否
• 未署名 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;

  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 secret は：

• webhook 設定ごとに一意
• 環境変数で安全に保管する
• client-side コードに露出しない
• 侵害疑い時はローテーションする

secret をローテーションした場合、連携側も即時更新してください。

失敗時対応

署名検証に失敗した場合：

• 非 2xx HTTP ステータスを返す
• payload を処理しない
• 失敗ログを残して監視する

署名失敗が続く場合は以下の可能性があります：

• secret 不一致
• endpoint 設定ミス
• 悪意あるトラフィック

配信モデル再確認

Webhook 配信は at-least-once モデルです。 重複イベントは発生し得ます。

ユースケース別ガイド

Giftpack API は実際の業務ワークフローを中心に設計されています。

エンドポイントを直接たどるのではなく、まず実装したい業務ケースを選んでください。各ケースでは次を示します：

• ビジネス意図
• API 実行順序
• 想定ライフサイクル
• 関連 webhook イベント

Webhook 署名検証の詳細は Webhook と非同期イベント を参照してください。

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