概要

エクソーラAPIは以下のことを含む：

• ペイステーションAPI — 決済UIとトークン化メソッド。
• インゲームストア&ゲームキーの直接販売API — インゲームストアおよびゲームキーの直接販売モジュールを操作するメソッド。
• サブスクリプションAPI — サブスクリプションのためのメソッド。
• アドミンページAPI — アドミンページのプロジェクトとユーザー、レポート、サポートチケットを操作するメソッド。
• ログインAPI — 独自のインターフェースを使用したユーザー認証のためのメソッド（統合ガイドを参照してください）。

エクソーラAPIはRESTに基づいて設計されています。APIには、予測可能なリソース指向のURLがあり、HTTPレスポンスコードを使用してAPIエラーを示します。APIは、エラーの場合を含め、常にJSON形式で応答します。

APIは、HTTP認証やHTTP動詞などの組み込みのHTTP機能を使用します。これは、既製のHTTPクライアントによって解釈できます。また、クロスオリジンリソースシェアリングをサポートしているため、クライアントWebアプリケーションから安全にアクセスできます。

エクソラAPIは次のエンドポイントのパスを使います：

• https://api.xsolla.com — ペイステーションAPI、アドミンページAPI、サブスクリプションAPI
• https://login.xsolla.com/api — ログインAPI
• https://store.xsolla.com/api — インゲームストア&ゲームキーの直接販売API

リクエストとレスポンス

エクソーラAPIのリクエストに必要なこと：

• HTTPSで送信。
• TLS 1.2以降を使用。
• 認証パラメータを含める。
• 追加ヘッダーContent-Type: application/jsonをPUTリクエストとPOSTリクエストに含める。

Authorization: Basic <your_authorization_basic_key>
Content-Type: application/json

既定では、すべてのリクエストが本文にJSONデータを持ち、Content-Type: application/jsonヘッダーを含むレスポンスを返します。

APIの変更内容

エクソーラはAPIの機能を次のように変更することがあります：

• 新しいAPIリソースを追加する。
• オプションのリクエストパラメータを追加する。
• 既存のAPIレスポンスに新しいプロパティを追加する。
• 列挙可能な値の既存のパラメータに新しい値を追加する。
• 新しいウェブフックタイプとJSONパラメータを追加する。
• HTTPリクエストヘッダを追加する。
• 有効なパラメータに無効な値が含まれているリクエストを拒否する。
• 解析ロジックが変更された場合、寛大な構文解析のために以前に受け入れられた不適切な形式のリクエストを拒否する。
• 文書化されていない機能をいつでも追加、変更、削除することができる。

変更に関係なく、クライアントは機能し続けます。たとえば、クライアントによって認識されない新しいJSONパラメータは、通常の操作を妨げてはいけません。

バージョン管理

すべてのエクソーラAPIメソッドはバージョン管理をサポートしています。現在のバージョンと互換性のない変更があるたびに新しいバージョンを発行します。バージョンは、URLの"/merchant"接頭辞に続く"v1"や"v2"などの識別子によって識別されます。

初めてAPIを使用する場合は、最新のバージョンを使用してください。バージョンを省略すると、デフォルトで最初のバージョンが使用されます。

認証

エクソーラAPIは基本アクセス認証を採用しています。APIに対する全リクエストは、Authorization: Basic <your_authorization_basic_key>ヘッダーを含む必要があります。<your_authorization_basic_key>はマーチャントID：APIキーのペアで、Base64の基準に従ってエンコードしています。アドミンページに移動して、次のパラメータを見つけます：

• マーチャントIDは以下の場所で表示されます：
  • プロジェクト設定 > ウェブフックセクション。
  • 会社設定 > 会社セクション。
  • アドミンページページのブラウザーアドレスバーのURL。URLは以下の形式があります：https://publisher.xsolla.com/​マーチャントID/アドミンページセクション。

• APIキーは、作成時に一度だけアドミンページに表示され、お客様側で保存する必要があります。次のセクションで新しいキーを作成できます：
  • 会社設定 > APIキー
  • プロジェクト設定 > APIキー

エンドポイントの種類

日付形式

ページネーション

エラー処理

サポートされているHTTPエラーの一覧：

• 200、201、204-エラーはありません。
• 400 Bad Request-これは必要なパラメーターが欠落していることを示します。詳細については、レスポンス本文を参照してください。
• 401 Unauthorized-有効なAPIキーがありません。
• 402 Request Failed-パラメータは有効でしたがリクエストの実行に失敗しました。
• 403 Forbidden-許可されていません。詳細については、レスポンス本文を参照してください。
• 404 Not Found-要求された項目が見つかりません。
• 409、422-リクエストパラメータが無効です。
• 412 Precondition Failed —プロジェクトはまだアクティブ化されていません（トークンを作成するメソッドで使用されています）。
• 415 Unsupported Media Type-HTTPヘッダに Content-Type: application/jsonがありません。
• 500、502、503、504 Server Errors-サーバーエラーが起きました。

エクソーラは、従来のHTTPレスポンスコードを使用して、APIリクエストが成功したかどうかを示します。一般的に、2xxは成功を示し、4xxは提供された情報のエラー（例えば、必要なパラメータの欠落、認証の失敗など）を示し、5xxはエクソーラのサーバに関する問題を示します。

