はじめる

概要

エクソーラのAPIには以下が含まれます：

• Pay Station API — 決済UIとトークン化メソッド。
• Shop Builder API — ショップビルダーモジュールを使用するためのメソッド。
• Subscriptions API — サブスクリプションのためのメソッド。
• Login API — 独自のインターフェースを使用したユーザー認証のためのメソッド（統合ガイドを参照してください）。

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

• https://api.xsolla.com — Pay Station API、Subscriptions API
• https://login.xsolla.com/api — Login API
• https://store.xsolla.com/api — Shop Builder API

リクエストとレスポンス

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

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

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

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

APIの変更内容

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

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

バージョン管理

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

認証

エクソーラAPIは、次の認証タイプを使用します：

• 基本アクセス認証。このようなAPIへのリクエストには、Authorization: Basic <your_authorization_basic_key>ヘッダーを含める必要があります。ここで、<your_authorization_basic_key>はBase64標準に従ってエンコードされたマーチャントID：APIキーペアです。パブリッシャーアカウントに移動して、以下のパラメータを見つけます：
  • マーチャントIDが表示されます：
    • 会社設定 > 会社セクションにあります。
    • 任意のパブリッシャーアカウントのブラウザのアドレスバーにあるURL。URLの形式は以下の通り：https://publisher.xsolla.com/<merchant_ID>/。
  • APIキーは、作成時に一度だけパブリッシャーアカウントに表示され、お客様側で保存する必要があります。次のセクションで新しいキーを作成できます：
    • 会社設定＞APIキー。
    • プロジェクト設定 > APIキー。
• ユーザーJWTを使用した認証。APIへのこのようなリクエストには、Authorization: Bearer <user_JWT>ヘッダーが含まれている必要があります。そこで、<user_JWT>はユーザートークンです。
• サーバーJWTを使用した認証。このようなAPIメソッドには、X-SERVER-AUTHORIZATION: <server_JWT>ヘッダーが含まれている必要があります。そこで、<server_JWT>はサーバートークンです。
• 認証なし。

相互作用モデルによるAPIコール

エクソーラAPI経由でエクソーラ製品を統合する場合、APIコールを使用目的に応じて使用することが重要です：

• クライアント側のAPIコール — パートナーのアプリケーションのクライアント部分とエクソーラサーバー間の相互作用のためのAPIコール。クライアントのユーザーアクションによって、これらのAPIコールのリクエストが開始されます。クライアント側APIコールの例：アイテムのリストを取得する、ユーザー認証、クライアントの決済トークンを取得する。
• サーバー側のAPIコール — パートナーのサーバーとエクソーラサーバー間の相互作用のためのAPIコール：
  • ユーザーフローの実装。
    クライアント上のユーザーアクションがパートナーのクライアントサイドAPIコールの呼び出しをトリガーし、エクソーラサーバーサイドAPIコールがパートナーのサーバー上で呼び出されます。ユーザーフローを実装するためのサーバーAPIコールの例：サーバーのユーザー属性を更新する、サーバー上で決済トークンを取得する。
  • 管理タスク、またはパートナーによるエクソーラ製品のセットアップ。
    クライアントのユーザーアクションはこれらのメソッドの呼び出しを開始できません。管理者サーバーAPIコールの例：アイテムやプロモーションの作成と編集。

• レート制限を超える場合：
  • サーバー側APIコールのレート制限は、クライアント側APIコールよりも厳しい。
  • 管理者のサーバーサイドAPIコールのレート制限は、ユーザーフロー実装APIコールよりも厳しくなります。
• 応答で無関係な情報を受け取ります。例えば、クライアントサイドでアイテムリストを取得してカタログを作るAPIコールの代わりに、サーバーサイドで管理者用のアイテムリストを取得するAPIコールを使う場合。
• ユーザーによる不正なデータ変更。例えば、サーバー側のAPIコールではなく、クライアント側のAPIコールを使って属性を更新した場合。
• 決済UIでの国と通貨の決定が正しくありません。

