ギフトコード

旧称：引き換えコード。API エンドポイントとイベント名に変更はありません。

Tokenz 引き換えコード API を使用してキャンペーンコードの検証と引き換えを行う方法を学びます。

引き換えコード API は、プレイヤーがコードを入力して報酬を受け取るキャンペーンを実施するのに役立ちます。サーバーがコードを検証し、資格を確認し、引き換えを実行した後、フルフィルメントのために redemption.completed Webhook を処理します。

概要

引き換えフローには以下が含まれます：

検証：コードが引き換え可能かどうかを確認し、報酬プレビューを返す
引き換え：特定のプレイヤーのためにコードを消費し、引き換えレコードを作成する
Webhook フルフィルメント：redemption.completed を受信し、ゲームバックエンドで報酬を付与する

キャンペーンの設定と管理

キャンペーンと引き換えコードは、Tokenz Dashboardで作成・管理されます。マーチャントは Tokenz Dashboard を使用して以下を行います：

有効期間と報酬設定を持つキャンペーンを作成する
引き換えコードを生成または管理する
キャンペーンの一時停止、再開、または終了を行う

キャンペーンのステータス

キャンペーンは以下のいずれかのステータスになります：

draft：作業中。引き換えは不可。すべてのフィールドが編集可能
scheduled：公開済みでキュー待ち。設定された start_at 時刻に自動的に active へ移行する
active：キャンペーンは公開中であり、引き換えが成功する
paused：手動で一時停止済み。引き換えは拒否される。active に再開可能
ended：キャンペーンは終了しており、引き換えは拒否される。この状態は不可逆

validate と redeem はキャンペーンが active の場合に成功します。また、scheduled のキャンペーンでも、すでに startAt に達していれば成功します。endAt 以降は拒否されます。scheduled のキャンペーンは startAt に自動的に active へ移行するため、これが影響するのは移行前後の短い時間だけです。

コードのステータス

引き換えコードのステータスは、キャンペーンのステータスとコード自体のステータスから導出されます：

pending：コードは有効だが、キャンペーンが現在アクティブでない（例：draft、scheduled、paused）。引き換え不可。ただし scheduled のキャンペーンで startAt に達している場合は引き換えできる。
active：コードは使用可能。キャンペーンがアクティブである必要がある。引き換え可能なステータスはこれだけではなく、scheduled のキャンペーンが startAt に達すると pending のコードも引き換えできる。
deactivated：コードは無効。マーチャントによる手動無効化、またはキャンペーン終了時に表示される。

表示されるコードステータスはキャンペーンの状態に依存します：

必要に応じて横にスクロール

キャンペーンステータス	コードステータス
`active`	`active`
`draft`、`scheduled`、`paused`	`pending`
`ended`	`deactivated`

キャンペーンが endAt を過ぎると、ステータスが active と表示されていてもコードは引き換えできません。この場合、API は redemptionCode.campaign-invalid エラーを返します。開始前のキャンペーンでも同じエラーが返ります。

マーチャントが手動でコードを無効化した場合、キャンペーンのステータスに関係なく常に deactivated と表示されます。

また、Tokenz Dashboardでは currentRedemptions >= maxRedemptions の場合、コードが引き換え済みと表示されますが、API ステータスは active のままです。これはダッシュボードのみの表示状態であり、API からは返されません。

引き換えのライフサイクル

プレイヤーがプロモーションキャンペーン UI でコードを入力する
サーバーが POST /v1/redemption-codes/validate を呼び出す
サーバーがプレイヤーに報酬プレビューを表示する
プレイヤーが引き換えを確認する
サーバーが POST /v1/redemption-codes/redeem を呼び出す
Tokenz が成功した引き換えレスポンスを返す
Tokenz が redemption.completed Webhook を送信する
バックエンドが報酬をフルフィルメントし、重複フルフィルメントを防ぐために redemptionId を使用する

図

コードの検証

検証はキャンペーンとコードの資格を確認し、キャンペーンプレビューと報酬プレビューを返します。検証が成功するには、キャンペーンがアクティブ、または scheduled で startAt に達しており、かつ endAt より前である必要があります。

bash

curl --request POST \
  --url https://api.tokenz.one/v1/redemption-codes/validate \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --data '{
    "redemptionCode": "SPRING2026FREE",
    "playerId": "player_98765"
  }'

リクエストフィールド

redemptionCode（必須）：プレイヤーが入力したコード
playerId（任意）：マーチャントのプレイヤー識別子。指定した場合、プレイヤーごとの上限も確認される。省略した場合、コードとキャンペーンのグローバル上限のみが検証される

成功レスポンス（`200`）

json

{
  "campaign": {
    "id": "campaign_1AbCdEfGh12",
    "name": "Spring Campaign 2026"
  },
  "rewardPreview": {
    "name": "SSR Reimu Card",
    "imageUrl": "https://images.example.com/rewards/reimu.png",
    "quantity": 1
  }
}

