Перейти к содержимому
/
Обновление цепочек наград

LiveOps API (2.0.0)

Введение

LiveOps — это набор инструментов для повышения вовлеченности пользователей с помощью акций и персонализированных предложений.

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

  • Промоакции — создание и управление купонами, промокодами, скидками и бонусными кампаниями.
  • Персонализация — возможность задавать условия отображения каталога товаров и применения акций только для определенного круга авторизованных пользователей.
  • Лимиты промоакций — настройка ограничений на количество использований акции пользователем, а также периодов автоматического обновления ограничений.
  • Цепочки наград и призовые баллы — настройка цепочек наград, привязанных к накоплению призовых баллов.
  • Ежедневные цепочки — настройка повторяющихся ежедневных наград для мотивации регулярных входов в игру.
  • Цепочки предложений — построение последовательных предложений покупки с ценой на каждом шаге и возможностью бесплатных наград.
  • Апселл — способ продаж, при котором пользователю предлагается купить товар с дополнительной ценностью.

Методы API

Методы API делятся на следующие группы:* Admin — методы для создания, обновления, активации и удаления кампаний и конфигураций цепочек. Для вызова требуется базовая HTTP-аутентификация с использованием учетных данных Личного кабинета.

  • Client — методы для получения доступных промоакций, получения активных цепочек, активации кодов и получения наград от имени аутентифицированных конечных пользователей. Аутентификация выполняется по JWT пользователя.
Скачать описание OpenAPI
index.json
index.yaml
Языки
Серверы
https://store.xsolla.com/api/
Mock server
https://xsolla.redocly.app/_mock/ru/api/liveops/

Общие

Операции

Купоны

Этот API позволяет вам управлять купонами.

Операции

Промокоды

Этот API позволяет вам управлять промокодами.

Операции

Уникальный каталог предложений

Этот API позволяет вам управлять уникальными предложениями каталога.

Операции

Скидки

Этот API позволяет вам управлять скидочными акциями.

Операции

Бонусы

Этот API позволяет вам управлять бонусными акциями.

Операции

Персонализированный каталог

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

Узнать о персонализированных акциях можно в подразделе "Скидки" раздела "Акции".

Чтобы передать атрибуты перед покупкой, вы можете использовать API Авторизации Иксолла или передать их в свойство user.attributes при генерации токена с помощью API Платежей Иксолла.

Операции

Управление

Операции

Admin

Операции

Получение цепочек наградServer-sideAdmin

Запрос

Получает определенную цепочку наград.

Безопасность
basicAuth
Путь
project_idintegerобязательный

ID проекта. Вы можете найти этот параметр в Личном кабинете рядом с названием проекта.

Пример: 44056
reward_chain_idintegerобязательный

ID цепочки наград.

Пример: 101
curl -i -X GET \
  -u <username>:<password> \
  https://store.xsolla.com/api/v3/project/44056/admin/reward_chain/id/101

Ответы

Указанная цепочка наград была успешно получена.

Телоapplication/json
One of:

Цепочка наград.

attribute_conditionsArray of type = string (object) or type = number (object) or type = date (object)(chain_user-attribute_conditions_model-get)[ 1 .. 100 ] items

Условия для проверки атрибутов пользователя. Определяют доступность цепочки на основе соответствия атрибутов пользователя всем указанным условиям.

description(two-letter (object or null)) or (five-letter (object or null))(description-localization-object)

Объект с локализованными описаниями товара. Принимает значения в одном из двух форматов: двухбуквенный код языка в нижнем регистре (например, en) или код локали из пяти символов (например, en-US). Оба формата допустимы при отправке запроса, но в ответе всегда используется код из двух символов. Если для одного языка указаны оба варианта (например, en и en-US), будет сохранено последнее переданное значение. Полный список поддерживаемых языков приведен в документации.

One of:

Объект с локализованными описаниями товара. Принимает значения в одном из двух форматов: двухбуквенный код языка в нижнем регистре (например, en) или код локали из пяти символов (например, en-US). Оба формата допустимы при отправке запроса, но в ответе всегда используется код из двух символов. Если для одного языка указаны оба варианта (например, en и en-US), будет сохранено последнее переданное значение. Полный список поддерживаемых языков приведен в документации.

image_urlstring or null(image_url)

URL-адрес изображения.

Пример: "https://image.example.com"
is_always_visibleboolean(chain_is_always_visible)

