С чего начать

Введение

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

  • Pay Station API — платежный интерфейс и методы токенизации.
  • IGS&BB API — методы для работы с модулями In-Game Store и Buy Button.
  • Subscriptions API — методы для подписок.
  • Publisher Account API — управление проектами и пользователями Личного кабинета, методы для работы с отчетами, тикетами поддержки.
  • Login API — методы аутентификации пользователей через собственный интерфейс (см. руководство по интеграции).
Xsolla API использует REST-архитектуру. В API мы используем HTTP коды ответов для обозначения ошибок и URL, аналогичных структуре каталогов. Ответы API (включая ошибки) возвращаются в виде JSON.

Мы используем встроенные особенности HTTP, такие как HTTP аутентификация и HTTP методы, которые понимаются всеми HTTP клиентами, также мы поддерживаем CORS (Cross-origin resource sharing) для обеспечения безопасной работы с API вашего клиентского приложения.

Xsolla API работает со следующими базовыми URL:
  • https://api.xsolla.com — Pay Station API, Publisher Account API, Subscriptions API
  • https://login.xsolla.com/api — Login API
  • https://store.xsolla.com/api — IGS&BB API
Многие ресурсы включают в себя параметр merchant_id, который указывает, что приложение работает именно от вашего имени.

Запрос и ответ

Запросы к Xsolla API должны:
  • отправляться по протоколу HTTPS;
  • использовать TLS версии 1.2 и выше;
  • содержать параметры аутентификации;
  • содержать дополнительный заголовок Content-Type: application/json для запросов типа PUT и POST.
Copy
Full screen
Small screen
    Authorization: Basic <your_authorization_basic_key>
Content-Type: application/json

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

    Изменения API

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

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

    Все разделы Xsolla API поддерживают версионирование. Мы будем выпускать новую версию всякий раз, когда будут появляться несовместимые с текущей версией изменения. Версия обозначается ID (“v1”/“v2” и т. п.), который указывается в URL после префикса “/merchant”. Если вы начинаете работу с API, используйте самую последнюю версию. Если вы не указали версию команды, то по умолчанию будет вызвана первая версия.
    Примечание
    Целостность работы 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 важно использовать методы в соответствии с их назначением:Корректно настроенная интеграция позволит избежать наиболее частых ошибок:
    Клиентские методы (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.

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

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

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

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

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

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

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

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

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

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

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

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

    Все команды 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 — что-то пошло не так.
    Xsolla использует стандартные HTTP коды для обозначения успешных или неуспешных запросов. В общем случае код в 2xx диапазоне обозначает успех, код диапазона 4хх означает ошибку в результате передачи некорректных параметров (например, обязательный параметр не передан, или авторизация не прошла и т. д.), код 5хх диапазона означает серверную ошибку. Не все ошибки в точности соответствуют HTTP кодам. Например, если запрос был верным, но не смог завершиться успешно, мы вернем 422 ошибку. В случае ошибочного ответа мы возвращаем JSON объект со следующими полями:
    НазваниеТипОписание
    http_status_codeintegerHTTP код.
    messagestringПонятное сообщение с описанием ошибки. Текст всегда на английском языке. Вы не должны использовать это поле в случае какой-либо ошибки, так как значение может измениться в будущем.
    extended_messagestringРасширенное описание ошибки.
    request_idstringУникальный ID запроса, используется, чтобы помочь нам диагностировать проблему.
    Copy
    Full screen
    Small screen
    • 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-атак на стороне партнера.
    • Некорректно настроенная интеграция, например:
      • использование методов подраздела Admin, не предназначенных для частого обращения, вместо методов подраздела Catalog;
      • слишком частый вызов метода Get order для получения статуса заказа и списка товаров в нем – 1 раз в секунду, когда рекомендуемая задержка между запросами составляет 3 секунды.
    • Запуск чрезмерно большого количества запросов за определенный период. Например: вызов метода 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:
    1. Откройте Личный кабинет.
    2. Перейдите в раздел Настройки компании > API ключи или Настройки проекта > API ключи.
    3. Нажмите Создать API ключ.
    4. Заполните поля:
      • Название ключа, которое будет отображаться в списке ключей. Задайте название, которое позволит легко идентифицировать ключ.
      • Тип ключа — постоянный или временный.
      • Срок действия — только для временного ключа API. После истечения срока действия временный ключ станет недействительным и вам необходимо будет создать новый ключ.
      • Проект, в котором будет действовать ключ (поле не отображается, если вы создаете ключ API из настроек проекта). По умолчанию выбраны все проекты.
    5. Нажмите Создать.
    6. В открывшемся окне нажмите Скопировать API ключ и сохраните созданный ключ API на вашей стороне.
    Примечание
    Если вы создаете ключ API на странице проекта, ключ будет действовать только в этом проекте.
    Внимание

    Основные рекомендации:

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

    Если необходимый метод API не включает в себя path-параметр project_id, используйте для авторизации ключ API, который действует во всех проектах.

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

    Чтобы удалить ключ API:
    1. Откройте Личный кабинет.
    2. Перейдите в раздел Настройки компании > API ключи или Настройки проекта > API ключи.
    3. В строке ключа API нажмите значок корзины и подтвердите действие.
    Удаление ключа API останавливает:
    • прием платежей в проектах, в которых используется этот ключ API;
    • выполнение вызовов API, которые используют этот ключ API.
    Чтобы избежать этого:
    1. Создайте новый ключ API.
    2. Переведите ваше приложение на новый ключ API.
    3. Удалите первоначальный ключ API.

    Вебхуки

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

    Была ли статья полезна?
    Спасибо!
    Что может сделать страницу еще лучше? Сообщение
    Жаль, что так произошло
    Расскажите, почему статья не была полезна. Сообщение
    Спасибо за обратную связь!
    Ваши мысли и идеи помогут нам улучшить ваш пользовательский опыт.
    Оценить страницу
    Оценить страницу
    Что может сделать страницу еще лучше?

    В другой раз

    Спасибо за обратную связь!
    Последнее обновление: 3 июля 2024

    Нашли опечатку или ошибку в тексте? Выделите ее и нажмите Ctrl+Enter.