入门

概览

艾克索拉API包括:

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

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

艾克索拉API使用以下端点路径:
  • https://api.xsolla.com — Pay Station API、Subscriptions API
  • https://login.xsolla.com/api — Login API
  • https://store.xsolla.com/api — IGS 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,请使用最新版本。如果忽略了版本,我们将默认使用第一个版本。
    注:
    请注意,我们只保证同一版本中的API完整性。

    身份验证

    Xsolla API使用以下身份认证类型:
    • 基本访问身份认证。此类对API的请求必须包含Authorization: Basic <your_authorization_basic_key<标头,其中<your_authorization_basic_key>是按照Base64标准编码的商户ID:API密钥对。前往发布商帐户找到以下参数:
      • 商户ID在以下位置显示:
        • 公司设置 > 公司部分。
        • 在发布商帐户任意页面的浏览器地址栏的URL中。URL的格式如下:https:​//publisher.xsolla.com/<merchant ID>/<Publisher Account section>
      • API密钥仅在创建它时在发布商帐户中显示一次,必须存储在己侧。您可以在以下部分创建新的密钥:
        • 公司设置 > API密钥
        • 项目设置 > API密钥
    • 使用用户JWT进行身份认证。此类对API的请求必须包含Authorization: Bearer <user_JWT>标头,其中<user_JWT>是用户令牌。
    • 使用服务器JWT进行身份认证。此类API方法必须包含X-SERVER-AUTHORIZATION: <server_JWT>标头,其中<server_JWT>是服务器令牌。
    • 无需身份认证。
    注意

    关于使用API密钥的详细信息,请参阅API参考

    关于密钥的建议:

    • 请在己侧保存生成的API密钥。您仅会在创建API密钥时在发布商帐户中看见它一次。
    • 请妥善保管API不被泄露。它提供对您的个人帐户及您在发布商帐户中项目的访问权限。
    • API密钥必须存储在您的服务器上,切勿保存在代码或前端中。

    如果所需API调用不包含project_id路径参数,请使用在您公司的所有项目中都有效的API密钥来设置授权。

    按交互模式分类的API调用

    通过艾克索拉API集成艾克索拉产品时,必须按照API的设计用途来使用它们:
    • 客户端侧API调用 — 用于在合作伙伴应用程序客户端部分和艾克索拉服务器之间交互的API调用。用户在客户端上的操作会发起这些API调用。客户端侧API调用示例获取商品列表用户身份认证在客户端上获取支付令牌
    • 服务器侧API调用 — 用于在合作伙伴服务器和艾克索拉服务器之间交互的API调用,主要用于以下任务:
      • 实现用户流程。
        用户在客户端上的操作会触发合作伙伴客户端侧API调用,然后合作伙伴服务器上的艾克索拉服务器侧API调用会被触发。实现用户流程的服务器API调用示例更新服务器上的用户属性在服务器上获取支付令牌
      • 管理类任务,或合作伙伴要对艾克索拉产品进行设置。
        客户端上的用户操作不能发起对这些方法的调用。管理员服务器API调用示例创建编辑商品或促销活动。
    正确配置集成有助于避免大部分常见错误:
    • 超出流量限制
      • 服务器侧API调用的流量限制比客户端侧API调用的流量限制更严格。
      • 管理员服务器侧API调用的流量限制比实现用户流程的API调用的流量限制更严格。
    • 在响应中收到不相关的信息。例如,使用了用于管理员的服务器侧获取商品列表API调用而不是客户端侧获取商品列表API调用来创建目录。
    • 用户侧未授权的数据更改。例如使用了客户端侧API调用而不是服务器侧API调用来更新属性。
    • 支付界面上不正确的国家/地区和货币判断。
    客户端侧服务器侧
    用于用户流程的实现用于管理类任务
    交互客户端对服务器。
    请求直接从游戏客户端发送到艾克索拉服务器。
    服务器对服务器。
    请求从游戏客户端发送到游戏服务器,然后从游戏服务器发送到艾克索拉服务器。
    服务器对服务器。
    请求从合作伙伴系统的服务器发送到艾克索拉服务器。
    身份认证用户的JSON Web令牌(JWT)或无身份认证。基本认证服务器JWT基本认证。
    流量限制可承受高负载。可承受高负载。设计仅供合作伙伴使用,因此这些API调用的性能要求低并有严格的流量限制。
    用户访问API调用在客户端侧使用,从而可以快速向用户显示数据,例如商品目录或用户属性(如下单数或在游戏中的等级)。
    所有数据可在客户端代码中公开访问。
    请勿将这些API调用用于不应被用户编辑的数据,例如更新用户属性。
    API调用用于服务器之间的交互,因此用户无法访问这些数据。
    这些API调用用于操作用户不能修改的数据。
    这些API调用不用于实现用户流程。
    国家/地区和货币的决定国家/地区和货币由发送请求的客户端IP地址决定。
    因此必须在客户端侧使用这些API调用而不是从服务器端。
    国家/地区和货币由发送请求的服务器IP地址决定。

    因此必须根据所使用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. 艾克索拉服务器返回包含请求处理结果的响应。
    此流程中使用了基本认证。

    端点类型

    端点类型指示其处理的数据类型以及在数据上执行的操作。最常见的操作包括:
    操作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_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"
    }
    

    流量限制

    一般信息

    为避免艾克索拉系统过载及突然的流量爆发式涌入,艾克索拉会限制一定时间内艾克索拉API接收请求的数量。如超出该限制,艾克索拉API会返回一个包含状态代码429的HTTP响应。 具体限制根据方法、项目及其他因素而变化。当前限制会定期更新以确保艾克索拉系统的稳定和不间断运行。部分情况下,我们可以根据优先请求调整当前限制。请联系您的客户成功经理或发送邮件至csm@xsolla.com提交相关请求。

    超过流量限制的常见原因

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

    流量限制处理

    为避免由流量限制引起的错误,建议:
    • 跟踪429状态代码并创建一个重试机制。您可以使用固定延迟或指数退避重试策略,而不是连续重试。
    • 优化代码来仅获取需要的数据。请确保仅发起应用程序需要的请求,避免不必要的API调用。如使用的是IGS API,可使用WebSocket API来减少调用次数。
    • 缓存应用程序需要频繁使用的数据。您可以将静态数据保存在己侧,从而减少向外部API发送的请求数量。
    • 预防可能破坏您API的DDoS攻击。
    • 调整您的请求频率以实现更平稳的分布。如429错误频繁发生,可考虑在代码中建立一个调整请求发送速度的过程,以便更均匀地发出。

    API密钥

    API密钥是用于用户数据加密和API请求身份认证的唯一密钥。在发布商帐户中,您可以为公司的全部项目或单个项目创建API密钥。

    注:
    适用于公司全部项目的密钥不在单个项目的页面上显示。
    注意

    如您的角色是以下之一,即可操作API密钥(查看列表、创建删除):

    • 开发人员
    • 所有者

    只有项目所有者可以在发布商帐户公司设置 > 用户部分更改角色。

    创建API密钥

    要创建API密钥:
    1. 打开发布商帐户
    2. 前往公司设置 > API密钥项目设置 > API密钥部分。
    3. 单击创建API密钥
    4. 填写以下字段:
      • 将在密钥列表中显示的密钥名称。请设置一个自己容易辨认的名称。
      • 密钥类型 — 永久或临时。
      • 到期日期 — 仅适用于临时密钥。超过到期时间后,密钥将不再有效,需要创建一个新密钥。
      • 该密钥适用的项目(在项目页面创建API密钥时不显示此字段)。默认选择所有项目。
    5. 单击创建
    6. 在随后打开的窗口中,单击复制API密钥并将创建的API密钥保存在己侧。
    注:
    如在项目页面上创建API密钥,则该密钥仅对该项目有效。
    注意

    关于密钥的建议:

    • 请在己侧保存生成的API密钥。您仅会在创建API密钥时在发布商帐户中看见它一次。
    • 请妥善保管API不被泄露。它提供对您的个人帐户及您在发布商帐户中项目的访问权限。
    • API密钥必须存储在您的服务器上,切勿保存在代码或前端中。

    如果所需API调用不包含project_id路径参数,请使用在您公司的所有项目中都有效的API密钥来设置授权。

    删除API密钥

    要删除API密钥:
    1. 打开发布商帐户
    2. 前往公司设置 > API密钥项目设置 > API密钥部分。
    3. 在API密钥行中,点击垃圾桶图标并确认操作。
    删除API密钥将停止:
    • 在使用该API密钥的项目中接收付款
    • 调用使用该API密钥的API方法
    要防止上述情况:
    1. 创建新的API密钥
    2. 更改应用程序让其使用新的API密钥。
    3. 删除原来的API密钥。

    Webhooks

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

    本文对您的有帮助吗?
    谢谢!
    我们还有其他可改进之处吗? 留言
    非常抱歉
    请说明为何本文没有帮助到您。 留言
    感谢您的反馈!
    我们会查看您的留言并运用它改进用户体验。
    上次更新时间: 2024年11月18日

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