概览

艾克索拉API包括：

• Pay Station API — 支付UI和令牌化方法。
• IGS API — 用于游戏内商店模块的方法。
• Subscriptions API — 用于订阅的方法。
• Login API — 使用自有界面认证用户的方法（请参阅集成指南）。

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

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

请求和响应

• 通过HTTPS发送，
• 使用TLS 1.2或更高版本，
• 包含认证参数，
• 对于PUT和POST请求额外包含一个头：Content-Type: application/json。

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

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

API变更

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

版本控制

身份验证

• 商户ID在以下位置显示：
  • 在公司设置 > 公司部分。
  • 在发布商帐户任意页面的浏览器地址栏的URL中。URL的格式如下：https:​//publisher.xsolla.com/<merchant ID>/<Publisher Account section>。

• API密钥仅在创建它时在发布商帐户中显示一次，必须存储在己侧。您可以在以下部分中创建新的密钥：
  • 公司设置 > API密钥
  • 项目设置 > API密钥

按交互模式分类的API调用

• 客户端侧API调用 — 用于在合作伙伴应用程序客户端部分和艾克索拉服务器之间交互的API调用。用户在客户端上的操作会发起这些API调用。客户端侧API调用示例：获取商品列表、用户身份认证、在客户端上获取支付令牌。
• 服务器侧API调用 — 用于在合作伙伴服务器和艾克索拉服务器之间交互的API调用，主要用于以下任务：
  • 实现用户流程。
    用户在客户端上的操作会触发合作伙伴客户端侧API调用，然后合作伙伴服务器上的艾克索拉服务器侧API调用会被触发。实现用户流程的服务器API调用示例：更新服务器上的用户属性、在服务器上获取支付令牌。
  • 管理类任务，或合作伙伴要对艾克索拉产品进行设置。
    客户端上的用户操作不能发起对这些方法的调用。管理员服务器API调用示例：创建及编辑商品或促销活动。

• 超出流量限制：
  • 服务器侧API调用的流量限制比客户端侧API调用的流量限制更严格。
  • 管理员服务器侧API调用的流量限制比实现用户流程的API调用的流量限制更严格。
• 在响应中收到不相关的信息。例如，使用了用于管理员的服务器侧获取商品列表API调用而不是客户端侧获取商品列表API调用来创建目录。
• 用户侧未授权的数据更改。例如使用了客户端侧API调用而不是服务器侧API调用来更新属性。
• 支付界面上不正确的国家/地区和货币判断。

您可以按照身份认证机制来判断一个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>是根据Base64标准编码的project_id:api_key对。
• 用于管理类任务的服务器侧API调用 — 通过Authorization: Basic <your_authorization_basic_key>头来调用，其中<your_authorization_basic_key>是根据Base64标准编码的project_id:api_key对。

使用服务器侧身份认证的服务器侧API调用示例：

使用客户端侧身份认证的客户端侧API调用示例：

根据自身要求，您可以选择在实现用户流程时如何设置集成——使用服务器侧或客户端侧API调用。不应使用服务器管理类API调用来实现用户流程。

使用客户端侧API调用的用户流程实现示例：

1. 用户在客户端上进行了操作，例如：商品加入购物车、下单等。
2. 游戏客户端向艾克索拉服务器发送包含数据的请求。
3. 艾克索拉服务器向游戏客户端发送响应。
4. 游戏客户端向用户显示结果。

此流程中使用了通过用户JWT进行身份认证。

使用服务器侧API调用的用户流程实现示例：

1. 用户在客户端上进行了操作，例如：商品加入购物车、下单等。
2. 游戏客户端向游戏服务器发送请求。
3. 如需要，合作伙伴可以在游戏服务器上实现更多数据处理。
4. 游戏服务器向艾克索拉服务器发送请求。
5. 艾克索拉服务器向游戏服务器发送响应。
6. 游戏服务器处理数据并向游戏客户端发送响应。
7. 游戏客户端向用户显示结果。

此流程中使用了基本认证或服务器令牌。

使用服务器侧管理员API调用时的交互流程：

1. 合作伙伴从其应用程序的客户端或服务器向艾克索拉服务器发送请求。
2. 艾克索拉服务器返回包含请求处理结果的响应。

端点类型

日期格式

分页

错误处理

• 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_status_code": 500,
    "message": "Internal Server Error",
    "extended_message": null,
    "request_id": "6445b85"
}

流量限制

一般信息

超过流量限制的常见原因

• 由于以下情况在合作伙伴侧发生的流量暴增：
  • 季节性销售
  • 封闭及公开测试的开始阶段
• 合作伙伴侧遭受DDoS攻击造成的流量暴增。
• 未正确配置集成，例如：
  • 使用了本不应频繁使用的Admin子部分下的方法，而没有使用Catalog子部分下的方法
  • 频繁调用Get order方法来获取订单状态及其中的商品列表，例如一秒一次，而不是按照推荐的请求间3秒间隔来调用
• 在一段时间内发起巨量请求，例如每秒超过200次调用Get virtual items list方法来显示商品目录。

流量限制处理

• 跟踪429状态代码并创建一个重试机制。您可以使用固定延迟或指数退避重试策略，而不是连续重试。
• 优化代码来仅获取需要的数据。请确保仅发起应用程序需要的请求，避免不必要的API调用。如使用的是IGS 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密钥

1. 打开发布商帐户。
2. 前往公司设置 > API密钥或项目设置 > API密钥部分。
3. 在API密钥行中，点击垃圾桶图标并确认操作。

• 在使用该API密钥的项目中接收付款
• 调用使用该API密钥的API方法

1. 创建新的API密钥。
2. 更改应用程序让其使用新的API密钥。
3. 删除原来的API密钥。

Webhooks

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