認証スキームによって、APIコールがクライアント側かサーバー側かを判断できます：

• クライアントサイド—認証なしまたはAuthorization header: Bearer <user_JWT>ヘッダーで呼び出されます。<user_JWT>はユーザートークンです。
• ユーザーフローを実装するためのサーバーサイドAPIコール — は以下のヘッダーで呼び出されます：
  • X-SERVER-AUTHORIZATION: <server_JWT>の中で、<server_JWT>はサーバートークン。
  • Authorization: Basic <your_authorization_basic_key>の中で、<your_authorization_basic_key>はproject_id:api_keyペアはBase 64標準に従ってエンコードされます。
• 管理タスクのサーバーサイドAPIコール — Authorization: Basic <your_authorization_basic_key>ヘッダーで呼び出されます。<your_authorization_basic_key> — project_id:api_keyペアはBase 64標準に従ってエンコードされます。

サーバーサイド認証を使用したサーバーサイドAPIコールの例：

クライアント側認証を使用したクライアント側APIコールの例：

要件に応じて、ユーザーフローを実装する際に、サーバー側またはクライアント側のAPIコールで統合を設定する方法を選択できます。サーバー管理APIコールはユーザーフローの実装に使用しないでください。

クライアント側のAPIコールを使用したユーザーフローの実装例：

1. ユーザーはクライアント上でアクションを実行します。例：カートに入れる、商品を購入する。
2. ゲームクライアントはデータを含むリクエストをエクソーラサーバーに送信します。
3. エクソーラサーバーはゲームクライアントに応答を送信します。
4. ゲームクライアントは結果をユーザーに表示します。

このフローでは、ユーザJWT経由での認証が使用されます。

サーバー側のAPIコールを使用したユーザーフローの実装例：

1. ユーザーはクライアント上でアクションを実行します。例：カートに入れる、商品を購入する。
2. ゲームクライアントはゲームサーバーにリクエストを送信します。
3. 必要に応じて、パートナーはゲームサーバーに追加のデータ処理を実装します。
4. ゲームサーバーはエクソーラサーバーにリクエストを送信します。
5. エクソーラサーバーはゲームサーバーに応答を送信します。
6. ゲームサーバーはデータを処理し、ゲームクライアントに応答を送信します。
7. ゲームクライアントは結果をユーザーに表示します。

このフローでは、基本アクセス認証またはサーバートークンが使用されます。

サーバーサイド管理のAPIコールを使用する際の相互作用フロー：

1. パートナーは、アプリケーションのクライアントまたはサーバーからエクソーラサーバーにリクエストを送信します。
2. エクソーラサーバーはリクエストの処理結果を応答として返します。

エンドポイントの種類

エンドポイントのタイプは、どのような種類のデータを処理するのか、どのような処理を実行するのかを示します。最も一般的なアクションは次のとおりです。

日付形式

すべての日付は、ISO 8601に従って文字配列として指定されます。日付文字配列は、UTC（例：2013-01-15T00:00:00Z）、またはUTCオフセット（例えばUTC+8の場合、2013-01-15T00:00:00-08:00）を指定できます。後者の場合は、夏時間を考慮してください。

ページネーション

リストのエンドポイントは、返された結果にページ区切りを付けることがあります。つまり、すべての結果を単一のレスポンスで返す代わりに、これらのエンドポイントは結果の一部と、次の結果セットにリンクするレスポンスヘッダを返す可能性があります。この目的のために、offsetトlimitのパラメータを使用します。

エラー処理

サポートされている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-サーバーエラーが起きました

1{
2    "http_status_code": 500,
3    "message": "Internal Server Error",
4    "extended_message": null,
5    "request_id": "6445b85"
6}

レート制限

一般情報

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

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

レート制限の処理

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

APIキー

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メソッドを呼び出す

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

ウェブフック

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