概要

• バージョン： 2.0.0
• サーバー： https://store.xsolla.com/api
• メールでのお問い合わせ
• お問い合わせURL： https://xsolla.com/
• 必要なTLSバージョン： 1.2

カタログAPIを使用すると、ゲーム内アイテムのカタログをエクソーラ側で設定し、そのカタログをストア内でユーザーに表示することができます。

本APIでは、以下のカタログエンティティを管理できます：

• 仮想アイテム — 武器、スキン、ブースターなどのゲーム内アイテム。
• 仮想通貨 — 仮想商品の購入に使用される仮想通貨。
• 仮想通貨パッケージ — 事前定義された仮想通貨のバンドル。
• バンドル — 仮想アイテム、通貨、またはゲームキーを1つのSKUとしてまとめたパッケージ。
• ゲームキー — Steamやその他のDRMプロバイダーを通じて配布される、ゲームおよびDLCのキー。
• グループ — カタログ内のアイテムを整理または並べ替えするための論理的なグループ分け。

APIコール

本APIは、以下のグループに分かれています：

• Admin — カタログアイテムやグループの作成、更新、削除、および設定を行うためのコール。マーチャントまたはプロジェクトの認証情報による基本アクセス認証で認証されます。ストアフロントでの使用は想定されていません。
• Catalog — アイテムの取得や、エンドユーザー向けのカスタムストアフロントを構築するためのコール。高負荷なシナリオに対応できるよう設計されています。ユーザー個別の制限事項や実施中のプロモーションなど、パーソナライズされたデータを返すための、ユーザーJWTによる任意認証をサポートしています。

認証

APIコールには、ユーザーまたはプロジェクトのいずれかに代わって認証が必要です。使用される認証スキームは、各コールの説明のセキュリティセクションに指定されています。

ユーザーのJWTを使用した認証

ユーザーのJWTを使用した認証は、ブラウザ、モバイルアプリケーション、またはゲームからリクエストが送信される場合に使用されます。デフォルトでは、XsollaLoginUserJWTスキームが適用されます。トークンの作成方法の詳細については、エクソーラログインAPIに関するドキュメントを参照してください。

トークンはAuthorizationヘッダーに次の形式で渡されます：Authorization: Bearer <user_JWT>。ここで<user_JWT>はユーザートークンです。このトークンによってユーザーが特定され、パーソナライズされたデータへのアクセスが可能になります。

別の方法として、決済UIを開くためのトークンを使用することも可能です。

基本HTTP認証

基本HTTP認証は、ユーザーのブラウザやモバイルアプリケーションからではなく、サーバーから直接APIコールが送信される場合のサーバー間のやり取りに使用されます。通常、APIキーを使用したHTTP基本認証が使用されます。

基本的なサーバーサイド認証では、すべてのAPIリクエストに以下のヘッダーを含める必要があります：

• basicAuthの場合 — Authorization: Basic <your_authorization_basic_key>。ここでyour_authorization_basic_keyは、Base64でエンコードされたproject_id:api_keyペアです。
• basicMerchantAuthの場合 — Authorization: Basic <your_authorization_basic_key>。ここでyour_authorization_basic_keyは、Base64でエンコードされたmerchant_id:api_keyペアです。

パラメータの値はパブリッシャーアカウントで確認できます：

• merchant_idは次の場所に表示されます：
  • 会社設定 > 会社。
  • パブリッシャーアカウントの任意のページのブラウザアドレスバーのURLに。URLの形式は以下の通りです： https://publisher.xsolla.com/<merchant_id>。
• project_idは次の場所に表示されます：
  • パブリッシャーアカウントのプロジェクト名の横に。
  • パブリッシャーアカウントでプロジェクトを操作しているときのブラウザアドレスバーのURLに。URLの形式は以下の通りです：https://publisher.xsolla.com/<merchant_id>/projects/<project_id>。
• api_keyは作成時にのみパブリッシャーアカウントに表示され、あなたの側で安全に保管する必要があります。APIキーは次のセクションで作成できます：
  • 会社設定 > APIキー
  • プロジェクト設定 > APIキー

APIキーの操作に関する詳細は、APIリファレンスを参照してください。

ゲストアクセスをサポートする認証

AuthForCart認証スキームはカートでの購入用であり、以下の2つのモードに対応しています：

1. ユーザーのJWTを使用した認証。 トークンは、次の形式でAuthorizationヘッダーに渡されます： Authorization: Bearer <user_JWT>。ここで<user_JWT>はユーザートークンです。このトークンはユーザーを識別し、パーソナライズされたデータへのアクセスを提供します。 または、決済UIを開くためのトークンを使用することもできます。