Отображается ли цепочка наград всем пользователям:

  • Если true — цепочка всегда отображается, независимо от авторизации пользователя и его атрибутов.
  • Если false — цепочка отображается, только если не найдено ни одной персонализированной цепочки. Например, если пользователь не авторизован или его атрибуты не соответствуют ни одной персонализированной цепочке.

Применяется только в контексте персонализации цепочек и используется, если массив attribute_conditions не передан.

По умолчанию true
Пример: true
is_enabledboolean(is_enabled)
Пример: true
is_reset_after_endboolean(is_reset_after_end)

Нужно ли сбрасывать цепочку наград (призовые баллы и прогресс всех пользователей) после даты ее окончания:

  • Если true, цепочка наград будет сброшена после даты окончания.
  • Если false, цепочка наград не будет сброшена после даты окончания.

Внимание

Не может быть true, если:
  • В recurrent_schedule задан период регулярного обновления.
  • В periods.date_until передано null.
По умолчанию false
Пример: false
long_description(two-letter (object or null)) or (five-letter (object or null))(long-description-localization-object)

Объект с локализованными длинными описаниями товара. Принимает значения в одном из двух форматов: двухбуквенный код языка в нижнем регистре (например, en) или код локали из пяти символов (например, en-US). Оба формата допустимы при отправке запроса, но в ответе всегда используется код из двух символов. Если для одного языка указаны оба варианта (например, en и en-US), будет сохранено последнее переданное значение. Полный список поддерживаемых языков приведен в документации.

Any of:

Объект с локализованными длинными описаниями товара. Принимает значения в одном из двух форматов: двухбуквенный код языка в нижнем регистре (например, en) или код локали из пяти символов (например, en-US). Оба формата допустимы при отправке запроса, но в ответе всегда используется код из двух символов. Если для одного языка указаны оба варианта (например, en и en-US), будет сохранено последнее переданное значение. Полный список поддерживаемых языков приведен в документации.

name(two-letter (object or null)) or (five-letter (object or null))(name-localization-object)

Объект с локализованными названиями товара. Принимает значения в одном из двух форматов: двухбуквенный код языка в нижнем регистре (например, en) или код языка из пяти символов (например, en-US). Оба формата допустимы при отправке запроса, но в ответе всегда используется двухбуквенный код языка. Если для одного языка указаны оба варианта (например, en и en-US), будет сохранено последнее переданное значение. Полный список поддерживаемых языков приведен в документации.

One of:

Объект с локализованными названиями товара. Принимает значения в одном из двух форматов: двухбуквенный код языка в нижнем регистре (например, en) или код языка из пяти символов (например, en-US). Оба формата допустимы при отправке запроса, но в ответе всегда используется двухбуквенный код языка. Если для одного языка указаны оба варианта (например, en и en-US), будет сохранено последнее переданное значение. Полный список поддерживаемых языков приведен в документации.

orderinteger(order)

Определяет порядок расположения.

Пример: 1
periodsArray of objects(periods)

Периоды действия цепочки наград. Если указано больше одного периода, параметры date_from и date_until становятся обязательными.

recurrent_schedule(interval_type = еженедельно (object or null)) or (interval_type = ежемесячно (object or null)) or (interval_type = hourly (object or null))(admin_recurrent_schedule)

Период регулярного сброса цепочки наград.

One of:

Период регулярного сброса цепочки наград.

reward_chain_idinteger(reward_chain_id)

Уникальный ID цепочки наград.

Пример: 9
stepsArray of objects(reward_step_short)
value_pointobject
Ответ
application/json
{
  "clan_type": "guild",
  "description": {
    "en": "Clan reward chain description."
  },
  "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png",
  "is_enabled": true,
  "long_description": {
    "en": "Clan reward chain long description."
  },
  "name": {
    "en": "Clan reward chain"
  },
  "order": 1,
  "periods": [
    { … }
  ],
  "popup_header": {
    "en": "How to unlock rewards"
  },
  "popup_image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png",
  "popup_instruction": {
    "en": "You must be a clan member in order to get clan rewards. You join a clan when a clan member invites you to the clan, and you accept the invite. You can also create your own clan."
  },
  "recurrent_schedule": {
    "day_of_week": 2,
    "displayable_reset_next_date": "2023-03-07T11:00:00+08:00",
    "displayable_reset_start_date": "2023-02-28T11:00:00+08:00",
    "interval_type": "weekly",
    "reset_next_date": 1677553200,
    "time": "11:00:00+08:00"
  },
  "reward_chain_id": 1,
  "steps": [
    { … },
    { … }
  ],
  "value_point": {
    "description": { … },
    "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png",
    "is_clan": true,
    "is_enabled": true,
    "long_description": { … },
    "media_list": [],
    "name": { … },
    "order": 1,
    "sku": "com.xsolla.clan_value_point_1"
  }
}

