REST API модуля «Геймификация»

Справочник REST-методов модуля ithive.gamification для интеграций, входящих вебхуков и AI-агентов.

Базовый URL

https://{портал}/rest/{user_id}/{webhook_code}/{method}.json

Пример:

https://portal.company.ru/rest/1/xxxxxxxx/gamification.balance.get.json

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

  • Scope: gamification
  • Аутентификация: входящий вебхук Bitrix24 или OAuth/сессия авторизованного пользователя
  • Все методы gamification.* требуют авторизованного пользователя REST. Без авторизации — ошибка UNAUTHORIZED.

Авторизация ≠ право на операцию: администраторские методы дополнительно проверяют роль (admin / manager), некоторые методы ограничивают просмотр чужого баланса или истории транзакций.

Права доступа

Группа методов Кто может вызывать
balance.get, balance.history, level.current Любой авторизованный (для чужого userId — только admin/manager или при наличии права canViewUserBalance)
thanks.send, thanks.list, thanks.category.list/get Любой авторизованный
shop.product.order Любой авторизованный
shop.category.list, rating.list/get, honour.list/get, action.list/get, event.list/get, level.list Любой авторизованный
Все *.create, *.update, *.delete, balance.set, transaction.create, rating.recalculate, rating.monthResults, rating.board.*, level.update, user.search*, shop.product.bulk* Только admin или manager

Формат ответа

Конверт модуля (в result обёртки Bitrix REST):

Поле Описание
result Данные или null при ошибке
total Количество записей (для list-методов; во входящем вебхуке часто на верхнем уровне Bitrix REST, рядом с result)
next Смещение следующей страницы; поле не возвращается, если следующей страницы нет
error null или { code, message, details }

Пагинация

Для методов *.list, balance.history.

Параметр По умолчанию Описание
limit 50 Размер страницы, максимум 500
offset 0 Смещение
fetchAll false Вернуть все записи одним ответом. Защитный лимит — 5000; при превышении — FETCHALL_LIMIT_EXCEEDED
filter — Фильтрация в Mongo-стиле (см. ниже)

Фильтрация (Mongo-стиль)

Параметр filter — объект вида { "FIELD": value } или с оператором { "$gt": { "FIELD": value } }.

Оператор Описание
(нет) Равенство
$gt, $gte, $lt, $lte Сравнение
$in, $nin Вхождение в массив / исключение
$ne Не равно

Недопустимый оператор или поле — INVALID_FILTER / INVALID_FILTER_OPERATOR.

Пакетные вызовы

Отдельного метода gamification.batch нет. Для нескольких gamification.* за один HTTP-запрос используйте штатный batch Битрикс24 (/rest/{user_id}/{webhook_code}/batch.json).

Разделы справочника

Раздел Описание
Баланс balance.*
Транзакции transaction.*
Действия action.*
События начисления event.*
Уровни level.*
Благодарности thanks., thanks.category.
Магазин бонусов shop.product., shop.category.
Рейтинги rating., rating.participant., rating.winner., rating.board., rating.type.*
Доска почёта honour.*
Поиск пользователей user.*
Справочники currency.list, notifyLevel.list, rating.status.list, shop.product.status.list
Коды ошибок Полный перечень

Всего методов в текущем коде: 52.

Предыдущая
Время пересчета рейтингов и начисления баллов
Следующая
Баланс