2. 認証ヘッダーを使用しない簡易モード。 このモードは未認証ユーザーにのみ使用され、ゲームキー販売にのみ適用できます。リクエストにはトークンの代わりに、以下のヘッダーを含める必要があります：

   • リクエストIDを含むx-unauthorized-id
   • Base64でエンコードされたユーザーのメールアドレスを含むx-user

有用なリンク

• 相互作用モデルに基づくAPIコール
• エンドポイントタイプ
• エラー処理
• APIキー

主要なエンティティ構造

すべてのタイプ（仮想アイテム、バンドル、仮想通貨、キー）のアイテムは、同様のデータ構造を使用しています。この基本構造を理解することで、APIの利用が簡素化され、ドキュメントをよりスムーズに読み進められるようになります。

識別

• merchant_id — パブリッシャーアカウントにおける会社ID
• project_id — パブリッシャーアカウントにおけるプロジェクトID
• sku — アイテムSKU、プロジェクト内で一意です

ストア表示

• name — アイテム名
• description — アイテム説明
• image_url — 画像URL
• is_enabled — アイテムの可用性
• is_show_in_store — アイテムがカタログに表示されるかどうか

カタログ内のアイテムの可用性管理に関する詳細は、ドキュメントを参照してください。

組織

• type — アイテムタイプ、例：仮想アイテム（virtual_item）またはバンドル（bundle）
• groups — アイテムが属するグループ
• order — カタログ内の表示順序

Sale conditions

• prices — 実際通貨または仮想通貨での価格
• limits — 購入制限
• periods — 可用期間
• regions — 地域別制限

主要なエンティティ構造の例：

基本的な購入フロー

エクソーラAPIを使用すると、ゲーム内ストアのロジックを実装でき、アイテムカタログの取得、カートの管理、注文の作成、そのステータスの追跡が可能です。統合シナリオに応じて、APIコールは管理者とカタログのサブセクションに分かれ、異なる認証スキームを使用します。

以下の例は、アイテムの作成から購入に至るまで、ストアのセットアップおよび運用の基本フローを示しています。

アイテムおよびグループの作成（管理者向け）

仮想アイテム、バンドル、仮想通貨など、ストアのアイテムカタログを作成します。

APIコールの例：

• 仮想アイテムを作成する
• バンドルを作成する
• 仮想通貨を作成する

プロモーション、チェーン、および制限の設定（管理者向け）

割引、ボーナス、デイリー報酬、またはオファーチェーンなど、ユーザー獲得および収益化のためのツールを設定します。

APIコールの例：

• ボーナスプロモーションを作成する
• デイリー報酬を作成する
• ユニークなカタログオファープロモーションを作成する

アイテム情報の取得（クライアント向け）

アプリケーション内でのアイテム表示を設定します。

APIコールの例：

• 仮想アイテムリストを取得する
• アイテムグループリストを取得する
• バンドルリストを取得する
• 販売可能なアイテムリストを取得する

アイテムの販売

アイテムは以下の方法で販売できます：

• 迅速な購入 — 1つのSKUを複数回販売します。
• カート購入 — ユーザーがアイテムをカートに追加し、アイテムを削除し、単一の注文内で数量を更新します。

アイテムが実際のお金ではなく仮想通貨で購入された場合は、仮想通貨で購入した指定アイテムで注文を作成するAPIコールを使用してください。当該APIコールの実行時に課金処理が行われるため、決済UIを表示する必要はありません。

無料アイテムの購入には、指定した無料アイテムで注文を作成するAPIコールまたは無料カートで注文を作成するAPIコールを使用してください。決済UIを表示する必要はありません。注文は即時にdoneステータスに設定されます。

迅速な購入

クライアント側のAPIコールを使用して、指定したアイテムで注文を作成します。このコールは、決済UIを開くために使用するトークンを返します。

カート購入

カートの設定と購入は、クライアントまたはサーバー側で実行できます。

クライアント側でのカートのセットアップと購入

アイテムの追加および削除のロジックは、独自に実装してください。カートを設定するためのAPIを呼び出す前は、購入にどのプロモーションが適用されるかに関する情報は取得できません。つまり、合計金額や、追加されるボーナスアイテムの詳細を事前に知ることはできません。

以下のカートロジックを実装します：

1. プレイヤーがカートにアイテムを入れた後、カートにアイテムを入れるAPIコールを使用します。このコールは、選択されたアイテムに関する現在の情報（割引前後の価格、ボーナスアイテム）を返します。
2. ユーザーのアクションに基づいてカートの内容を更新します：
   • アイテムの追加または数量の変更を行うには、カートIDでカートアイテムを更新するAPIコールを使用します。
   • アイテムを削除するには、カートIDでカートアイテムを削除するAPIコールを使用します。