Обновление цепочек наградServer-sideAdmin

Запрос

Обновляет определенную цепочку наград.

Безопасность
basicAuth
Путь
project_idintegerобязательный

ID проекта. Вы можете найти этот параметр в Личном кабинете рядом с названием проекта.

Пример: 44056
reward_chain_idintegerобязательный

ID цепочки наград.

Пример: 101
Телоapplication/json
One of:

Цепочка наград.

attribute_conditionsArray of type = string (object) or type = number (object) or type = date (object)(chain_user-attribute_conditions_model-post)[ 1 .. 100 ] items

Условия для проверки атрибутов пользователя. Определяют доступность цепочки на основе соответствия атрибутов пользователя всем указанным условиям.

description(two-letter (object or null)) or (five-letter (object or null))(description-localization-object)

Объект с локализованными описаниями товара. Принимает значения в одном из двух форматов: двухбуквенный код языка в нижнем регистре (например, en) или код локали из пяти символов (например, en-US). Оба формата допустимы при отправке запроса, но в ответе всегда используется код из двух символов. Если для одного языка указаны оба варианта (например, en и en-US), будет сохранено последнее переданное значение. Полный список поддерживаемых языков приведен в документации.

One of:

Объект с локализованными описаниями товара. Принимает значения в одном из двух форматов: двухбуквенный код языка в нижнем регистре (например, en) или код локали из пяти символов (например, en-US). Оба формата допустимы при отправке запроса, но в ответе всегда используется код из двух символов. Если для одного языка указаны оба варианта (например, en и en-US), будет сохранено последнее переданное значение. Полный список поддерживаемых языков приведен в документации.

image_urlstring or null(image_url)

URL-адрес изображения.

Пример: "https://image.example.com"
is_always_visibleboolean(chain_is_always_visible)

Отображается ли цепочка наград всем пользователям:

  • Если true — цепочка всегда отображается, независимо от авторизации пользователя и его атрибутов.
  • Если false — цепочка отображается, только если не найдено ни одной персонализированной цепочки. Например, если пользователь не авторизован или его атрибуты не соответствуют ни одной персонализированной цепочке.

Применяется только в контексте персонализации цепочек и используется, если массив attribute_conditions не передан.

По умолчанию true
Пример: true
is_enabledboolean(is_enabled)обязательный
Пример: true
is_reset_after_endboolean(is_reset_after_end)

Нужно ли сбрасывать цепочку наград (призовые баллы и прогресс всех пользователей) после даты ее окончания:

  • Если true, цепочка наград будет сброшена после даты окончания.
  • Если false, цепочка наград не будет сброшена после даты окончания.

Внимание

Не может быть true, если:
  • В recurrent_schedule задан период регулярного обновления.
  • В periods.date_until передано null.
По умолчанию false
Пример: false
long_description(two-letter (object or null)) or (five-letter (object or null))(long-description-localization-object)

Объект с локализованными длинными описаниями товара. Принимает значения в одном из двух форматов: двухбуквенный код языка в нижнем регистре (например, en) или код локали из пяти символов (например, en-US). Оба формата допустимы при отправке запроса, но в ответе всегда используется код из двух символов. Если для одного языка указаны оба варианта (например, en и en-US), будет сохранено последнее переданное значение. Полный список поддерживаемых языков приведен в документации.

Any of:

Объект с локализованными длинными описаниями товара. Принимает значения в одном из двух форматов: двухбуквенный код языка в нижнем регистре (например, en) или код локали из пяти символов (например, en-US). Оба формата допустимы при отправке запроса, но в ответе всегда используется код из двух символов. Если для одного языка указаны оба варианта (например, en и en-US), будет сохранено последнее переданное значение. Полный список поддерживаемых языков приведен в документации.

name(two-letter (object or null)) or (five-letter (object or null))(name-localization-object)обязательный

Объект с локализованными названиями товара. Принимает значения в одном из двух форматов: двухбуквенный код языка в нижнем регистре (например, en) или код языка из пяти символов (например, en-US). Оба формата допустимы при отправке запроса, но в ответе всегда используется двухбуквенный код языка. Если для одного языка указаны оба варианта (например, en и en-US), будет сохранено последнее переданное значение. Полный список поддерживаемых языков приведен в документации.

One of:

