概览

艾克索拉API包括：

• Pay Station API — 支付UI和令牌化方法。
• IGS&BB API — 用于游戏内商店和Buy Button模块的方法。
• Subscription API — 用于订阅的方法。
• Publisher Account API — 发布商帐户项目管理及用户管理，以及用于报告、支持工单的方法。
• Login API — 使用自有界面认证用户的方法（请参阅集成指南）。

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

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

艾克索拉API使用以下端点路径：

• https://api.xsolla.com — Pay Station API、IGS&BB API、Publisher Account API
• https://login.xsolla.com/api — Login API

请求和响应

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

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

版本控制

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

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

身份验证

艾克索拉API使用基本认证。所有发送到API的请求必须包含Authorization: Basic <your_authorization_basic_key>头，其中<your_authorization_basic_key>是按照Base64标准加密的商户ID: API密钥对。请前往发布商帐户找到以下参数：

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

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

端点类型

日期格式

分页

错误处理

受支持的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_code": 500,
    "message": "Internal Server Error",
    "extended_message": null,
    "request_id": "6445b85"
}

流量限制

一般信息

为避免艾克索拉系统过载及突然的流量爆发式涌入，艾克索拉会限制一定时间内艾克索拉API接收请求的数量。如超出该限制，艾克索拉API会返回一个包含状态代码429的HTTP响应。

具体限制根据方法、项目及其他因素而变化。当前限制会定期更新以确保艾克索拉系统的稳定和不间断运行。部分情况下，我们可以根据优先请求调整当前限制。请联系您的帐户经理或发送邮件至am@xsolla.com提交相关请求。

超过流量限制的常见原因

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

流量限制处理

为避免由流量限制引起的错误，建议：

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

要删除API密钥：

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

删除API密钥将停止：

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

要防止上述情况：

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

Webhooks

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

为此页面评分

我们还有其他可改进之处吗？ 发送

不想回答

感谢您的反馈！