3. 現在のカートからすべてのアイテムで注文を作成するAPIコールを使用します。このコールは注文IDと決済トークンを返します。新しく作成された注文はデフォルトでnewステータスに設定されます。

サーバー側でのカートのセットアップと購入

カートへの変更ごとにAPIコールを伴う必要があるため、この設定オプションではカートの設定に時間がかかる場合があります。

以下のカートロジックを実装します：

1. プレイヤーがカートにアイテムを入れた後、カートにアイテムを入れるAPIコールを使用します。このコールは、選択されたアイテムに関する現在の情報（割引前後の価格、ボーナスアイテム）を返します。
2. 現在のカートのすべてのアイテムで注文を作成するAPIコールを使用します。このコールは、注文IDと支払いトークンを返します。新しく作成された注文は、デフォルトでnewステータスに設定されます。

決済UIを開く

返されたトークンを使用して、新しいウィンドウで決済UIを開きます。決済UIを開くその他の方法は、ドキュメントに記載されています。

| アクション | エンドポイント | |：--------------------------------|：--------------------------------------------------------------------------| | 本番環境で開きます。 | https://secure.xsolla.com/paystation4/?token={token} | | サンドボックスモードで開きます。 | https://sandbox-secure.xsolla.com/paystation4/?token={token} |

サンドボックスモードを有効または無効にするには、迅速な購入およびカート購入のリクエストでsandboxパラメータの値を変更します。サンドボックスモードはデフォルトでオフになっています。

可能な注文状況：

• new — 注文作成済み
• paid — 支払い受領済み
• done — アイテム付与完了
• canceled — 注文キャンセル済み
• expired — 注文期限切れ

以下のいずれかの方法を使用して、注文ステータスを追跡します：

• サーバーサイドで設定されたウェーブフック
• ショートポーリング
• WebSocket API

有用なリンク

• 認証
• インタラクションモデルに基づくAPIコール
• 決済テスト
• 注文状況追跡の設定
• ウェブフック
• レート制限
• エラー処理
• APIキー

ページネーション

大規模なレコードセットを返すAPIコール（カタログを構築する場合など）では、データがページ分割されて返されます。ページネーションは、単一のAPI応答で返されるアイテム数を制限し、下一ページのデータを順次取得できるようにするための仕組みです。

返されるアイテム数を制御するには、以下のパラメータを使用します：

• limit — 1ページあたりのアイテム件数
• offset — ページ上の最初のアイテムのインデックス（番号付けは0から始まります）
• has_more — 次のページが利用可能かどうかを示します
• total_items_count — アイテムの総数

リクエスト例：

応答例：

応答がhas_more = falseを返すまで、後続のリクエストを送信することをお勧めします。

日付と時刻の形式

日付と時間の値は、ISO 8601フォーマットで渡されます。

以下がサポートされています：

• UTCオフセット
• アイテムの表示に時間制限がない場合はnull値
• 一部のフィールドで使用されるUnixタイムスタンプ（秒単位）

フォーマット：YYYY-MM-DDTHH:MM:SS±HH:MM

例：2026-03-16T10:00:00+03:00

ローカリゼーション

エクソーラは、アイテム名や説明などのユーザー向けフィールドのローカライズをサポートしています。ローカライズされた値は、言語コードをキーとするオブジェクトとして渡されます。サポートされている言語の完全なリストは、ドキュメントで確認できます。

サポートされているフィールド

次のパラメータに対してローカリゼーションを指定できます：

• name
• description
• long_description

ロケール形式

ロケールキーは、以下のいずれかのフォーマットで指定できます：

• 2文字の言語コード：en、ru
• 5文字の言語コード： en-US、ru-RU、de-DE

例

2文字の言語コードの例：

5文字の言語コードの例：

エラー応答フォーマット

エラーが発生した場合、APIはHTTPステータスとJSON応答本文を返します。ストア関連のエラーの全リストはドキュメントで確認できます。

応答例：

• errorCode — エラーコード。
• errorMessage — 短いエラー説明。
• statusCode — HTTP応答ステータス。
• transactionId — リクエストID。一部の場合にのみ返されます。
• errorMessageExtended — リクエストパラメータなどの追加エラー詳細。一部の場合にのみ返されます。

拡張応答例：

共通のHTTPステータスコード

• 400 — 無効なリクエスト
• 401 — 認証エラー
• 403 — 権限不足
• 404 — リソースが見つかりません
• 422 — 検証エラー
• 429 — レート制限超過

推奨事項

• HTTPステータスと応答本文を一緒に処理します。
• errorCodeを使用してアプリケーションロジックに関連するエラーを処理します。
• transactionIdを使用して、エラーを分析する際にリクエストをより迅速に特定します。