入门

概览

艾克索拉API包括:

艾克索拉API使用REST架构。该API拥有面向资源的可预测URL,并使用HTTP响应代码来指示API错误。API始终以JSON格式响应(包括发生错误时)。

我们使用HTTP身份验证和HTTP动词等内置HTTP功能(这些功能可被现行HTTP客户端理解),并且我们支持跨域资源共享,使您可以从客户端Web应用程序与我们的API进行安全交互。

艾克索拉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或更高版本,
  • 包含认证参数,
  • 对于PUT和POST请求额外包含一个头:Content-Type: application/json

Copy
Full screen
Small screen
    Authorization: Basic <your_authorization_basic_key>
    Content-Type: application/json

    默认情况下,所有请求均返回一个正文中包含JSON数据、头中包含Content-Type: application/json的响应。

    API变更

    艾克索拉可能使用此API更改功能:

    • 艾克索拉可能添加新的API资源;
    • 艾克索拉可能添加可选的请求参数;
    • 艾克索拉可能向现有API响应添加新属性;
    • 艾克索拉可能向已枚举值集合的现有参数添加新值;
    • 艾克索拉可能添加新的webhook类型并将新参数添加到JSON;
    • 艾克索拉可能添加可选的HTTP请求头部;
    • 艾克索拉可能拒绝任何有效参数包含无效参数值的请求;
    • 如解析逻辑被更正,则由于过度宽松的解析而被接受的不正确请求可能被拒绝
    • 艾克索拉可能随时添加、更改或删除未记录的功能。

    您的客户端应保持正常工作状态,而不应受到这些更改的影响。例如,您的客户端无法识别的新JSON参数,但这不会影响其正常工作的能力。

    版本控制

    所有艾克索拉 API方法支持版本控制。当存在与当前版本不兼容的改动时,我们将发布一个新版本。可根据URL中"/merchant"前缀后面的"v1"/"v2"/等来识别版本。

    如果首次使用API,请使用最新版本。如果忽略了版本,我们将默认使用第一个版本。

    Info: 请注意,我们只保证同一版本中的API完整性。

    身份验证

    艾克索拉API使用基本认证。所有发送到API的请求必须包含Authorization: Basic <your_authorization_basic_key>头,其中<your_authorization_basic_key>是按照Base64标准加密的merchant_id:api_key对。

    艾克索拉发布商帐户中找到merchant_idapi_key参数的值:

    • merchant_id:公司设置 > 公司 > 商户ID
    • api_key:公司设置 > API密钥

    Notice:
    • 请妥善保管您的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以及相应的“List”端点,然后向对应的“Retrieve”端点提供ID。
    检索GET提供与您提供的标识符相匹配的单个实体的综合信息。
    替换PUT修改与您提供的标识符相匹配的现有实体的所有字段。
    更新PATCH仅修改与您提供的标识符相匹配的现有实体的指定字段。
    删除DELETE删除与您提供的标识符相匹配的现有实体。

    日期格式

    所有日期表示都是ISO 8601格式的字符串。可以提供UTC日期字符串(例如2013-01-15T00:00:00Z)或者用于指示时区的UTC时区偏差日期字符串(例如2013-01-15T00:00:00-08:00表示比UTC时间晚八小时)。如果提供时区偏差日期,需确保根据情况正确计算夏时令时间。

    分页

    List端点可能会将返回的结果进行分页。也就是说,这些端点可能只会返回一部分结果,另外提供一个能够链接到下一组结果的响应头,而不是在一个响应中返回所有结果。为此,我们使用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 - Content-Type: application/json HTTP 标头未发送。
    • 500、502、503、504 Server errors - 发生错误。

    艾克索拉使用传统HTTP响应代码指示API请求是成功还是失败。通常,2xx范围内的代码指示请求成功,4xx范围内的代码指示提供的信息导致错误(例如必要参数缺失、身份验证失败等),5xx范围内的代码指示艾克索拉服务器出现错误。

    不过,也不是所有错误都能明确地反映到HTTP响应代码中。不过,也不是所有错误都能明确地反映到HTTP响应代码中。如果请求有效但未成功完成,将返回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"
    }

    Webhooks

    艾克索拉侧配置的事件发生时,Webhook可让您立即收到事件通知。您可以设置对Webhook进行自动处理实现应用程序的自动化。关于可用Webhook的列表及其功能的详细说明信息,请参阅我们的文档

    本文对您的有帮助吗?
    谢谢!
    我们还有其他可改进之处吗? 留言
    非常抱歉
    请说明为何本文没有帮助到您。 留言
    感谢您的反馈!
    我们会查看您的留言并运用它改进用户体验。
    为此页面评分
    为此页面评分
    我们还有其他可改进之处吗?

    不想回答

    感谢您的反馈!
    上次更新时间: 2021年8月16日

    发现了错别字或其他内容错误? 请选择文本,然后按Ctrl+Enter。