--- title: "プロダクト" description: "Product API を通じて、バーチャルアイテムやバンドルの管理およびアクセス方法について学びます。" source: "https://docs.tokenz.one/ja/v2/product" api_version: "v2" locale: "ja" version_status: "current" docs_stage: "prod" --- # プロダクト > **早期アクセス**: Product API は早期アクセス段階です。機能の追加と対応範囲の拡大を進めています。一部の機能には制限があり、今後変更される可能性があります。本番環境で使用する前に、連携を十分にテストしてください。 Product API を通じて、バーチャルアイテムやバンドルの管理およびアクセス方法について学びます。 Product API は、マーチャントがバーチャルアイテムを管理し、バンドルを作成できるコンテンツ管理システムです。API は、ページネーションとフィルタリングを備えた、プロダクトカタログへの安全なアクセスを提供します。各プロダクトは単一通貨で価格設定されていますが、チェックアウト時には複数の支払い通貨をサポートしています。 ストアフロントに表示するプロダクト情報の取得、在庫管理、お好みの通貨での価格設定を行うことができます。 **金額フォーマット：** すべての金額値（`price` フィールドなど）は各通貨の最小単位で表現されます。通貨ごとの正確なエンコーディングについては、[サポートされている通貨](https://docs.tokenz.one/ja/v2/checkout/currency)を参照してください。 ## 概要 プロダクトシステムは 2 つの主要コンポーネントで構成されています： - **バーチャルアイテム**: 名前、説明、画像、価格を持つ個別のデジタル製品 - **バンドル**: バンドル価格で一緒に販売されるバーチャルアイテムのコレクション プロダクトは単一通貨での価格設定とリッチメディア添付ファイルをサポートしています。API はページネーションとフィルタリング機能を含んでいます。各プロダクトには 1 つの基本通貨がありますが、顧客はチェックアウト時に現地通貨で支払うことができます。 ## プロダクトライフサイクル 1. **プロダクト作成**: バーチャルアイテムとバンドルは Tokenz Dashboard で作成・設定されます 2. **API アクセス**: アプリケーションは、フィルタリングとページネーションを使用して Product API でプロダクトデータを取得します 3. **表示**: プロダクトは適切な価格設定でストアフロントに表示されます 4. **統合**: プロダクトデータは購入フローのために Checkout Session と統合されます ```mermaid sequenceDiagram; autonumber; participant M as マーチャントアプリ; participant T as Product API; participant DB as プロダクトデータベース; %% 1 ── プロダクトカタログをリクエスト; M->>T: GET /v2/product/virtual-items; T->>DB: バーチャルアイテムをクエリ; DB-->>T: プロダクトデータを返却; T-->>M: ページネーションされたプロダクトリスト; %% 2 ── 特定のプロダクト詳細をリクエスト; M->>T: GET /v2/product/virtual-items/{id}; T->>DB: 特定のアイテムをクエリ; DB-->>T: 詳細なプロダクトを返却; T-->>M: 完全なプロダクト詳細; %% 3 ── チェックアウトとの統合; M->>M: 顧客がプロダクトを選択; M->>T: プロダクトで Checkout Session を作成; T-->>M: チェックアウトセッション作成完了; ``` ## API 呼び出し例 ### バーチャルアイテム一覧取得 オプションのフィルタリングとソートを使用して、バーチャルアイテムのページネーションされたリストを取得します。 ```bash curl --request GET \ --url 'https://api.tokenz.one/v2/product/virtual-items' \ --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \ --header 'Content-Type: application/json' ``` 以下のクエリパラメータがサポートされています： ### クエリパラメータ #### ページネーション - `limit`: 返すアイテム数（最大 100、デフォルト 20） - `offset`: ページネーション用にスキップするアイテム数 #### フィルタリング - `sku`: SKU でフィルタ（完全一致） - `category`: カテゴリでフィルタ #### ソート バーチャルアイテムとバンドルは以下でのソートに対応： - `name_asc` / `name_desc`: 名前でソート - `sku_asc` / `sku_desc`: SKU でソート - `created_asc` / `created_desc`: 作成日でソート（デフォルト：`created_desc`） ```bash curl --request GET \ --url 'https://api.tokenz.one/v2/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/v2/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/v2/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/v2/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/v2/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 エンドポイント **既知の制限事項：** - プロダクト名と説明のローカライゼーションはまだサポートされていません - 一部の高度なフィルタリングオプションが制限される場合があります これらの機能の開発を進めています。早期アクセス期間中のフィードバックをお待ちしています。