С версии 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».

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

#DOCUMENT_ROOT#/bitrix/modules/acrit_bonus_api.log

В лог попадает:

• дата и время;
• метод API;
• HTTP-статус;
• код ошибки, если он есть.

Входные параметры, токен авторизации и полный JSON-ответ в лог не записываются.

---

Методы Public API

1. user.get

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

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 

Поиск по внешнему идентификатору:

method=user.get&xml_id=15%7Ctest_user%7CИван 

Поиск по нескольким полям:

method=user.get&login=test_user&email=user@example.com&xml_id=15%7Ctest_user%7CИван 

Параметры

• login: логин пользователя
• email: email пользователя
• xml_id: внешний идентификатор пользователя из поля b_user.XML_ID

Возвращает в 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", "xml_id": "15|test_user|Иван" } 

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

---

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. accounts.get

Получить список бонусных счетов по фильтру

Header

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

Body

Базовый запрос:

method=accounts.get&user_id=15&limit=20&offset=0&sort=ID&order=ASC 

Запрос с фильтрами:

method=accounts.get&user_id=15&site_id=s1&active=Y 

Параметры

• user_id: ID пользователя (не обязательно, для получения всех счетов не указывать)
• limit: количество записей, по умолчанию 50, максимум 100
• offset: смещение, по умолчанию 0
• sort: поле сортировки: ID, ACCOUNT_ID, TIMESTAMP_X, BALANCE
• order: направление сортировки: ASC или DESC
• site_id: необязательный фильтр по сайту бонусного счёта
• active: необязательный фильтр активности бонусного счёта: Y или N

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

{ "total": 2, "limit": 50, "offset": 0, "items": [ { "id": 10, "user_id": 15, "user_xml_id": "15|test_user|Иван", "account_id": 1, "balance": 150.5, "account_name": "Основной бонусный счет", "site_id": "s1", "active": "Y", "timestamp_x": "2026-03-01T10:12:00+03:00", "notes": "" } ] } 

Если у пользователя нет счетов, метод возвращает пустой список без ошибки:

{ "total": 0, "limit": 50, "offset": 0, "items": [] } 

---

5. 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).

---

6. 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С&operation_id=ERP-20260325-001 

Списание:

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

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

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

Параметры

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

---

Коды ошибок

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

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

---

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

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

Назад в раздел