Введение
Xsolla API включает в себя:
- Pay Station API — платежный интерфейс и методы токенизации.
- IGS&BB API — методы для работы с модулями In-Game Store и Buy Button.
- Subscriptions API — методы для подписок.
- Login API — методы аутентификации пользователей через собственный интерфейс (см. руководство по интеграции).
Мы используем встроенные особенности HTTP, такие как HTTP аутентификация и HTTP методы, которые понимаются всеми HTTP клиентами, также мы поддерживаем CORS (Cross-origin resource sharing) для обеспечения безопасной работы с API вашего клиентского приложения.
Xsolla API работает со следующими базовыми URL: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
Запрос и ответ
Запросы к Xsolla 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
Xsolla может изменять функциональные возможности API:- Добавлять новые ресурсы API;
- Добавлять необязательные параметры запроса;
- Добавлять новые свойства к существующим ответам API;
- Добавлять новые значения для параметров, имеющих перечисление возможных значений;
- Добавлять новые типы вебхуков и новые параметры в JSON;
- Добавлять необязательные заголовки в HTTP-запросы;
- Отклонять любой запрос, если его параметры принимают недопустимые значения;
- Ошибочно сформированные запросы могут быть приняты из-за избыточно мягкого анализа синтаксиса. В будущем, если проверка будет более строгой, подобные запросы могут быть отклонены;
- Добавлять, изменять или удалять незадокументированные функциональные возможности в любое время.
Версионирование
Все разделы Xsolla API поддерживают версионирование. Мы будем выпускать новую версию всякий раз, когда будут появляться несовместимые с текущей версией изменения. Версия обозначается ID (“v1”/“v2” и т. п.), который указывается в URL после префикса “/merchant”. Если вы начинаете работу с API, используйте самую последнюю версию. Если вы не указали версию команды, то по умолчанию будет вызвана первая версия.Аутентификация
Xsolla API использует базовую 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.
Подробная информация о работе с ключами API приведена в справочнике API.
Основные рекомендации:
- Сохраните созданный ключ API на вашей стороне. Вы можете посмотреть ключ API в Личном кабинете только один раз при его создании.
- Никому не сообщайте ваш ключ API, так как он дает доступ к управлению аккаунтом и проектами в Личном кабинете.
- Ключ API должен храниться на вашем сервере и никогда — в бинарных файлах или на фронтенде.
Если необходимый метод API не включает в себя path-параметр project_id
, используйте для авторизации ключ API, который действует во всех проектах.
Методы API по модели взаимодействия
При интеграции продуктов Xsolla через Xsolla API важно использовать методы в соответствии с их назначением:- Клиентские методы — методы для взаимодействия между клиентской частью приложения партнера и сервером Xsolla. Действия пользователя на клиенте инициируют вызов этих методов. Пример клиентских методов: получение списка товаров, аутентификация пользователей, получение платежного токена на клиенте.
- Серверные методы — методы для взаимодействия между сервером партнера и сервером Xsolla, которые предназначены для следующих задач:
- Реализация сценария пользователя.
Действия пользователя на клиенте инициируют вызов клиентского метода партнера, затем на сервере партнера вызывается серверный метод Xsolla API. Пример серверных методов для реализации сценария пользователя: обновление атрибутов пользователя на сервере, получение платежного токена на сервере. - Административные задачи, настройка партнером продуктов Xsolla.
Действия пользователя на клиенте не могут инициировать вызов этих методов. Пример серверных методов администратора: создание и редактирование товара или акции.
- Реализация сценария пользователя.
- Превышение ограничений частоты запросов:
- Ограничения для серверных методов строже, чем для клиентских.
- Ограничения для серверных методов администратора строже, чем для методов реализации сценария пользователя.
- Получение нерелевантной информации в ответе. Например, при использовании серверных методов получения списка товаров для администратора вместо клиентских методов получения списка товаров для построения каталога.
- Несанкционированное изменение данных пользователями. Например, при использовании для обновления атрибутов клиентских методов вместо серверных.
- Неправильное определение страны и валюты в платежном интерфейсе.
Клиентские методы (Client-side) | Серверные методы (Server-side) | ||
---|---|---|---|
Для реализации сценария пользователя | Для административных задач | ||
Взаимодействие | Client-to-server. Запрос отправляется с клиента игры на сервер Xsolla. | Server-to-server. Запрос отправляется с клиента игры на сервер игры, затем с сервера игры на сервер Xsolla. | Server-to-server. Запрос отправляется с сервера партнера на сервер Xsolla. |
Аутентификация | JSON web token (JWT) пользователя или без аутентификации. | Базовая HTTP-аутентификация или серверный JWT. | Базовая HTTP-аутентификация. |
Ограничения частоты запросов | Могут выдерживать высокую нагрузку. | Могут выдерживать высокую нагрузку. | Предназначены для использования только партнером, поэтому у этих методов низкие требования к производительности и строгие ограничения частоты запросов. |
Доступ пользователя | Методы используются на клиенте, что позволяет быстро отображать пользователю данные, например каталог товаров или атрибуты пользователя — количество покупок или уровень в игре. Все данные находятся в открытом доступе в коде клиента. Не используйте эти методы для работы с данными, которые не должны быть доступны пользователю для редактирования. Например, для обновления атрибутов пользователя. | Методы используются для взаимодействия между серверами, поэтому пользователь не имеет доступ к данным. Используйте эти методы для работы с данными, значения которых пользователь не может изменять. | Методы не используются для реализации сценария действий пользователя. |
Определение страны и валюты | Страна и валюта определяются по IP-адресу клиента, с которого отправляется запрос. Поэтому важно использовать клиентские методы на стороне клиента, а не сервера. | Страна и валюта определяются по IP-адресу сервера, с которого отправляется запрос. Поэтому важно передать данные страны/валюты пользователя в заголовке или параметре в соответствии с описанием в используемом методе. | Методы не используются для реализации сценария действий пользователя. |
Вы можете определить, является метод клиентским или серверным, по способу аутентификации:
- Клиентские — методы, которые вызываются без аутентификации или с заголовком
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.
Пример метода с серверной аутентификацией:
Пример метода с клиентской аутентификацией:
В зависимости от ваших требований вы можете выбрать, как настроить интеграцию при реализации сценария пользователя — с серверными или клиентскими методами. Серверные методы администратора не должны использоваться для реализации сценария пользователя.
Пример реализации сценария пользователя с использованием клиентских методов:
- Пользователь выполняет действия на клиенте игры. Например, наполняет корзину, совершает покупку товара.
- Клиент игры отправляет запрос с данными на сервер Xsolla.
- Cервер Xsolla отправляет ответ клиенту игры.
- Клиент игры отображает результат пользователю.
В этом сценарии используется аутентификация по JWT пользователя.
Пример реализации сценария пользователя при использовании серверных методов:
- Пользователь выполняет действия на клиенте игры. Например, наполняет корзину, совершает покупку товара.
- Клиент игры отправляет запрос на сервер игры.
- При необходимости на сервере игры партнер реализует дополнительную обработку данных.
- Сервер игры отправляет запрос на сервер Xsolla.
- Cервер Xsolla отправляет ответ серверу игры.
- Сервер игры обрабатывает данные и отправляет ответ клиенту игры.
- Клиент игры отображает результат пользователю.
В этом сценарии используется базовая HTTP-аутентификация или серверный токен.
Сценарий взаимодействия при использовании серверных методов для административных задач:
- Партнер отправляет запрос со своего сервера на сервер Xsolla.
- Cервер Xsolla возвращает ответ с результатом обработки запроса.
Команды управления ресурсами
Все команды API указывают на тип данных, который должен быть обработан, и на действие, которое требуется совершить с этими данными. Стандартный список действий:Действие | HTTP-метод | Описание |
---|---|---|
Создание | POST | Создает и сохраняет сущность соответствующего типа. |
Список | GET | Возвращает список сущностей, удовлетворяющих запросу. |
Получение | GET | Возвращает данные по конкретному ID, которые вы присылаете в запросе. |
Замена | PUT | Заменяет все поля для сущности, переданной в запросе. |
Изменение | PATCH | Изменяет только указанные поля существующего объекта, который соответствует ID из запроса |
Удаление | DELETE | Удаляет существующий объект, который соответствует ID из запроса. |
Формат даты
Все представления дат передаются в строках согласно ISO 8601. Вы можете либо передавать дату в UTC (например, 2013-01-15T00:00:00Z), либо смещение от UTC для обозначения часового пояса (например, 2013-01-15T00:00:00-08:00 8 часов от UTC).Постраничная навигация
Результат запроса должен выводиться постранично. Это означает, что вместо вывода всех результатов выполнения запроса выводится только часть. Для этого необходимо использовать параметры limit и offset.Типы ошибок
Список поддерживаемых HTTP ответов:- 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 — что-то пошло не так.
422
ошибку.
В случае ошибочного ответа мы возвращаем 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"
}
Ограничение частоты запросов
Основная информация
Чтобы избежать чрезмерной нагрузки на системы Xsolla и защитить их от всплесков входящего трафика, Xsolla ограничивает количество запросов, полученных Xsolla API в течение определенного периода времени. В случае превышения лимита Xsolla API вернет HTTP-ответ с кодом429
.
Предельные значения ограничений варьируются в зависимости от метода, проекта и других факторов. Текущие ограничения регулярно обновляются, чтобы обеспечить стабильную и бесперебойную работу систем Xsolla. В отдельных случаях есть возможность регулировать заданные ограничения по предварительному запросу. Вы можете обратиться к вашему персональному менеджеру или написать на csm@xsolla.com, чтобы запросить изменение заданных ограничений.Распространенные причины превышения ограничений
- Внезапное увеличение трафика на стороне партнера в результате:
- сезонных распродаж;
- старта закрытых и открытых тестирований.
- Внезапное увеличение трафика в результате DDoS-атак на стороне партнера.
- Некорректно настроенная интеграция, например:
- Запуск чрезмерно большого количества запросов за определенный период. Например: вызов метода Get virtual items list для отображения каталога товаров в количестве более 200 запросов в секунду.
Управление ограничениями
Чтобы предотвратить появление ошибок, вызванных превышением ограничений, рекомендуется:- Отслеживать коды состояния
429
и создать механизм повторных попыток. Вместо непрерывных повторных попыток вы можете использовать паттерн Retry с фиксированными или экспоненциальными задержками между попытками. - Оптимизировать код для получения только необходимых данных. Убедитесь, что вы выполняете только те запросы, которые требуются вашему приложению, и исключите любые ненужные вызовы API. Если вы используете IGS&BB API, уменьшить количество вызовов можно при помощи WebSocket API.
- Кешировать данные, которые часто используются вашим приложением. Вы можете сохранить статические данные на своей стороне и уменьшить количество запросов к внешнему API.
- Предотвращать DDoS-атаки, которые могут вывести из строя ваш API.
- Регулировать скорость ваших запросов для более плавного распределения. Если ошибка
429
возникает регулярно, рассмотрите возможность включения в свой код процесса, который регулирует скорость ваших запросов и позволяет распределять их более равномерно во времени.
Ключи API
Ключ API — это уникальный ключ, который используется для шифрования данных пользователей и аутентификации API запросов. В Личном кабинете вы можете создать ключи API как для всех проектов компании, так и для отдельного проекта.
Вы можете работать с ключами API (просматривать список, создавать и удалять), если у вас одна из следующих ролей:
- разработчик;
- владелец.
Изменить роли может владелец проекта в Личном кабинете в разделе Настройки компании > Пользователи.
Создание ключей API
Чтобы создать ключ API:- Откройте Личный кабинет.
- Перейдите в раздел Настройки компании > API ключи или Настройки проекта > API ключи.
- Нажмите Создать API ключ.
- Заполните поля:
- Название ключа, которое будет отображаться в списке ключей. Задайте название, которое позволит легко идентифицировать ключ.
- Тип ключа — постоянный или временный.
- Срок действия — только для временного ключа API. После истечения срока действия временный ключ станет недействительным и вам необходимо будет создать новый ключ.
- Проект, в котором будет действовать ключ (поле не отображается, если вы создаете ключ API из настроек проекта). По умолчанию выбраны все проекты.
- Нажмите Создать.
- В открывшемся окне нажмите Скопировать API ключ и сохраните созданный ключ API на вашей стороне.
Основные рекомендации:
- Сохраните созданный ключ API на вашей стороне. Вы можете посмотреть ключ API в Личном кабинете только один раз при его создании.
- Никому не сообщайте ваш ключ API, так как он дает доступ к управлению аккаунтом и проектами в Личном кабинете.
- Ключ API должен храниться на вашем сервере и никогда — в бинарных файлах или на фронтенде.
Если необходимый метод API не включает в себя path-параметр project_id
, используйте для авторизации ключ API, который действует во всех проектах.
Удаление ключей API
Чтобы удалить ключ API:- Откройте Личный кабинет.
- Перейдите в раздел Настройки компании > API ключи или Настройки проекта > API ключи.
- В строке ключа API нажмите значок корзины и подтвердите действие.
- прием платежей в проектах, в которых используется этот ключ API;
- выполнение вызовов API, которые используют этот ключ API.
- Создайте новый ключ API.
- Переведите ваше приложение на новый ключ API.
- Удалите первоначальный ключ API.
Вебхуки
Вебхук — это механизм моментального оповещения вашей системы о событиях на стороне Xsolla. Настройте обработку вебхуков для автоматизации вашего приложения. Полный список вебхуков и механизм их работы описаны в документации.
Нашли опечатку или ошибку в тексте? Выделите ее и нажмите Ctrl+Enter.