Типовые сценарии

В зависимости от целей и задач, которые преследует внешняя система во взаимодействии с системой лояльности ProBonus, можно выделить несколько типовых сценариев интеграции.

В данном разделе описаны базовые кейсы и указаны конкретные методы API, необходимые для их реализации.

Если требуемая вам логика взаимодействия не описана в данном разделе, вы можете написать нам на soft@carbis.ru, и мы обязательно поможем найти решение.

API ProBonus предусматривает два различных способа авторизации:

1. Получение bearer-токена через авторизацию (/api/v0/auth/login) и его дальнейшее обновление (/api/v0/auth/refresh_token).
2. Работа через токен для API. Все запросы в заголовках содержат постоянный токен.

Поддерживаются оба варианта, но вариант 2 проще и удобнее. В Swagger доступны оба варианта.

• В качестве сквозного идентификатора гостя используем номер телефона.
• Если бизнес-логика подразумевает создание новых счетов из внешней системы, тогда каждого нового гостя вы создаёте в ProBonus методом /api/v0/accounts/insert_by_template.
  По минимуму нужно передать только анкетные данные и телефон (email и доп. идентификаторы — по желанию). Счёт для гостя будет создан в группе accountGroupId, и данному гостю будет автоматически назначена лояльность по шаблону, настроенному для этой группы в рамках системы ProBonus (уровень, приветственные бонусы, установлено сгорание и т. п.).
  ID нужной группы вы можете получить по API методом /api/v0/account_groups/list или просто посмотреть в админке (http://probonus.pro:6896/account-groups/) и вынести в настройки на своей стороне.
  Важно! Для корректного создания новых счетов по шаблону нужна группа с признаком «Шаблон для API» (haveTemplate=true). В тестовой БД это «Самостоятельно зарегистрировавшиеся» (id=3).
• Проверить гостя на существование в системе лояльности можно с помощью метода /api/v0/accounts/find_by_phone. Он ищет гостя по номеру телефона. Если гость с указанным номером телефона существует, то в ответ вернётся практически вся информация о нём: анкета, текущий остаток на счёте, текущий уровень, купоны и так далее.

• Начисление бонусов гостю по инициативе внешней системы (например, за какую-то активность в вашем приложении).
  /api/v0/accounts/refill
• Транзакции по счёту (показать в ЛК гостю его транзакции).
  /api/v0/accounts/transactions — вернёт все транзакции по счёту за указанный период.
  /api/v0/accounts/transactions — вернёт N последних транзакций.
• Обновить данные счёта (изменить анкету, изменить скидку/бонус, срок жизни бонусов и т. п.).
  /api/v0/accounts/update
• Получить данные конкретного чека гостя (вплоть до блюд).
  /api/v0/checks/get_by_id
• Если используются сгорающие бонусы.
  /api/v0/accounts/get_balance_extended — вернёт детализацию баланса счёта с указанием, когда и сколько сгорит.

Учёт лояльности (скидки/бонусы/потраты) за все покупки, совершённые гостем через систему r_keeper, происходит автоматически, и все данные об этих транзакциях попадают в базу ProBonus.

В некоторых случаях транзакция (которую нужно учесть в рамках ProBonus) происходит за рамками контура r_keeper (например, заказ на доставку, который по итогу не будет создан в r_keeper, т. к. внешний модуль доставки не имеет интеграции с кассовой системой и существует отдельно). При этом сумма покупки должна быть учтена в оборотах по счёту гостя (учёт потрат для расчёта лестницы, начисление/списание бонусов за внешнюю покупку и т. п.).

Для этой цели используется метод /api/v0/external/register_check.

Описание переменных:

Метод /api/v0/external/return_check используется для отката всех начислений, сделанных в ProBonus, в случае отмены покупки во внешней системе.