Объект с локализованными названиями товара. Принимает значения в одном из двух форматов: двухбуквенный код языка в нижнем регистре (например, en) или код языка из пяти символов (например, en-US). Оба формата допустимы при отправке запроса, но в ответе всегда используется двухбуквенный код языка. Если для одного языка указаны оба варианта (например, en и en-US), будет сохранено последнее переданное значение. Полный список поддерживаемых языков приведен в документации.

name.​arstring or null

Арабский

name.​bgstring or null

Болгарский

name.​cnstring or null

Китайский упрощенный

name.​csstring or null

Чешский

name.​destring or null

Немецкий

name.​enstring or null

Английский

name.​esstring or null

Spanish (Spain)

name.​frstring or null

Французский

name.​hestring or null

Иврит

name.​idstring or null

Индонезийский

name.​itstring or null

Итальянский

name.​jastring or null

Японский

name.​kmstring or null

Кхмерский

name.​kostring or null

Корейский

name.​lostring or null

Лаосский

name.​mystring or null

Бирманский

name.​nestring or null

Непальский

name.​phstring or null

Филиппинский

name.​plstring or null

Польский

name.​ptstring or null

Португальский

name.​rostring or null

Румынский

name.​rustring or null

Русский

name.​thstring or null

Тайский

name.​trstring or null

Турецкий

name.​twstring or null

Китайский традиционный

name.​vistring or null

Вьетнамский

orderinteger(order)

Определяет порядок расположения.

Пример: 1
periodsArray of objects(periods)обязательный

Периоды действия цепочки наград. Если указано больше одного периода, параметры date_from и date_until становятся обязательными.

periods[].​date_fromstring(date-time)обязательный

Дата начала действия указанной цепочки наград.

Пример: "2020-08-11T10:00:00+03:00"
periods[].​date_untilstring or null(date-time)

Дата окончания действия указанной цепочки наград. Может быть null, только если указан один период действия.

Пример: "2020-08-11T20:00:00+03:00"
recurrent_schedule(interval_type = еженедельно (object or null)) or (interval_type = ежемесячно (object or null)) or (interval_type = hourly (object or null))(recurrent_schedule_create_update)

Период регулярного сброса цепочки наград.

One of:

Период регулярного сброса цепочки наград.

stepsArray of objects(modify_reward_step)обязательный
steps[].​image_urlstring or null(image_url)

URL-адрес изображения.

Пример: "https://image.example.com"
steps[].​name(two-letter (object or null)) or (five-letter (object or null))(name-localization-object)обязательный

Объект с локализованными названиями товара. Принимает значения в одном из двух форматов: двухбуквенный код языка в нижнем регистре (например, en) или код языка из пяти символов (например, en-US). Оба формата допустимы при отправке запроса, но в ответе всегда используется двухбуквенный код языка. Если для одного языка указаны оба варианта (например, en и en-US), будет сохранено последнее переданное значение. Полный список поддерживаемых языков приведен в документации.

One of:

Объект с локализованными названиями товара. Принимает значения в одном из двух форматов: двухбуквенный код языка в нижнем регистре (например, en) или код языка из пяти символов (например, en-US). Оба формата допустимы при отправке запроса, но в ответе всегда используется двухбуквенный код языка. Если для одного языка указаны оба варианта (например, en и en-US), будет сохранено последнее переданное значение. Полный список поддерживаемых языков приведен в документации.

steps[].​name.​arstring or null

Арабский

steps[].​name.​bgstring or null

Болгарский

steps[].​name.​cnstring or null

Китайский упрощенный

steps[].​name.​csstring or null

Чешский

steps[].​name.​destring or null

Немецкий

steps[].​name.​enstring or null

Английский

steps[].​name.​esstring or null

Spanish (Spain)

steps[].​name.​frstring or null

Французский

steps[].​name.​hestring or null

Иврит

steps[].​name.​idstring or null

Индонезийский

steps[].​name.​itstring or null

Итальянский

steps[].​name.​jastring or null

Японский

steps[].​name.​kmstring or null

Кхмерский

steps[].​name.​kostring or null

Корейский

steps[].​name.​lostring or null

Лаосский

steps[].​name.​mystring or null

Бирманский

steps[].​name.​nestring or null

Непальский

steps[].​name.​phstring or null

Филиппинский

steps[].​name.​plstring or null

Польский

steps[].​name.​ptstring or null

Португальский

steps[].​name.​rostring or null

Румынский

steps[].​name.​rustring or null

Русский

steps[].​name.​thstring or null

Тайский

steps[].​name.​trstring or null

Турецкий

steps[].​name.​twstring or null