しかし、すべてのエラーがHTTPレスポンスコードと完全に一致するわけではありません。たとえば、リクエストが有効であったにもかかわらず失敗した場合、APIは422エラーコードを返します。

すべてのAPIエラーレスポンスは、JSONオブジェクトに次のフィールドを提供します。

{
    "http_status_code": 500,
    "message": "Internal Server Error",
    "extended_message": null,
    "request_id": "6445b85"
}

レート制限

一般情報

エクソーラシステムの過負荷を回避し、受信トラフィックのバーストからシステムを保護するために、エクソーラは、指定された期間内に エクソーラAPIによって受信されるリクエストの数を制限します。制限を超えた場合、エクソーラAPIは429ステータスコードでHTTPレスポンスを返します。

制限値は、方式、プロジェクト、その他の要因によって異なります。現在の制限値は、エクソーラシステムの安定的かつ継続的な運用を保証するために定期的に更新されます。場合によっては、事前のリクエストにより、指定された制限を調整することが可能です。カスタマーサクセスマネージャーに連絡するか、メールcsm@xsolla.comまでリクエストを送信してください。

レート制限を超える一般的な原因

• パートナー側のトラフィックが急激に増加した原因は以下通り：
  • 季節セール
  • クローズドテストとオープンテストの開始
• パートナー側でのDDoS攻撃の結果、トラフィックが急激に増加しました。
• 不適切に構成された統合。例：
  • Catalogサブセクションのメソッドの代わりに、頻繁に使用することに対応していないAdminサブセクションのメソッドを使用すること
  • 注文の状態とその中のアイテムのリストを取得するために、Get orderメソッドを頻繁に呼び出すこと。例：推奨されるリクエストの遅延時間は3秒ですが、1秒に1回呼び出されます
• 一定時間内に過剰に多くのリクエストを起動すること。例：アイテムカタログを表示するためのGet virtual items listメソッドを1秒間に200回以上呼び出すこと。

レート制限の処理

レート制限によるエラーを防ぐために、以下のことをお勧めします：

• 429ステータスコードを追跡し、再試行メカニズムを作成します。連続再試行の代わりに、再試行間に固定または指数バックオフを持つ再試行パターンを使用することができます。
• 必要なデータのみを取得するようにコードを最適化します。アプリケーションが必要とするリクエストのみを行い、不要なAPIコールを避けるようにします。IGS&BB APIを使用している場合は、WebSocket APIを使用することで呼び出し回数を減らすことができます。
• アプリケーションで頻繁に使用されるデータをキャッシュします。静的なデータを手元に置いて、外部APIへのリクエストの数を減らすことができます。
• APIを破壊するDDoS攻撃を防ぐことができます。
• リクエストのレートを調整することで、よりスムーズな配信が可能になります。429エラーが定期的に発生する場合は、リクエストのレートを調節し、リクエストをより均等に分散できるようなプロセスをコードに含めることを検討してください。

APIキー

APIキーは、ユーザーデータの暗号化およびAPIリクエストの認証に使用される一意のキーです。アドミンページでは、会社のすべてのプロジェクトと個々のプロジェクトに対してAPIキーを作成できます。

APIキーを作成する

1. アドミンページを開きます。
2. 会社設定 > APIキーまたはプロジェクト設定 > APIキーセクションに移動します。
3. APIキーを作成するをクリックします。
4. 以下のフィルドを入力します：
   • キーのリストに表示されるキーの名前。キーを簡単に識別できるような名前を設定します。
   • キーのタイプ — 永久的または一時的。
   • 有効期限 — 一時的なキーの場合のみです。有効期限を過ぎると、そのキーは無効となり、新たにキーを作成する必要があります。
   • キーが有効なプロジェクト（プロジェクトページでAPIキーを作成しても、このフィールドは表示されません）。デフォルトでは、すべてのプロジェクトが選択されています。
5. 作成するをクリックします。
6. 開いたウィンドウで、APIキーをコピーするをクリックし、作成したAPIキーを自分側で保存します。

APIキーを削除する

APIキーを削除するには：

1. アドミンページを開きます。
2. 会社設定 > APIキーまたはプロジェクト設定 > APIキーセクションに移動します。
3. APIキーの行で、ビンのアイコンをクリックし、動作を確認します。

以下の場合、APIキーの削除が中止されます：

• このAPIキーが使われたプロジェクトで支払いを受ける
• このAPIキーを使用したAPIメソッドを呼び出す

それを防ぐには：

1. 新しいAPIキーを作成します。
2. 新しいAPIキーを使用するようにアプリケーションを変更します。
3. 初期のAPIキーを削除します。

ウェブフック

ウェブフックを使用すると、エクソーラ側で構成されたイベントの即時通知を受信できます。処理用エクソーラを設定することで、アプリケーションを自動化することができます。利用可能なウェブフックのリストとその動作の詳細については、当社のドキュメンテーションを参照してください。

このページを評価する

改善できることはありますか？ 送信

答えたくない

ご意見ありがとうございました！