プロダクト

早期アクセス: Product API は早期アクセス段階です。機能の追加と対応範囲の拡大を進めています。一部の機能には制限があり、今後変更される可能性があります。本番環境で使用する前に、連携を十分にテストしてください。

Product API を通じて、バーチャルアイテムやバンドルの管理およびアクセス方法について学びます。

Product API は、マーチャントがバーチャルアイテムを管理し、バンドルを作成できるコンテンツ管理システムです。API は、ページネーションとフィルタリングを備えた、プロダクトカタログへの安全なアクセスを提供します。各プロダクトは単一通貨で価格設定されていますが、チェックアウト時には複数の支払い通貨をサポートしています。

ストアフロントに表示するプロダクト情報の取得、在庫管理、お好みの通貨での価格設定を行うことができます。

金額フォーマット： すべての金額値（price フィールドなど）は各通貨の最小単位で表現されます。通貨ごとの正確なエンコーディングについては、サポートされている通貨を参照してください。

概要

プロダクトシステムは 2 つの主要コンポーネントで構成されています：

バーチャルアイテム: 名前、説明、画像、価格を持つ個別のデジタル製品
バンドル: バンドル価格で一緒に販売されるバーチャルアイテムのコレクション

プロダクトは単一通貨での価格設定とリッチメディア添付ファイルをサポートしています。API はページネーションとフィルタリング機能を含んでいます。各プロダクトには 1 つの基本通貨がありますが、顧客はチェックアウト時に現地通貨で支払うことができます。

プロダクトライフサイクル

プロダクト作成: バーチャルアイテムとバンドルは Tokenz Dashboard で作成・設定されます
API アクセス: アプリケーションは、フィルタリングとページネーションを使用して Product API でプロダクトデータを取得します
表示: プロダクトは適切な価格設定でストアフロントに表示されます
統合: プロダクトデータは購入フローのために Checkout Session と統合されます

図

API 呼び出し例

バーチャルアイテム一覧取得

オプションのフィルタリングとソートを使用して、バーチャルアイテムのページネーションされたリストを取得します。

bash

curl --request GET \
  --url 'https://api.tokenz.one/v1/product/virtual-items' \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --header 'Content-Type: application/json'

以下のクエリパラメータがサポートされています：

クエリパラメータ

ページネーション

limit: 返すアイテム数（最大 100、デフォルト 20）
offset: ページネーション用にスキップするアイテム数

フィルタリング

sku: SKU でフィルタ（完全一致）

ソート

バーチャルアイテムとバンドルは以下でのソートに対応：

name_asc / name_desc: 名前でソート
sku_asc / sku_desc: SKU でソート
created_asc / created_desc: 作成日でソート（デフォルト：created_desc）

bash

curl --request GET \
  --url 'https://api.tokenz.one/v1/product/virtual-items?limit=10&offset=0&sku=gold-ring-350&sort=name_asc' \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --header 'Content-Type: application/json'

レスポンス:

json

