Типовые сценарии [База знаний ГК Карбис]

Эта страница только для чтения. Вы можете посмотреть её исходный текст, но не можете его изменить. Сообщите администратору, если считаете, что это неправильно.
====== Типовые сценарии ======

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

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

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

===== Авторизация для работы с API =====

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

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

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

{{:external:pro_bonus:10_probonus_api:pasted:20260216-093451.png}}

===== Работа с анкетными данными на уровне личного кабинета внешней системы =====

  * В качестве сквозного идентификатора гостя используем номер телефона.
  * Если бизнес-логика подразумевает создание новых счетов из внешней системы, тогда каждого нового гостя вы создаёте в 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 ProBonus =====

  * **Начисление бонусов гостю** по инициативе внешней системы (например, за какую-то активность в вашем приложении). \\ ''/api/v0/accounts/refill''
  * **Транзакции по счёту** (показать в ЛК гостю его транзакции). \\ ''/api/v0/accounts/transactions'' — вернёт все транзакции по счёту за указанный период. \\ ''/api/v0/accounts/get_last_raw_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''**.

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

^ Переменная ^ Описание ^
| ''restCode'' | Код ресторана (из справочника **Настройки → Рестораны**), к которому нужно отнести данную транзакцию для отчётов. |
| ''checkGuid'' | Уникальный номер внешней транзакции (в формате GUID). **Важно!** Система ProBonus не контролирует уникальность переданного GUID в рамках своей БД. Контроль уникальности лежит на внешней системе. |
| ''accountId'' | ID счёта, по которому совершена транзакция. |
| ''rkUnit'' | Код станции (рабочего места) в ресторане, к которому нужно отнести данную транзакцию для отчётов. Рекомендуем указывать код, заведомо определяющий, что это не настоящая станция в ресторане. Например, 999 или 888 или любой другой трёхзначный. |
| ''externalCheck'' | Номер транзакции во внешней системе (может использоваться для дальнейшей сверки транзакций между двумя отчётами). |
| ''bonusSpentSum'' | Сумма (в копейках), которую нужно списать со счёта в оплату транзакции. |
| ''discountSum'' | Сумма скидки (в копейках), которую гость получил во внешней системе. |
| ''bonusAccruedSum'' | Сумма (в копейках), которую нужно начислить на счёт за данную транзакцию. |
| ''moneySpentSum'' | Сумма (в копейках), которую гость потратил (оплатил) в рамках данной транзакции. |
| ''checkData'' | Любая текстовая информация о содержимом внешнего чека. |

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