コードの引き換え

引き換えはプレイヤーのためにコードを消費し、引き換えレコードを作成します。引き換えが成功するには、キャンペーンがアクティブ、または scheduled で startAt に達しており、かつ endAt より前である必要があります。

bash

curl --request POST \
  --url https://api.tokenz.one/v1/redemption-codes/redeem \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --data '{
    "redemptionCode": "SPRING2026FREE",
    "playerId": "player_98765"
  }'

リクエストフィールド

redemptionCode（必須）：プレイヤーが入力したコード
playerId（必須）：マーチャントのプレイヤー識別子

成功レスポンス（`201`）

json

{
  "redemptionId": "redemption_1XyZaBcDe34",
  "code": "SPRING2026FREE",
  "playerId": "player_98765",
  "campaign": {
    "id": "campaign_1AbCdEfGh12",
    "name": "Spring Campaign 2026"
  },
  "reward": {
    "skuRedemptionReward": {
      "type": "EXTERNAL_SKU",
      "sku": "ITEM_SSR_REIMU",
      "name": "SSR Reimu Card",
      "quantity": 1
    }
  },
  "redeemedAt": "2026-03-25T08:10:00Z"
}

引き換え Webhook

引き換えが成功すると、Tokenz はこのイベントを購読している Webhook エンドポイントに redemption.completed を送信します。

報酬を付与する前に必ず署名を検証してください。 すべての配信には Tokenz-Signature ヘッダーが含まれます。検証を省略すると、エンドポイントの URL を知った第三者に報酬を付与してしまう可能性があります。生のリクエストボディに対して検証し、その後にパースしてください。手順はWebhook エンドポイントを保護するを参照してください。以下のフィールドは、署名の検証が成功した場合にのみ信頼できます。

json

{
  "id": "f75ff6f0-bdf9-4b25-bb96-968f8733a7e3",
  "object": "redemption.completed",
  "createdAt": "2026-03-24T23:10:00Z",
  "test": false,
  "eventData": {
    "type": "redemption",
    "version": "v1",
    "data": {
      "redemption": {
        "redemptionId": "redemption_1XyZaBcDe34",
        "campaign": {
          "id": "campaign_1AbCdEfGh12",
          "name": "Spring Campaign 2026"
        },
        "code": "SPRING2026FREE",
        "playerId": "player_98765",
        "reward": {
          "skuRedemptionReward": {
            "type": "EXTERNAL_SKU",
            "sku": "ITEM_SSR_REIMU",
            "name": "SSR Reimu Card",
            "quantity": 1
          }
        },
        "redeemedAt": "2026-03-25T08:10:00Z"
      }
    }
  }
}

Webhook 配信のトレースにはトップレベルのイベント id を使用し、バックエンドでの重複フルフィルメントを防ぐために redemptionId を使用してください。

エラー処理

引き換えエンドポイントは、構造化されたエラーオブジェクトを伴う標準 HTTP ステータスコードを返します。

一般的なエラー

401 Unauthorized：無効または欠落している API キー
403 Forbidden：API キーに必要なスコープがない
404 Not Found（entity.not-found）：引き換えコードが見つからない
422 Unprocessable Entity（campaign.limit-reached）：キャンペーンが合計引き換え上限に達した
422 Unprocessable Entity（campaign.player-limit-reached）：プレイヤーがキャンペーンごとの引き換え上限に達した
422 Unprocessable Entity（redemptionCode.campaign-invalid）：キャンペーンが有効でない、有効期間外、またはコードが無効化されている。エラーの message フィールドでこれらの理由を区別できます
422 Unprocessable Entity（redemptionCode.limit-reached）：引き換えコードが自身の利用上限に達した
422 Unprocessable Entity（redemptionCode.player-limit-reached）：プレイヤーがこのコードの引き換え上限に達した
429 Too Many Requests：レート制限を超過した
500 Server Error：予期しないサーバーエラー

テスト

テストモードを使用して引き換え機能の開発とテストを行います：

テスト API キー（test_ プレフィックス付き）を使用してテストキャンペーンとコードを操作する
Tokenz Dashboardでテストモードを使用してテストキャンペーンを作成する
テスト引き換えはライブデータから完全に分離される — テスト API キーはテストコードのみ、ライブ API キーはライブコードのみ引き換え可能
テストエンティティ ID には _t サフィックスが付く（例：redemption_1XyZaBcDe34_t）
テスト Webhook はテスト Webhook エンドポイントにのみ配信され、ペイロードに "test": true が含まれる

ギフトコード

概要

キャンペーンの設定と管理

キャンペーンのステータス

コードのステータス

引き換えのライフサイクル

コードの検証

リクエストフィールド

成功レスポンス（200）

コードの引き換え

リクエストフィールド

成功レスポンス（201）

引き換え Webhook

エラー処理

一般的なエラー

テスト

成功レスポンス（`200`）

成功レスポンス（`201`）