С чего начать

Введение

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 указывают на тип данных, который должен быть обработан, и на действие, которое требуется совершить с этими данными. Стандартный список действий:
    Действие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

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

    Вебхуки

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

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

    В другой раз

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

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