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 Любой авторизованный (thanks.send с fromUserId другого пользователя — только администратор портала)
shop.product.order Любой авторизованный (с userId другого пользователя — только администратор портала)
level.create/delete, rating.create/delete, thanks.category.create/delete Право на изменение настроек модуля — уровень доступа к модулю выше «чтения», как на странице настроек; у администратора портала есть всегда
schema Любой авторизованный
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 (transaction.create с date — только администратор портала)

Параметры «только для администратора»

Параметры, которые действуют от имени другого сотрудника или переписывают историю, доступны только администратору портала; сам метод остаётся доступен своим обычным пользователям. Сотрудник должен существовать и быть активным, иначе — USER_NOT_FOUND.

Метод Параметр Что делает
thanks.send fromUserId Отправить благодарность от имени сотрудника
shop.product.order userId Оформить заказ на сотрудника
transaction.create date Записать операцию на дату в прошлом

Не-администратор, передавший такой параметр с чужим ID (или date), получает ACCESS_DENIED.

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

Конверт модуля (в 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
Служебные методы schema
Коды ошибок Полный перечень

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

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