Введение
Xsolla API включает в себя:
- Pay Station API — платежный интерфейс и методы токенизации.
- IGS&BB API — методы для работы с модулями In-Game Store и Buy Button.
- Subscriptions API — методы для подписок.
- Publisher Account 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 указывают на тип данных, который должен быть обработан, и на действие, которое требуется совершить с этими данными. Стандартный список действий:Действие | 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
Чтобы удалить ключ API:- Откройте Личный кабинет.
- Перейдите в раздел Настройки компании > API ключи или Настройки проекта > API ключи.
- В строке ключа API нажмите значок корзины и подтвердите действие.
- прием платежей в проектах, в которых используется этот ключ API;
- выполнение вызовов API, которые используют этот ключ API.
- Создайте новый ключ API.
- Переведите ваше приложение на новый ключ API.
- Удалите первоначальный ключ API.
Вебхуки
Вебхук — это механизм моментального оповещения вашей системы о событиях на стороне Xsolla. Настройте обработку вебхуков для автоматизации вашего приложения. Полный список вебхуков и механизм их работы описаны в документации.
Была ли статья полезна?
Оценить страницу
В другой раз
Спасибо за обратную связь!
Нашли опечатку или ошибку в тексте? Выделите ее и нажмите Ctrl+Enter.