Введение

Xsolla API включает в себя:

• Pay Station API — платежный интерфейс и методы токенизации.
• IGS API — методы для работы с модулем In-Game Store.
• Subscriptions API — методы для подписок.
• Login API — методы аутентификации пользователей через собственный интерфейс (см. руководство по интеграции).

Мы используем встроенные особенности HTTP, такие как HTTP аутентификация и HTTP методы, которые понимаются всеми HTTP клиентами, также мы поддерживаем CORS (Cross-origin resource sharing) для обеспечения безопасной работы с 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 и выше;
• содержать параметры аутентификации;
• содержать дополнительный заголовок Content-Type: application/json для запросов типа PUT и POST.

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

По умолчанию все запросы возвращают ответ в виде JSON с заголовком Content-Type: application/json.

Изменения API

• Добавлять новые ресурсы API;
• Добавлять необязательные параметры запроса;
• Добавлять новые свойства к существующим ответам API;
• Добавлять новые значения для параметров, имеющих перечисление возможных значений;
• Добавлять новые типы вебхуков и новые параметры в JSON;
• Добавлять необязательные заголовки в HTTP-запросы;
• Отклонять любой запрос, если его параметры принимают недопустимые значения;
• Ошибочно сформированные запросы могут быть приняты из-за избыточно мягкого анализа синтаксиса. В будущем, если проверка будет более строгой, подобные запросы могут быть отклонены;
• Добавлять, изменять или удалять незадокументированные функциональные возможности в любое время.

Версионирование

Аутентификация

• Базовая HTTP-аутентификация. Такие запросы к API должны содержать заголовок Authorization: Basic <your_authorization_basic_key<, где <your_authorization_basic_key> — пара ID продавца:ключ API, закодированная по стандарту Base64. Значения параметров вы можете найти в Личном кабинете:
  • ID продавца указан:
    • В разделе Настройки компании > Компания.
    • Aдресной строке браузера на любой странице Личного кабинета. 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 по модели взаимодействия

• Клиентские методы — методы для взаимодействия между клиентской частью приложения партнера и сервером Xsolla. Действия пользователя на клиенте инициируют вызов этих методов. Пример клиентских методов: получение списка товаров, аутентификация пользователей, получение платежного токена на клиенте.
• Серверные методы — методы для взаимодействия между сервером партнера и сервером Xsolla, которые предназначены для следующих задач:
  • Реализация сценария пользователя.
    Действия пользователя на клиенте инициируют вызов клиентского метода партнера, затем на сервере партнера вызывается серверный метод Xsolla API. Пример серверных методов для реализации сценария пользователя: обновление атрибутов пользователя на сервере, получение платежного токена на сервере.
  • Административные задачи, настройка партнером продуктов Xsolla.
    Действия пользователя на клиенте не могут инициировать вызов этих методов. Пример серверных методов администратора: создание и редактирование товара или акции.

• Превышение ограничений частоты запросов:
  • Ограничения для серверных методов строже, чем для клиентских.
  • Ограничения для серверных методов администратора строже, чем для методов реализации сценария пользователя.
• Получение нерелевантной информации в ответе. Например, при использовании серверных методов получения списка товаров для администратора вместо клиентских методов получения списка товаров для построения каталога.
• Несанкционированное изменение данных пользователями. Например, при использовании для обновления атрибутов клиентских методов вместо серверных.
• Неправильное определение страны и валюты в платежном интерфейсе.

Вы можете определить, является метод клиентским или серверным, по способу аутентификации:

• Клиентские — методы, которые вызываются без аутентификации или с заголовком Authorization header: Bearer <user_JWT>, где <user_JWT>, где — это токен пользователя.
• Серверные методы для реализации сценария пользователя — методы, которые вызываются с заголовком:
  • X-SERVER-AUTHORIZATION: <server_JWT>, где <server_JWT> — это серверный токен.
  • Authorization: Basic <your_authorization_basic_key>, где <your_authorization_basic_key> — пара , project_id:api_key закодированная в соответствии со стандартом Base64.
• Серверные методы для административных задач — методы, которые вызываются с заголовком Authorization: Basic <your_authorization_basic_key>, где <your_authorization_basic_key> — пара project_id:api_key, закодированная в соответствии со стандартом Base64.

Пример метода с серверной аутентификацией:

Пример метода с клиентской аутентификацией:

В зависимости от ваших требований вы можете выбрать, как настроить интеграцию при реализации сценария пользователя — с серверными или клиентскими методами. Серверные методы администратора не должны использоваться для реализации сценария пользователя.

Пример реализации сценария пользователя с использованием клиентских методов:

