はじめる

概要

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

  • Pay Station API — 決済UIとトークン化メソッド。
  • Commerce API — ゲーム内ストアおよびBuy Buttonモジュールを操作するメソッド。
  • Subscription API — サブスクリプションのためのメソッド。
  • Publisher Account API — パブリッシャーアカウントのプロジェクトとユーザー、レポート、サポートチケットを操作するメソッド。
  • Login API — 独自のインターフェースを使用したユーザー認証のためのメソッド(統合ガイドを参照してください)。

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

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

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

  • https://api.xsolla.com — Pay Station API、Commerce API、Publisher Account API
  • https://login.xsolla.com/api — Login API
ほとんどのエンドポイントのパスには、merchant_idパラメーターが含まれています。これは、アプリケーションが出品者のために機能していることを示します。

リクエストとレスポンス

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

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

Copy
Full screen
Small screen
    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は基本アクセス認証を採用しています。APIに対する全リクエストは、Authorization: Basic <your_authorization_basic_key>ヘッダーを含む必要があります。<your_authorization_basic_key>merchant_id:api_keyのペアで、Base64の基準に従ってエンコードしています。

    エクソラのパブリッシャーアカウントを開いてパラメータmerchant_idapi_keyの値をご確認ください:

    • merchant_id:会社設定>会社>マーチャントID
    • api_key:会社設定>APIキー

    注意
    • APIキーを秘密にしてください。これにより、個人アカウントおよびパブリッシャーアカウントのプロジェクトにアクセスできます。
    • APIキーを変更すると、すべてのプロジェクトへの支払いが停止する場合があります。現在のキーを使用するAPI呼び出しは、新しいキーで更新するまで機能しなくなります。
    Copy
    Full screen
    Small screen
    http
    • http
    • curl
    • php
    • C#
    • python
    • ruby
    • java
    • js
    GET https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages
    Headers:
      Authorization: Basic <your_authorization_basic_key>
    curl --request GET \
    --url 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages' \
    --header 'authorization: Basic <your_authorization_basic_key>'
    <?php
    
    // if you use Xsolla SDK for PHP
    use Xsolla\SDK\API\XsollaClient;
    $xsollaClient = XsollaClient::factory(array(
        'merchant_id' => MERCHANT_ID,
        'api_key' => API_KEY
    ));
    $eventsList = $client->ListEvents(array());
    
    // if you don’t use Xsolla SDK for PHP
    $client = new http\Client;
    $request = new http\Client\Request;
    
    $request->setRequestUrl('https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages');
    $request->setRequestMethod('GET');
    $request->setHeaders(array(
      'authorization' => 'Basic <your_authorization_basic_key>'
    ));
    
    $client->enqueue($request)->send();
    $response = $client->getResponse();
    
    echo $response->getBody();
    
    var client = new RestClient("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages");
    var request = new RestRequest(Method.GET);
    request.AddHeader("authorization", "Basic <your_authorization_basic_key>");
    IRestResponse response = client.Execute(request);
    
    import http.client
    
    conn = http.client.HTTPSConnection("api.xsolla.com")
    
    headers = { 'authorization': "Basic <your_authorization_basic_key>" }
    
    conn.request("GET", "/merchant/v2/merchants/{merchant_id}/events/messages", headers=headers)
    
    res = conn.getresponse()
    data = res.read()
    
    print(data.decode("utf-8"))
    require 'uri'
    require 'net/http'
    
    url = URI("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages")
    
    http = Net::HTTP.new(url.host, url.port)
    http.use_ssl = true
    http.verify_mode = OpenSSL::SSL::VERIFY_NONE
    
    request = Net::HTTP::Get.new(url)
    request["authorization"] = 'Basic <your_authorization_basic_key>'
    
    response = http.request(request)
    puts response.read_body
    OkHttpClient client = new OkHttpClient();
    
    Request request = new Request.Builder()
      .url("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages")
      .get()
      .addHeader("authorization", "Basic <your_authorization_basic_key>")
      .build();
    
    Response response = client.newCall(request).execute();
    var data = null;
    
    var xhr = new XMLHttpRequest();
    xhr.withCredentials = true;
    
    xhr.addEventListener("readystatechange", function () {
      if (this.readyState === this.DONE) {
        console.log(this.responseText);
      }
    });
    
    xhr.open("GET", "https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages");
    xhr.setRequestHeader("authorization", "Basic <your_authorization_basic_key>");
    
    xhr.send(data);
    

    エンドポイントの種類

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

    アクションHTTPメソッド説明文
    作成POST指定されたタイプのエンティティを作成して保存します。
    リストGETクエリに一致するエンティティのリストを返します。エンティティの詳細を取得するには、最初に対応するリストのエンドポイントを使用してそのIDを見つけ、このIDを対応する取得のエンドポイントに提供します。
    取得GET指定されたIDを持つエンティティの詳細を提供します。
    置換PUT指定されたIDを持つエンティティのすべてのフィールドを変更します。
    更新PATCH指定されたIDを持つエンティティの指定されたフィールドを変更します。
    削除DELETE指定されたIDを持つエンティティを削除します。

    日付形式

    すべての日付は、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-サーバーエラーが起きました。

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

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

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

    名前種類説明文
    http_status_codeintegerHTTPコード。
    messagestring人間が判読できるエラーの説明。このメッセージは常に英語で表示されます。将来的に変更される可能性があるため、特定のエラーのためにこの値に頼らないでください。
    extended_messagestringより詳細なエラーの説明。
    request_idstringトラブルシューティングに使用する固有のリクエストID。
    Copy
    Full screen
    Small screen
    {
        "http_status_code": 500,
        "message": "Internal Server Error",
        "extended_message": null,
        "request_id": "6445b85"
    }

    ウェブフック

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

    この記事は役に立ちましたか?
    ありがとうございます!
    改善できることはありますか? メッセージ
    申し訳ありません
    この記事が参考にならなかった理由を説明してください。 メッセージ
    ご意見ありがとうございました!
    あなたのメッセージを確認し、体験を向上させるために利用させていただきます。
    このページを評価する
    このページを評価する
    改善できることはありますか?

    答えたくない

    ご意見ありがとうございました!
    最終更新日: 2021年8月16日

    誤字脱字などのテキストエラーを見つけましたか? テキストを選択し、Ctrl+Enterを押します。