はじめに

Giftpack API を利用すると、リワード、インセンティブ、マーチャンダイズ、受取人による選択を含むワークフローを、お客様のバックエンドから作成・運用できます。ビジネストリガーと顧客データはお客様のシステムで管理し、カタログの在庫状況、受取人向けエクスペリエンス、フルフィルメント、配送状況の更新は Giftpack が処理します。

本番環境のベース URL は次のとおりです。

https://developer.giftpack.ai

リクエストとレスポンスの完全なスキーマについては、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 キーを作成したら、Webhook イベントカタログを取得してアクセスを確認します。

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

レスポンスには、API が現在サポートしている Webhook イベントタイプが一覧で返されます。ハードコードされたクライアント側のリストではなく、このエンドポイントが正式なイベントカタログです。

次のステップ

1. API キーを保存または使用する前に、認証とセキュリティを確認する。
2. 実装レシピからワークフローを選択する。
3. 本番連携を開始する前に、Webhook を設定して検証する。
4. エンドポイント固有の必須フィールドとレスポンスモデルは、API Referenceで確認する。

用語定義

この定義は、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 の主要な /v1 オペレーションでは、ワークスペース単位の API キーを X-API-KEY ヘッダーで送信します。API キーは、信頼できるサーバーサイドアプリケーションからのみ使用してください。

アクセス要件

API キーは Developer Settings で管理できます。ワークスペースと現在のユーザーには、Giftpack Open API 機能へのアクセス権、および必要な開発者設定権限が必要です。

Developer ページを利用できない場合は、連携の開発を始める前に、ワークスペース管理者へ契約プランとご自身のロールを確認してください。

キーの作成と保管

1. Giftpack にサインインする。
2. Developer Settings を開く。
3. 使用する環境向けの API キーを作成する。
4. キーをサーバーサイドのシークレットマネージャーに保存する。

API キーをブラウザー JavaScript、モバイルアプリケーション、ログ、スクリーンショット、サポートチケット、ソース管理に含めないでください。

ステージング環境と本番環境では別々の認証情報を使用します。キーが漏えいした可能性がある場合は、直ちに無効化してください。

リクエストを認証する

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

API キーによってワークスペースが識別されます。リソースに対する認可はサーバー側で適用されるため、別のワークスペースに属する ID を指定しても、そのリソースへのアクセス権は得られません。

環境と通信

• 本番リクエストは https://developer.giftpack.ai に送信する。
• すべてのリクエストで HTTPS を使用する。
• 認証情報は環境ごとのシークレットストレージに保管する。
• ローカル開発で本番用キーを再利用しない。

API Reference に掲載されている一部のコネクターオペレーションでは、Bearer Token またはプロバイダー固有の認証を使用します。各オペレーションに表示されるセキュリティスキームに従い、Giftpack API キーでコネクターエンドポイントを呼び出せるとは想定しないでください。

運用上のベストプラクティス

• 組織のセキュリティポリシーに従って認証情報をローテーションする。
• キーへのアクセスを、必要とするサービスだけに制限する。
• リクエストログとエラーログから X-API-KEY をマスキングする。
• サポート時の診断に備え、オペレーション、リソース ID、HTTP ステータス、タイムスタンプを記録する。
• API リクエストの認証とは別に、Webhook 署名を検証する。

公開 API の契約では、すべてのオペレーションに共通するレート制限や単一の再試行ポリシーは保証されていません。利用可能な場合は、エンドポイント固有のヘッダーと API Reference を確認し、大量のバーストリクエストを計画する前に Giftpack へお問い合わせください。

エラーと復旧

Giftpack のオペレーションでは、標準の HTTP ステータスコードを使用します。API Reference に記載されているエラーレスポンスのメディアタイプは application/problem+json です。

Problem レスポンス

{
  "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 を永続化する。
• エンドポイントが対応している場合は、自社のビジネス参照フィールドを使用する。
• 複数のワーカーが同一の論理オペレーションを送信しないようにする。

通信タイムアウトは、クライアントがレスポンスを受信しなかったことを意味します。サーバーがリクエストを完了しなかったことの証明にはなりません。

サポート用の診断情報

問題をエスカレーションする際は、エンドポイント、メソッド、UTC タイムスタンプ、HTTP ステータス、関連するリソース ID、機密情報をマスキングした Problem レスポンスを提供してください。API キーやマスキングしていない受取人データは、決して含めないでください。

Webhook と非同期イベント

Webhook は、API リクエストの完了後に発生する受取人およびフルフィルメントの状態遷移を通知します。ライフサイクルを把握するための主要なシグナルとして Webhook を使用し、状態の照合には GET オペレーションを使用してください。

イベントカタログ

古いリストをハードコードせず、現在のカタログを取得してください。

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

現在のカタログには、2 つのリソースファミリーが含まれています。

giftee

連携から開始された Campaign、予約プログラム、自動リワードワークフローなど、Smart Gifting の注文における受取人のライフサイクルイベントです。

• 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

Smart Gifting の Campaign ワークフローを介さず、Gift Mall または Merchandise Catalog から直接行われた注文における受取人のライフサイクルイベントです。

• 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

ペイロード契約

各配信の内容は JSON オブジェクトです。data は構造化されたリソースのスナップショットであり、エスケープされた JSON 文字列ではありません。

{
  "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 はイベントの発生時刻です。配信順序が前後する可能性があるため、状態遷移を並べる際はこの値を使用してください。
• 削除イベントでは、稼働中のリソースが削除された後も、最後に保存されていたスナップショットが保持されます。

署名検証

Giftpack は、未加工のリクエストボディから算出した HMAC-SHA256 ダイジェストを、小文字の 16 進数文字列として 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)
  );
}

ペイロードをパースまたは処理する前に、署名を検証してください。Webhook シークレットはサーバーサイドのシークレットストレージに保管します。

配信と再試行の動作

• Giftpack は JSON ボディを含む HTTP POST を送信します。
• 2xx レスポンスを返すと、配信は成功として記録されます。
• 1 回のリクエストは最大 60 秒間接続されたままになる場合があります。
• 配信に失敗した場合は、約 1 分後、5 分後、15 分後に再試行されます。最初のリクエストを含め、配信試行は最大 4 回です。
• 同じイベントが重複して配信される可能性があります。id に基づいて冪等に処理してください。
• 配信順序は保証されません。

イベントを検証し、永続的に受け入れた後、速やかに 2xx を返してください。負荷の高い処理はキューへ移します。

イベントログのステータス

Webhook のイベントログとリクエストログでは、次の数値ステータスを使用します。

• -1: 失敗
• 0: 処理中
• 1: 成功

イベント詳細レスポンスには、トラブルシューティングに使用できる構造化された webhook_event_data、試行回数、個別のリクエストレコードが含まれます。

本番環境のチェックリスト

• ワークフローが生成するイベントファミリーだけを購読する。
• 未変更の raw body に対して X-Giftpack-Signature を検証する。
• イベントの id で重複排除する。
• created_at を保存し、イベントが順不同で到着しても処理できるようにする。
• イベントを安全に受け入れた後にのみ 2xx を返す。
• 失敗ステータスに達したイベントを監視する。
• 本番エンドポイントを有効にする前に、ダッシュボードのテスト機能を使用する。

実装レシピ

受取人がリワードを受け取る方法に合ったリソースファミリーを選択してください。すべての必須フィールドとレスポンスモデルについては、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 イベントファミリーを設定する。
• 署名を検証し、イベントを重複排除する。
• 状態を変更するリクエストを再試行する前に、タイムアウト時の照合方法を定義する。