概要
エクソラ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 APIhttps://login.xsolla.com/api
— Login 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>
はmerchant_id:api_key
のペアで、Base64の基準に従ってエンコードしています。
エクソラのパブリッシャーアカウントを開いてパラメータmerchant_idとapi_keyの値をご確認ください:
- merchant_id:会社設定>会社>マーチャントID
- api_key:会社設定>APIキー
- APIキーを秘密にしてください。これにより、個人アカウントおよびパブリッシャーアカウントのプロジェクトにアクセスできます。
- APIキーを変更すると、すべてのプロジェクトへの支払いが停止する場合があります。現在のキーを使用するAPI呼び出しは、新しいキーで更新するまで機能しなくなります。
- 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_code | integer | HTTPコード。 |
message | string | 人間が判読できるエラーの説明。このメッセージは常に英語で表示されます。将来的に変更される可能性があるため、特定のエラーのためにこの値に頼らないでください。 |
extended_message | string | より詳細なエラーの説明。 |
request_id | string | トラブルシューティングに使用する固有のリクエストID。 |
- http
{
"http_status_code": 500,
"message": "Internal Server Error",
"extended_message": null,
"request_id": "6445b85"
}
ウェブフック
ウェブフックを使用すると、エクソラ側で構成されたイベントの即時通知を受信できます。処理用エクソラを設定することで、アプリケーションを自動化することができます。利用可能なウェブフックのリストとその動作の詳細については、当社のドキュメンテーションを参照してください。
この記事は役に立ちましたか?
このページを評価する
答えたくない
ご意見ありがとうございました!
誤字脱字などのテキストエラーを見つけましたか? テキストを選択し、Ctrl+Enterを押します。