ProBonus API. Справочник методов

ProBonus предоставляет REST API (JSON over HTTP) для интеграции с внешними системами: сайтом и мобильным приложением, службой доставки, CRM, системами отчётности. Общее описание API и типовые сценарии — в статьях ProBonus Api и Типовые сценарии.

Справочник построен по OpenAPI-схеме сервера ProBonus версии 65535.2.86.411 и содержит 285 методов в 8 разделах. Набор методов и полей зависит от версии ProBonus: актуальное описание для вашего сервера всегда доступно в интерактивной документации (Swagger) по адресу http:<сервер>:<порт>/docs или во вкладке «ProBonus API» веб-интерфейса.


===== Подключение =====

* Адрес: http:<сервер ProBonus>:<порт> — тот же адрес и порт, что и у веб-интерфейса ProBonus.

• Формат: запросы и ответы — JSON в кодировке UTF-8 (заголовок Content-Type: application/json). Загрузка файлов — multipart/form-data.
• Методы HTTP: чтение данных — GET с параметрами в строке запроса; добавление, изменение, удаление и операции — POST с телом запроса в JSON.
• Версии API: основная часть методов — /api/v0/…. Сегментные акции в актуальном формате (акция с несколькими действиями) — /api/v1/promotions/…; методы /api/v0/promotions/… сохранены для совместимости.

Все методы, кроме отмеченных «Авторизация: не требуется», требуют авторизации одним из двух способов.

Используется веб-интерфейсом и подходит для интерактивных приложений.

1. Получите токен методом POST /api/v0/auth/login, передав логин и пароль пользователя ProBonus:

   { "login": "api_user", "password": "********" }

2. В ответе придут accessToken, срок его действия expire и refreshToken.
3. Передавайте токен во всех запросах в заголовке:

   Authorization: Bearer <accessToken>

4. До истечения срока действия получите новую пару токенов методом POST /api/v0/auth/refresh_token. Сроки действия токенов задаются в настройках сервера (accessTokenValidMinutes, refreshTokenValidMinutes).

Рекомендуемый способ для интеграций с внешними системами (доступен с версии ProBonus 1.2.60.297). Создайте в веб-интерфейсе пользователя для API (или методом POST /api/v0/users/insert_api_user) и передавайте его бессрочный токен в заголовке:

X-API-Key: <токен пользователя API>

Важно! Права пользователя API ограничиваются его ролью: роль содержит перечень разрешённых методов (см. Роли). При вызове метода, не разрешённого ролью, сервер вернёт ответ 403. Выдавайте пользователю API только те методы, которые нужны интеграции.

• Имена полей в JSON — в стиле camelCase (accountGroupId), имена query-параметров — в стиле snake_case (account_group_id).
• Суммы с типом number передаются в рублях с копейками в дробной части (например, 150.50). Обратите внимание: в базе данных те же суммы хранятся в копейках.
• Даты — строки в формате ISO 8601: дата 2026-10-01, дата и время 2026-10-01T12:30:00.
• Списочные параметры (например, account_group_ids) передаются повторением параметра: ?account_group_ids=1&account_group_ids=5.
• Удаление объектов справочников, как правило, мягкое: объект помечается удалённым и может быть восстановлен (методы restore).
• Обязательные поля отмечены в таблицах знаком «да» в колонке «Обяз.». Необязательные поля можно не передавать или передавать null.

Формат ошибок:

// 400, 401, 403, 410 — массив ошибок
[ { "code": "ACCOUNT_NOT_FOUND", "message": "Счёт не найден" } ]
 
// 422 — ошибка валидации
{ "detail": [ { "loc": ["body", "amount"], "msg": "field required", "type": "value_error.missing" } ] }
 
// 500 — внутренняя ошибка
{ "class_name": "Exception", "message": "..." }

Коды и тексты ошибок в примере условные — сервер возвращает собственные значения.

# 1. Найти счёт по номеру телефона
curl -H "X-API-Key: <токен>" "http://probonus:11030/api/v0/accounts/find_by_phone?phone=79991234567"
 
# 2. Пополнить баланс найденного счёта на 100 руб. с отложенным на 1 день начислением
curl -X POST -H "X-API-Key: <токен>" -H "Content-Type: application/json" \
     -d '{"id": 123, "amount": 100, "reason": "Компенсация", "lateIssueDays": 1}' \
     "http://probonus:11030/api/v0/accounts/refill"