С чего начать

Введение

API Иксоллы включает в себя:

  • Pay Station API — платежный интерфейс и методы токенизации.
  • IGS&BB API — методы для работы с модулями Внутриигровой магазин и Buy Button.
  • Subscription API — методы для подписок.
  • Publisher Account API — управление проектами и пользователями Личного кабинета, методы для работы с отчетами, тикетами поддержки.
  • Login API — методы аутентификации пользователей через собственный интерфейс (см. руководство по интеграции).

API Иксоллы использует REST-архитектуру. В API мы используем HTTP коды ответов для обозначения ошибок и URL, аналогичных структуре каталогов. Ответы API (включая ошибки) возвращаются в виде JSON.

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

API Иксоллы работает со следующими базовыми URL:

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

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

Запросы к 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

    Иксолла может изменять функциональные возможности API:

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

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

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

    Все разделы API Иксоллы поддерживают версионирование. Мы будем выпускать новую версию всякий раз, когда будут появляться несовместимые с текущей версией изменения. Версия обозначается идентификатором ("v1"/"v2" и т. п.), который указывается в URL после префикса "/merchant".

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

    Примечание
    Целостность работы API гарантируется в рамках одной версии.

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

    API Иксоллы использует базовую HTTP-аутентификацию. Все запросы к API должны содержать заголовок Authorization: Basic <your_authorization_basic_key>, где <your_authorization_basic_key> — пара merchant_id:api_key, закодированная по стандарту Base64.

    Значения параметров merchant_id и api_key вы можете найти в Личном кабинете Иксолла:

    • merchant_id: Настройки компании > Компания > ID продавца
    • api_key: Настройки компании > Ключ API

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

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

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

    ДействиеHTTP-методОписание
    СозданиеPOSTСоздает и сохраняет сущность соответствующего типа.
    СписокGETВозвращает список сущностей, удовлетворяющих запросу.
    ПолучениеGETВозвращает данные по конкретному идентификатору, которые вы присылаете в запросе.
    ЗаменаPUTЗаменяет все поля для сущности, переданной в запросе.
    ИзменениеPATCHИзменяет только указанные поля существующего объекта, который соответствует идентификатору из запроса
    УдалениеDELETEУдаляет существующий объект, который соответствует идентификатору из запроса.

    Формат даты

    Все представления дат передаются в строках согласно 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 — что-то пошло не так.

    Иксолла использует стандартные HTTP коды для обозначения успешных или неуспешных запросов. В общем случае код в 2xx диапазоне обозначает успех, код диапазона 4хх означает ошибку в результате передачи некорректных параметров (например, обязательный параметр не передан, или авторизация не прошла и т. д.), код 5хх диапазона означает серверную ошибку.

    Не все ошибки в точности соответствуют HTTP кодам. Например, если запрос был верным, но не смог завершиться успешно, мы вернем 422 ошибку.

    В случае ошибочного ответа мы возвращаем JSON объект со следующими полями:

    НазваниеТипОписание
    http_status_codeintegerHTTP код.
    messagestringПонятное сообщение с описанием ошибки. Текст всегда на английском языке. Вы не должны использовать это поле в случае какой-либо ошибки, так как значение может измениться в будущем.
    extended_messagestringРасширенное описание ошибки.
    request_idstringУникальный ID запроса, используется, чтобы помочь нам диагностировать проблему.
    Copy
    Full screen
    Small screen
    {
        "http_status_code": 500,
        "message": "Internal Server Error",
        "extended_message": null,
        "request_id": "6445b85"
    }

    Ограничение частоты запросов

    Общая информация

    Чтобы избежать чрезмерной нагрузки на системы Иксоллы и защитить их от всплесков входящего трафика, Иксолла ограничивает количество запросов, полученных API Иксоллы в течение определенного периода времени. В случае превышения лимита API Иксоллы вернет HTTP-ответ с кодом 429.

    Предельные значения ограничений варьируются в зависимости от метода, проекта и других факторов. Текущие ограничения регулярно обновляются, чтобы обеспечить стабильную и бесперебойную работу систем Иксоллы. В отдельных случаях есть возможность регулировать заданные ограничения по предварительному запросу. Вы можете обратиться к вашему аккаунт-менеджеру или написать на am@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 возникает регулярно, рассмотрите возможность включения в свой код процесса, который регулирует скорость ваших запросов и позволяет распределять их более равномерно во времени.

    Вебхуки

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

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

    В другой раз

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

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