1. Пользователь выполняет действия на клиенте игры. Например, наполняет корзину, совершает покупку товара.
2. Клиент игры отправляет запрос с данными на сервер Xsolla.
3. Cервер Xsolla отправляет ответ клиенту игры.
4. Клиент игры отображает результат пользователю.

В этом сценарии используется аутентификация по JWT пользователя.

Пример реализации сценария пользователя при использовании серверных методов:

1. Пользователь выполняет действия на клиенте игры. Например, наполняет корзину, совершает покупку товара.
2. Клиент игры отправляет запрос на сервер игры.
3. При необходимости на сервере игры партнер реализует дополнительную обработку данных.
4. Сервер игры отправляет запрос на сервер Xsolla.
5. Cервер Xsolla отправляет ответ серверу игры.
6. Сервер игры обрабатывает данные и отправляет ответ клиенту игры.
7. Клиент игры отображает результат пользователю.

В этом сценарии используется базовая HTTP-аутентификация или серверный токен.

Сценарий взаимодействия при использовании серверных методов для административных задач:

1. Партнер отправляет запрос со своего сервера на сервер Xsolla.
2. Cервер Xsolla возвращает ответ с результатом обработки запроса.

Команды управления ресурсами

Формат даты

Постраничная навигация

Типы ошибок

• 200, 201, 204 — Успешный ответ.
• 400 Bad Request — Отсутствует обязательный параметр. Полное описание можно найти в теле ответа.
• 401 Unauthorized — Недействительный ключ API.
• 402 Request Failed — Параметры верны, но запрос не прошел.
• 403 Forbidden — Нет прав доступа. Полное описание можно найти в теле ответа.
• 404 Not Found — Соответствующего ресурса нет по данному URI.
• 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;
  • слишком частый вызов метода Получение заказа для получения статуса заказа и списка товаров в нем – 1 раз в секунду, когда рекомендуемая задержка между запросами составляет 3 секунды.
• Запуск чрезмерно большого количества запросов за определенный период. Например: вызов метода Получение списка виртуальных предметов для отображения каталога товаров в количестве более 200 запросов в секунду.

Управление ограничениями

• Отслеживать коды состояния 429 и создать механизм повторных попыток. Вместо непрерывных повторных попыток вы можете использовать паттерн Retry с фиксированными или экспоненциальными задержками между попытками.
• Оптимизировать код для получения только необходимых данных. Убедитесь, что вы выполняете только те запросы, которые требуются вашему приложению, и исключите любые ненужные вызовы API. Если вы используете IGS API, уменьшить количество вызовов можно при помощи WebSocket API.
• Кешировать данные, которые часто используются вашим приложением. Вы можете сохранить статические данные на своей стороне и уменьшить количество запросов к внешнему API.
• Предотвращать DDoS-атаки, которые могут вывести из строя ваш API.
• Регулировать скорость ваших запросов для более плавного распределения. Если ошибка 429 возникает регулярно, рассмотрите возможность включения в свой код процесса, который регулирует скорость ваших запросов и позволяет распределять их более равномерно во времени.

Ключи API

Ключ API — это уникальный ключ, который используется для шифрования данных пользователей и аутентификации API запросов. В Личном кабинете вы можете создать ключи API как для всех проектов компании, так и для отдельного проекта.

Создание ключей API

1. Откройте Личный кабинет.
2. Перейдите в раздел Настройки компании > API ключи или Настройки проекта > API ключи.
3. Нажмите Создать API ключ.
4. Заполните поля:
   • Название ключа, которое будет отображаться в списке ключей. Задайте название, которое позволит легко идентифицировать ключ.
   • Тип ключа — постоянный или временный.
   • Срок действия — только для временного ключа API. После истечения срока действия временный ключ станет недействительным и вам необходимо будет создать новый ключ.
   • Проект, в котором будет действовать ключ (поле не отображается, если вы создаете ключ API из настроек проекта). По умолчанию выбраны все проекты.
5. Нажмите Создать.
6. В открывшемся окне нажмите Скопировать API ключ и сохраните созданный ключ API на вашей стороне.

Удаление ключей API

1. Откройте Личный кабинет.
2. Перейдите в раздел Настройки компании > API ключи или Настройки проекта > API ключи.
3. В строке ключа API нажмите значок корзины и подтвердите действие.

• прием платежей в проектах, в которых используется этот ключ API;
• выполнение вызовов API, которые используют этот ключ API.

1. Создайте новый ключ API.
2. Переведите ваше приложение на новый ключ API.
3. Удалите первоначальный ключ API.

Вебхуки

Вебхук — это механизм моментального оповещения вашей системы о событиях на стороне Xsolla. Настройте обработку вебхуков для автоматизации вашего приложения. Полный список вебхуков и механизм их работы описаны в документации.