С версии 3.9 модуля бонусов появился публичный REST API модуля бонусов для сознания внешних интеграций с бонусной системой и счетами покупателей.

Включить и протестировать методы REST API модуля можно в настройках: 

Входная точка запросов (Endpoint)

/bitrix/tools/acrit.bonus/public_api.php

Авторизация

Доступ к Public API выполняется по токену из настроек модуля. Держите его в секрете!

Header

X-Acrit-Bonus-Token: <token>
Content-Type: application/x-www-form-urlencoded

Формат запроса

Все запросы отправляются методом POST. Параметры передаются в Body как обычные POST-поля.

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

Успешный ответ:

{
  "success": true,
  "data": {},
  "error": null,
  "meta": {
    "timestamp": "2026-03-25T13:40:00+00:00",
    "method": "user.get"
  }
}

Ответ с ошибкой:

{
  "success": false,
  "data": null,
  "error": {
    "code": "ERROR_CODE",
    "message": "Текст ошибки"
  },
  "meta": {
    "timestamp": "2026-03-25T13:40:00+00:00",
    "method": "user.get"
  }
}

Встроенный тестер

Во вкладке Public API в настройках модуля доступен встроенный блок «Протестировать API».

Что умеет тестер: - автоматически использует текущий endpoint модуля; - отправляет запросы с заголовком X-Acrit-Bonus-Token; - показывает только поля, нужные для выбранного метода; - выводит «Ответ JSON».

Логирование API

Во вкладке Public API доступна настройка «Вести логи API».

Если опция включена, модуль пишет лог в файл:

/upload/acrit.bonus/public_api.log

В лог попадает: - дата и время; - метод API; - входные параметры; - HTTP-статус; - JSON-ответ; - код ошибки, если он есть.

Токен авторизации в открытом виде в лог не записывается.

Методы Public API

1. user.get

Поиск пользователя Bitrix по login, email или по обоим параметрам сразу. Поиск выполняется по точному значению полей, без поиска по части строки.

Header

X-Acrit-Bonus-Token: <token>
Content-Type: application/x-www-form-urlencoded

Body

Поиск по login:

method=user.get&login=test_user

Поиск по email:

method=user.get&email=user@example.com

Поиск по login и email:

method=user.get&login=test_user&email=user@example.com

Параметры

• login — логин пользователя
• email — email пользователя

Возвращает в data

{
  "id": 15,
  "login": "test_user",
  "email": "user@example.com",
  "name": "Иван",
  "last_name": "Иванов",
  "second_name": "Иванович",
  "active": "Y",
  "date_register": "2026-03-01T10:12:00+03:00"
}

Если ни login, ни email не переданы, возвращается ошибка. Если пользователь не найден, возвращается ошибка. Если найдено несколько пользователей, возвращается ошибка неоднозначности.

2. account.get

Получить бонусный счёт пользователя.

Header

X-Acrit-Bonus-Token: <token>
Content-Type: application/x-www-form-urlencoded

Body

По account_id:

method=account.get&user_id=15&account_id=1

По site_id:

method=account.get&user_id=15&site_id=s1

Параметры

• user_id — ID пользователя
• account_id — ID бонусного счёта системы
• site_id — ID сайта, если счёт нужно определить по сайту

3. account.create

Создать бонусный счёт пользователя или вернуть уже существующий.

Header

X-Acrit-Bonus-Token: <token>
Content-Type: application/x-www-form-urlencoded

Body

По site_id:

method=account.create&user_id=15&site_id=s1

По account_id:

method=account.create&user_id=15&account_id=1

Параметры

• user_id — ID пользователя
• account_id — ID бонусного счёта системы
• site_id — ID сайта, если счёт нужно определить по сайту

4. transactions.get

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

Header

X-Acrit-Bonus-Token: <token>
Content-Type: application/x-www-form-urlencoded

Body

method=transactions.get&user_id=15&account_id=1&limit=20&offset=0&sort=TIMESTAMP_X&order=DESC&date_from=2026-03-01&date_to=2026-03-31

Параметры

• user_id — ID пользователя
• account_id — ID бонусного счёта системы
• limit — количество записей, максимум 100
• offset — смещение
• sort — поле сортировки: ID, TIMESTAMP_X, VALUE, ACTIVE_FROM, ACTIVE_TO
• order — направление сортировки: ASC или DESC
• date_from — дата начала периода
• date_to — дата конца периода

Для обратной совместимости также поддерживается старый формат, когда в sort передавалось только направление сортировки (ASC или DESC).

5. account.update

Изменить баланс счёта пользователя.

Header

X-Acrit-Bonus-Token: <token>
Content-Type: application/x-www-form-urlencoded

Body

Начисление:

method=account.update&user_id=15&account_id=1&mode=delta&value=150&description=Начисление из 1С&external_id=ERP-20260325-001

Списание:

method=account.update&user_id=15&account_id=1&mode=delta&value=-50&description=Списание на кассе&external_id=POS-20260325-010

Установка точного баланса:

method=account.update&user_id=15&account_id=1&mode=set&value=500&description=Синхронизация остатка

Параметры

• user_id — ID пользователя
• account_id — ID бонусного счёта системы
• mode — режим: delta или set
• value — число для операции
• description — комментарий к операции
• external_id — внешний ID операции

Коды ошибок

Примеры возможных ошибок:

• UNAUTHORIZED — неверный или отсутствующий токен
• API_DISABLED — Public API выключен в настройках
• METHOD_REQUIRED — не передан параметр method
• METHOD_NOT_FOUND — неизвестный метод API
• USER_LOOKUP_FIELDS_REQUIRED — для user.get не переданы login и email
• USER_NOT_FOUND — пользователь не найден
• USER_LOOKUP_AMBIGUOUS — найдено несколько пользователей
• ACCOUNT_ENTITY_NOT_FOUND — не найден бонусный счёт системы
• ACCOUNT_NOT_FOUND — не найден бонусный счёт пользователя
• VALUE_INVALID — некорректное значение value
• INSUFFICIENT_FUNDS — недостаточно бонусов для списания

Рекомендуемый сценарий интеграции

1. Найти пользователя через user.get
2. Получить USER_ID
3. Создать пользовательский бонусный счёт через account.create
4. Проверить текущий баланс через account.get
5. Начислять и списывать бонусы через account.update
6. Получать историю операций через transactions.get