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

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