概览
艾克索拉API包括:
- Pay Station API — 支付UI和令牌化方法。
- IGS&BB API — 用于游戏内商店和Buy Button模块的方法。
- Subscriptions 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、Publisher Account API、Subscriptions APIhttps://login.xsolla.com/api
— Login APIhttps://store.xsolla.com/api
— IGS&BB 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密钥
关于使用API密钥的详细信息,请参阅API参考。
关于密钥的建议:
- 请在己侧保存生成的API密钥。您仅会在创建API密钥时在发布商帐户中看见它一次。
- 请妥善保管API不被泄露。它提供对您的个人帐户及您在发布商帐户中项目的访问权限。
- API密钥必须存储在您的服务器上,切勿保存在代码或前端中。
端点类型
端点类型指示其处理的数据类型以及在数据上执行的操作。最常见的操作包括:操作 | HTTP 方法 | 描述 |
---|---|---|
创建 | POST | 创建并保持对应类型的实体。 |
列示 | GET | 返回与您提供的查询参数相匹配的所有实体的汇总信息。要获取特定实体的综合信息,首先获取实体的ID以及相应的列示端点,然后向对应的检索端点提供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_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"
}
流量限制
一般信息
为避免艾克索拉系统过载及突然的流量爆发式涌入,艾克索拉会限制一定时间内艾克索拉API接收请求的数量。如超出该限制,艾克索拉API会返回一个包含状态代码429
的HTTP响应。
具体限制根据方法、项目及其他因素而变化。当前限制会定期更新以确保艾克索拉系统的稳定和不间断运行。部分情况下,我们可以根据优先请求调整当前限制。请联系您的客户成功经理或发送邮件至csm@xsolla.com提交相关请求。
超过流量限制的常见原因
- 由于以下情况在合作伙伴侧发生的流量暴增:
- 季节性销售
- 封闭及公开测试的开始阶段
- 合作伙伴侧遭受DDoS攻击造成的流量暴增。
- 未正确配置集成,例如:
- 在一段时间内发起巨量请求,例如每秒超过200次调用Get virtual items list方法来显示商品目录。
流量限制处理
为避免由流量限制引起的错误,建议:
- 跟踪
429
状态代码并创建一个重试机制。您可以使用固定延迟或指数退避重试策略,而不是连续重试。 - 优化代码来仅获取需要的数据。请确保仅发起应用程序需要的请求,避免不必要的API调用。如使用的是IGS&BB API,可使用WebSocket API来减少调用次数。
- 缓存应用程序需要频繁使用的数据。您可以将静态数据保存在己侧,从而减少向外部API发送的请求数量。
- 预防可能破坏您API的DDoS攻击。
- 调整您的请求频率以实现更平稳的分布。如
429
错误频繁发生,可考虑在代码中建立一个调整请求发送速度的过程,以便更均匀地发出。
API密钥
API密钥是用于用户数据加密和API请求身份认证的唯一密钥。在发布商帐户中,您可以为公司的全部项目或单个项目创建API密钥。
创建API密钥
要创建API密钥:- 打开发布商帐户。
- 前往公司设置 > API密钥或项目设置 > API密钥部分。
- 单击创建API密钥。
- 填写以下字段:
- 将在密钥列表中显示的密钥名称。请设置一个自己容易辨认的名称。
- 密钥类型 — 永久或临时。
- 到期日期 — 仅适用于临时密钥。超过到期时间后,密钥将不再有效,需要创建一个新密钥。
- 该密钥适用的项目(在项目页面创建API密钥时不显示此字段)。默认选择所有项目。
- 单击创建。
- 在随后打开的窗口中,单击复制API密钥并将创建的API密钥保存在己侧。

- 请在己侧保存生成的API密钥。您仅会在创建API密钥时在发布商帐户中看见它一次。
- 请妥善保管API不被泄露。它提供对您的个人帐户及您在发布商帐户中项目的访问权限。
- API密钥必须存储在您的服务器上,切勿保存在代码或前端中。
删除API密钥
要删除API密钥:
- 打开发布商帐户。
- 前往公司设置 > API密钥或项目设置 > API密钥部分。
- 在API密钥行中,点击垃圾桶图标并确认操作。
删除API密钥将停止:
- 在使用该API密钥的项目中接收付款
- 调用使用该API密钥的API方法
要防止上述情况:
- 创建新的API密钥。
- 更改应用程序让其使用新的API密钥。
- 删除原来的API密钥。
Webhooks
艾克索拉侧配置的事件发生时,Webhook可让您立即收到事件通知。您可以设置对Webhook进行自动处理实现应用程序的自动化。关于可用Webhook的列表及其功能的详细说明信息,请参阅我们的文档。
本文对您的有帮助吗?
为此页面评分
不想回答
感谢您的反馈!
发现了错别字或其他内容错误? 请选择文本,然后按Ctrl+Enter。