Китайский традиционный

steps[].​name.​vistring or null

Вьетнамский

steps[].​priceobject(reward_step_price)обязательный
steps[].​price.​amountinteger(step_price_amount)обязательный

Цена уровня в призовых баллах.

Пример: 100
steps[].​rewardArray of objectsобязательный
steps[].​reward[].​attribute_conditionsArray of type = string (object) or type = number (object) or type = date (object)(reward-chain-step-reward_user-attribute_conditions_model-post)[ 1 .. 100 ] items

Условия для проверки атрибутов пользователя. Определяют доступность награды на шаге цепочки наград на основе соответствия атрибутов пользователя всем указанным условиям.

steps[].​reward[].​quantityinteger(reward_item_quantity)обязательный

Количество товаров.

Пример: 2
steps[].​reward[].​skustring(sku)[ 1 .. 255 ] characters^[a-zA-Z0-9_\-–.]*$обязательный

Уникальный ID товара. Артикул может содержать только строчные и заглавные латинские буквы, цифры, точки, тире и подчеркивания.

Пример: "booster_mega_1"
steps[].​step_idinteger or null(step_id)обязательный

Уникальный ID уровня.

Пример: 10
curl -i -X PUT \
  -u <username>:<password> \
  https://store.xsolla.com/api/v3/project/44056/admin/reward_chain/id/101 \
  -H 'Content-Type: application/json' \
  -d '{
    "clan_type": "guild",
    "description": {
      "en": "Clan reward chain description."
    },
    "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png",
    "is_enabled": true,
    "long_description": {
      "en": "Clan reward chain long description."
    },
    "name": {
      "en": "Clan reward chain"
    },
    "order": 1,
    "periods": [
      {
        "date_from": "2026-01-01T01:00:00+05:00",
        "date_until": "2026-01-31T23:59:59+05:00"
      },
      {
        "date_from": "2026-02-01T01:00:00+05:00",
        "date_until": "2026-02-28T23:59:59+05:00"
      }
    ],
    "popup_header": {
      "en": "How to unlock rewards"
    },
    "popup_image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png",
    "popup_instruction": {
      "en": "You should be a clan member to get clan rewards. You join a clan when a clan member invited you to the clan, and you accepted the invite. You can create your own clan."
    },
    "recurrent_schedule": {
      "day_of_week": 1,
      "interval_type": "weekly",
      "time": "01:00:00+08:00"
    },
    "steps": [
      {
        "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png",
        "name": {
          "en": "First step of the reward chain"
        },
        "price": {
          "amount": 10
        },
        "reward": [
          {
            "quantity": 5,
            "sku": "com.xsolla.item_1"
          },
          {
            "quantity": 1,
            "sku": "com.xsolla.item_2"
          }
        ],
        "step_id": 1
      },
      {
        "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png",
        "name": {
          "en": "Second step of the reward chain"
        },
        "price": {
          "amount": 15
        },
        "reward": [
          {
            "quantity": 5,
            "sku": "com.xsolla.item_3"
          },
          {
            "quantity": 1,
            "sku": "com.xsolla.item_4"
          }
        ],
        "step_id": 2
      }
    ]
  }'

Ответы

Цепочка наград была успешно обновлена.

Тело
Ответ
Нет содержимого

Сброс цепочки наградServer-sideAdmin

Запрос

Resets the value points balance and progress of all users in the reward chain.
The balance is tied to the value points type, not to a specific reward chain. If these value points are used in other chains, the balance will be reset in all chains that use these value points.
After the reset, you can update the reward chain’s validity period, and users will be able to progress through it again.
The clan balance is calculated as the sum of its members’ balances. Therefore, after the reset, the clan balance is also reset.
This request is irreversible and applies to all users of the project.

Notice

You should not reset the reward chain during its validity period. In this case, users may lose earned value points before they claim their reward.
Безопасность
basicAuth
Путь
project_idintegerобязательный

ID проекта. Вы можете найти этот параметр в Личном кабинете рядом с названием проекта.

Пример: 44056
reward_chain_idintegerобязательный

ID цепочки наград.

Пример: 101
curl -i -X POST \
  -u <username>:<password> \
  https://store.xsolla.com/api/v3/project/44056/admin/reward_chain/id/101/reset

Ответы

Цепочка наград сброшена.

Тело
Ответ
Нет содержимого

Клиент

Операции

Клиент кланов

Операции

Admin

Операции

Клиент

Операции

Admin

Операции

Клиент

Операции

Admin

Операции

Клиент

Операции