{
  "data": [
    {
      "id": "virtualitem_YJoSoHrd9R1",
      "sku": "gold-ring-350",
      "label": {
        "en_US": "Gold Ring"
      },
      "description": {
        "en_US": ""
      },
      "images": [
        {
          "id": "3ZUJBfy7M99jRh0YglPUQv",
          "fileName": "gold-ring.png",
          "url": "https://images.ctfassets.net/z82qbo7cv7ia/3ZUJBfy7M99jRh0YglPUQv/a7d42e8c35d2af8ec7efee4e2a1f79b7/gold-ring.png",
          "width": 240,
          "height": 240
        }
      ],
      "defaultFiatCurrency": "JPY",
      "unitPrices": [
        {
          "amount": 350,
          "currency": "JPY"
        }
      ],
      "taxCategory": "DIGITAL_GOODS_AND_SERVICES",
      "createdAt": "2025-07-28T04:28:21.112Z",
      "updatedAt": "2025-07-28T04:28:21.112Z",
      "publishedAt": "2025-07-28T04:28:21.112Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 10,
    "offset": 0,
    "hasNext": false,
    "hasPrevious": false
  }
}

ID によるバーチャルアイテム取得

ID を使用して特定のバーチャルアイテムの詳細情報を取得します。

bash

curl --request GET \
  --url https://api.tokenz.one/v1/product/virtual-items/{VirtualItemID} \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --header 'Content-Type: application/json'

レスポンス:

json

{
  "data": {
    "id": "virtualitem_YJoSoHrd9R1",
    "sku": "gold-ring-350",
    "label": {
      "en_US": "Gold Ring"
    },
    "description": {
      "en_US": ""
    },
    "images": [
      {
        "id": "3ZUJBfy7M99jRh0YglPUQv",
        "fileName": "gold-ring.png",
        "url": "https://images.ctfassets.net/z82qbo7cv7ia/3ZUJBfy7M99jRh0YglPUQv/a7d42e8c35d2af8ec7efee4e2a1f79b7/gold-ring.png",
        "width": 240,
        "height": 240
      }
    ],
    "defaultFiatCurrency": "JPY",
    "unitPrices": [
      {
        "amount": 350,
        "currency": "JPY"
      }
    ],
    "taxCategory": "DIGITAL_GOODS_AND_SERVICES",
    "createdAt": "2025-07-28T04:28:21.112Z",
    "updatedAt": "2025-07-28T04:28:21.112Z",
    "publishedAt": "2025-07-28T04:28:21.112Z"
  }
}

バンドル一覧取得

バンドルアイテムのオプション包含でバンドルを取得します。

bash

curl --request GET \
  --url 'https://api.tokenz.one/v1/product/bundles' \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --header 'Content-Type: application/json'

以下のクエリパラメータがサポートされています：

ページネーション

limit: 返すアイテム数（最大 100、デフォルト 20）
offset: ページネーション用にスキップするアイテム数

アイテム包含

include_items: レスポンスにバンドルアイテムを含める（デフォルト：false）

フィルタリング

sku: SKU でフィルタ（完全一致）

ソート

バンドルは以下でのソートに対応：

name_asc / name_desc: 名前でソート
sku_asc / sku_desc: SKU でソート
created_asc / created_desc: 作成日でソート（デフォルト：created_desc）

bash

curl --request GET \
  --url 'https://api.tokenz.one/v1/product/bundles?include_items=true&limit=10&offset=0&sku=treasure-box&sort=name_asc' \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --header 'Content-Type: application/json'

レスポンス:

json

{
  "data": [
    {
      "id": "bundle_GavBmyQmH43",
      "sku": "treasure-box",
      "label": {
        "en_US": "Treasure Box"
      },
      "description": {
        "en_US": ""
      },
      "images": [
        {
          "id": "3CeCTmaDg0SbVBh1oegKam",
          "fileName": "treasure-box-1.png",
          "url": "https://images.ctfassets.net/z82qbo7cv7ia/3CeCTmaDg0SbVBh1oegKam/9c9cfe621960b96971d1a88089514e2f/treasure-box-1.png",
          "width": 360,
          "height": 360
        }
      ],
      "defaultFiatCurrency": "JPY",
      "unitPrices": [
        {
          "amount": 1500,
          "currency": "JPY"
        }
      ],
      "bundleItems": [],
      "createdAt": "2025-07-28T12:43:28.991Z",
      "updatedAt": "2025-09-12T07:25:13.994Z",
      "publishedAt": "2025-09-12T07:25:13.994Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 10,
    "offset": 0,
    "hasNext": false,
    "hasPrevious": false
  }
}

ID によるバンドル取得

ID を使用して特定のバンドルの詳細情報を取得します。

bash

curl --request GET \
  --url https://api.tokenz.one/v1/product/bundles/{BundleID} \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --header 'Content-Type: application/json'

レスポンス:

json

{
  "data": {
    "id": "bundle_GavBmyQmH43",
    "sku": "treasure-box",
    "label": {
      "en_US": "Treasure Box"
    },
    "description": {
      "en_US": ""
    },
    "images": [
      {
        "id": "3CeCTmaDg0SbVBh1oegKam",
        "fileName": "treasure-box-1.png",
        "url": "https://images.ctfassets.net/z82qbo7cv7ia/3CeCTmaDg0SbVBh1oegKam/9c9cfe621960b96971d1a88089514e2f/treasure-box-1.png",
        "width": 360,
        "height": 360
      }
    ],
    "defaultFiatCurrency": "JPY",
    "unitPrices": [
      {
        "amount": 1500,
        "currency": "JPY"
      }
    ],
    "bundleItems": [
      {
        "quantity": 5,
        "item": {
          "id": "virtualitem_YJoSoHrd9R1",
          "sku": "gold-ring-350",
          "label": {
            "en_US": "Gold Ring"
          },
          "description": {
            "en_US": ""
          },
          "images": [
            {
              "id": "3ZUJBfy7M99jRh0YglPUQv",
              "fileName": "gold-ring.png",
              "url": "https://images.ctfassets.net/z82qbo7cv7ia/3ZUJBfy7M99jRh0YglPUQv/a7d42e8c35d2af8ec7efee4e2a1f79b7/gold-ring.png",
              "width": 240,
              "height": 240
            }
          ],
          "defaultFiatCurrency": "JPY",
          "unitPrices": [
            {
              "amount": 350,
              "currency": "JPY"
            }
          ],
          "taxCategory": "DIGITAL_GOODS_AND_SERVICES",
          "createdAt": "2025-07-28T04:28:21.112Z",
          "updatedAt": "2025-07-28T04:28:21.112Z",
          "publishedAt": "2025-07-28T04:28:21.112Z"
        }
      },
      {
        "quantity": 10,
        "item": {
          "id": "virtualitem_83f3aWcvJ4w",
          "sku": "diamond-currency",
          "label": {
            "en_US": "Diamond"
          },
          "description": {
            "en_US": ""
          },
          "images": [
            {
              "id": "3jOZHd2Ht3uOL1bBxLGmeM",
              "fileName": "pngtree-blue-diamond-for-game-png-image_2914528.jpg",
              "url": "https://images.ctfassets.net/z82qbo7cv7ia/3jOZHd2Ht3uOL1bBxLGmeM/397c603cb7b968bfa9ebba2fcd21216e/pngtree-blue-diamond-for-game-png-image_2914528.jpg",
              "width": 360,
              "height": 360
            }
          ],
          "defaultFiatCurrency": "JPY",
          "unitPrices": [
            {
              "amount": 100,
              "currency": "JPY"
            }
          ],
          "taxCategory": "VIRTUAL_CURRENCY",
          "createdAt": "2025-09-12T02:35:53.272Z",
          "updatedAt": "2025-09-12T02:35:53.272Z",
          "publishedAt": "2025-09-12T02:35:53.272Z"
        }
      }
    ],
    "createdAt": "2025-07-28T12:43:28.991Z",
    "updatedAt": "2025-09-12T07:25:13.994Z",
    "publishedAt": "2025-09-12T07:25:13.994Z"
  }
}

バンドル管理

バンドルを使用すると、複数のバーチャルアイテムを割引価格でグループ化できます。バンドルを取得する際：

バンドルされたアイテムの詳細情報を取得するにはinclude_items=trueを使用
バンドル価格は個別アイテム価格とは独立
各バンドルアイテムには数量情報が含まれます

エラーハンドリング

API は標準の HTTP ステータスコードと詳細なエラーメッセージを返します：

401 Unauthorized: 無効または欠落した API トークン
404 Not Found: プロダクトまたはバンドルが見つからない
429 Too Many Requests: レート制限を超過
500 Server Error: 内部サーバーエラー

すべてのエラーレスポンスには、プログラム的な処理のためのコードとメッセージを含む構造化されたエラーオブジェクトが含まれます。

早期アクセスの状況

Product API は早期アクセス段階です。対応状況と制限は以下のとおりです。

現在利用可能：

バーチャルアイテムとバンドルの管理
プロダクトごとの単一通貨価格設定
基本的なページネーションとフィルタリング
リッチメディア添付ファイル
チェックアウト統合

近日公開予定：

多言語ローカライゼーションサポート
拡張されたフィルタリングと検索機能
高度な在庫管理機能
拡張 API エンドポイント

既知の制限事項：

プロダクト名と説明のローカライゼーションはまだサポートされていません
一部の高度なフィルタリングオプションが制限される場合があります

これらの機能の開発を進めています。早期アクセス期間中のフィードバックをお待ちしています。