Cценарии интеграции с kilbil по API

Обработка чека (документа продажи) с вводом клиента

1. Ввод карты клиента (номера телефона/ номера карты/электронной карты)

Ввод номера карты/телефона осуществляется в одном интерфейсном окне.

При необходимости надо запретить ввод карты клиента вручную (только считывая с оборудования) и разрешить ручной ввод только для номера телефона.

После получения номера карты/телефона выполняем запрос searchclient с соответствующим search_mode (0 – поиск по номеру телефона, 1 – поиск по внутреннему № карты).

В запросе должны быть заполнены параметры goods_data и promo_codes. Эти параметры передаются для предварительного расчета чека для возврата доступной суммы списания бонусов с учетом акций и всех ограничений.

2. Обработка полученных данных по клиенту

Основные параметры ответа от сервера kilbil являются result_code и result_text (в result_text в большинстве случаев есть описание результата).

Основная информация:

• ФИО клиента

• название программы лояльности

• сумма по чеку (которая пришла из kilbil после расчетов discounted_total)

• бонусный баланс

• лимит списания бонусов на чек

• если включена настройка показывать сумму покупок, тогда выводим purchases_sum

• если статус клиента не пуст, тогда выводим статус last_month_status

• если есть сообщение с тегами, выводим его tags

• если есть сообщение с любимыми товарами, тогда выводим его top_sales

После всех проверок (пункты 2.1 и 2.2) выводим окно со списанием бонусов, при этом:

• Показываем окно со списанием бонусов, если введена карта или only_with_cards = 0 или use_sms_code > 0.

• Может быть параметр требования кода подтверждения в зависимости от величины суммы списания. Смотрим на параметр sms_code_sum, если он больше 0 → то запрашиваем код подтверждения от суммы больше или равно суммы в sms_code_sum.

• В остальных случаях без возможности списания.

• Не выводим окно со списанием бонусов для дисконтной программы лояльности (program_type не равно 1).

Возможность активации клиента на кассе определяется параметром activate_client_type. Возможность замены карты клиента на кассе определяется параметром replace_card_type. См. п. 5.

Для определения проверки по коду подтверждения при списании бонусов используется параметр use_sms_code (0 - нет, 1 - при вводе телефона, 2 - при вводе карты и телефона). См. п. 6.

2.1. Клиент не найден

Клиент считается не найденным, если result_code = 6 (при этом client_id = null).

Если поиск был по номеру карты, то нужно обработать result_code = 4 или 5 → это означает что карта не найдена, отменяем ввод карты.

Если настройка "К клиенту обязательно привязана карта" включена и клиент не найден (only_with_cards = 1 и result_code = 6) → проверяем настройку activate_client_type:

• Если activate_client_type = 2 → сообщаем кассиру, что активация клиента на кассе запрещена.

• Если activate_client_type = 0 или 1 → сообщаем, что клиент не найден и необходимо выдать карту.

2.2. Клиент найден

Клиент считается найденным, если client_id не 0 и не null (имеет ненулевое значение).

Проверяем состояние клиента и карты, если card_state не равно 0 (2 - заблокирована, 3 - заменена) → информируем кассира о состоянии клиента/карты и отменяем ввод карты.

Если статус клиента "Не активирован" (state = 0 или state = 3):

• activate_client_type = 2 → информируем, что активация на кассе запрещена

• activate_client_type = 0 или 1, тогда:

→ Если поиск клиента был "по номеру телефона" и "к клиенту обязательно привязана карта" отключено (only_with_cards = 0), предлагаем активировать клиента, иначе выводим окно с информацией о бонусной системе с информированием о том, что клиент "не активирован" (может работать в режиме накопления бонусов без возможности списания бонусов).

→ Если поиск клиента был "по номеру карты" и клиент найден (client_id не равен null), тогда предлагаем активировать карту.

Клиент считается "Активированным", если state = 1.

Если Тип программы лояльности = "Подарочный сертификат" (program_type = 3), тогда проверяем на какой тип списания настроено (program_write_off_type).

Если program_write_off_type = 1, это означает, что при использовании подарочного сертификата списание с баланса проходит на кассе как "Тип оплаты = Сертификат". Информируем кассира о том, что Подарочный сертификат настроен на тип оплаты и применять его как бонусную карту нельзя. Отменить ввод карты.

Подробнее см. в статье Сценарии работы с Подарочными картами

3. Создание документа в kilbil и применение акций/ скидок/цен из kilbil

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

Для этого отправляем запрос processsale. Обязательные параметры запроса:

• type = тип операции (0 - продажа, 1 - возврат)

• client_id = id клиента

• bonus_out = сумма бонусов для списания (0, если списания бонусов нет)

• max_bonus_out = максимально возможная сумма для списания бонусов без учета баланса клиента (передается значение выходного параметра max_bill_bonus_out функции searchclient)

• goods_data = JSON с позициями чека в полном виде

• move_id = id чека на торговом оборудовании, должен быть уникальным в рамках одного торгового оборудования (кассы) на протяжении всего времени работы

• doc_open_dt = дата и время открытия документа чека

• card_apply_dt = дата и время применения карты (в часовом поясе UTC)

• shift_number = номер смены

После выполнения запроса получаем ответ с готовыми расчетами. Расчеты производятся на каждую позицию отдельно, информация о позициях находится в массиве items.

• Полную скидку на позицию можно получить, сложив 3 параметра:

  • discount - скидка

  • bonus_out_money - списанные бонусы

  • rounding - округление настроенное в kilbil

• Новая цена позиции находится в параметре price для каждой позиции, если она отличается от текущей цены, необходимо установить новую цену.

3.1. Промокоды (ввод промокода на документ)

Промокод может работать с вводом карты лояльности (с клиентом) и без ввода карта (ввода клиента).

Ввод промокода обычно настраивается на кассе по нажатию отдельной кнопки “Ввод промокода” (или “Ввод купона”).

Если кассир ввел промокод после ввода карты/ввода номера телефона → вывести сообщение вида "Отмените ввод карты/клиента, введите промокод и введите карту/номер телефона снова".

По кнопке, на которую настроен ввод промокода, вводим промокод.

Выполняем функцию searchpromocode. Проверяем ответ от kilbil:

• Если result_code равен 0 → показать сообщение кассиру вида "Промокод НОМЕРПРОМОКОДА введен".

• Если result_code не равен 0 → вывести result_text.

Далее этот промокод нужно передавать во все последующие запросы searchclient и processsale в объекте promo_codes. См. пример в документации API.

3.2. Вывод сообщений продавцу из настроек в kilbil, печать информации в чек

Информация для продавца выводится в едином окне. Нужно проверять следующие параметры:

• applied_actions = примененные акции

• responds_quantities_rests_messages = сообщение о невыданном подарке → нужно дать возможность кассиру вернуться в чек для добавления подарочного товара или продолжить продажу

• actions_lc_rests → остаток товаров по акции вида “с ограничением количества” → информирует кассира об остаточном количестве товара, который доступен по акции

Информация для печати в чек:

• _bill_header = шапка (заголовок)

• _bill_body = информация о программе лояльности, бонусам, статусу клиента и т.п.

• _bill_foote = подвал чека

3.3. Работа в офлайн-режиме (когда нет интернета или связи с сервером kilbil)

Не является обязательным при реализации интеграции.

→ Если сервер kilbil не доступен на стадии поиска клиента searchclient:

• В интерфейс вывести информацию вида "Нет связи с системой лояльности. Не удалось получить данные о клиенте. Нажмите ОК".

• Кассиру запрещаем списывать бонусы и не показываем окно с информацией о бонусах.

• Дальнейшие запросы processsale и confirmsale сохраняем для отправки, когда появится связь с сервером kilbil.

→ Если сервер kilbil не доступен на стадии создания документа в kilbil processsale:

• Сообщаем кассиру о том, что "Нет связи с системой лояльности".

• При этом если было указано списание бонусов, необходимо обнулить списание, так как скидка не распределилась, и сохранить запрос для дальнейшей отправки (confirmsale сохраняется без попытки подключения к серверу).

→ Если сервер kilbil не доступен на стадии подтверждения чека confirmsale:

• Сохраняем запрос подтверждения для дальнейшей отправки.

Для правильной обработки чеков в офлайне необходимо в processsale добавить информацию для авторизации, если введена карта, параметры client_search_mode и client_search_value в соответствии со значениями из searchclient (передавать всегда независимо от режима работы).

Параметр "офлайн" добавляется только в случае: is_offline: 1 (при работе в обычном режиме, когда связь с сервером есть, можно не передавать). Дополнительных признаков офлайна для других функций не требуется.

Остальные функции в оффлайне работать не могут.

В чеке вместо информации напечатать сообщение вида: "По техническим причинам эта покупка появится в Программе Лояльности позднее"

При восстановлении подключения к серверу kilbil необходимо последовательно передать все накопившееся чеки, при этом к одному чеку может относится 1 или 2 запроса - processsale и confirmsale или только confirmsale.

• при наличии processsale и confirmsale: сначала отправляем processsale, необходимо убедиться что покупка создана, "result_code": "0", только после этого отправляем confirmsale; также убеждаемся, что запрос обработан, только после подтверждения запроса о его успешной обработке считаем что запрос передан.

• при наличии confirmsale отправляем и фиксируем успешную отправку.

• периодичность отправки одного чека 10 секунд (processsale + confirmsale считается одним чеком).

4. Подтверждение документа

Подтверждение документа происходит после печати фискального чека, т.е. когда операция оплаты полностью выполнена и подтверждена на кассовом месте.

Выполняется методом confirmsale, данные о чеке должны совпадать с processsale.

Добавление нового клиента

1. Регистрация нового клиента в Программе лояльности

Регистрация нового клиента в Программе лояльности выполняется методом addclient.

В случае кассы продавец заполняет на кассе поля анкеты, данные анкетирования отправляются на сервер. На сайте пользователь заполняет поля анкеты.

Если требуется верификация номера телефона по пин-коду подтверждения (определяем из ответа searchclient), то делаем перед отправкой проверку кодом подтверждения.

2. Регистрация нового клиента с применением реферальной механики

Если в kilbil включена реферальная механика (referral_system_is_used=1, определяем из ответа searchclient), то при регистрации нового клиента показать "Поле для ввода рекомендателя" (addclient).

Привязка Реферала к Рекомендателю может быть реализована 2 способами:

• через ввод в "Поле для ввода рекомендателя" его номера телефона;

• через ввод в "Поле для ввода рекомендателя" его реферального кода.

Реферальный код на кассе может быть считан сканером.

Номер телефона определяем следующим образом: 11 символов; первая цифра 7. Иначе считаем, что введен реферальный код.

Если в "Поле для ввода рекомендателя" введен номер телефона, то нужно:

• проверить, что этот номер телефона не совпадает с номером телефона регистрируемого Реферала;

• найти клиента по номеру телефона (searchclient);

• далее если клиент существует и статус карты не "замена карты (донор)" (state не равно 4 и не null):

  • одобрить регистрацию нового клиента-реферала;

  • в функцию addclient необходимо в параметре referrer_client_id передать client_id Рекомендателя полученный в ответе на searchclient.

• иначе выдать сообщение вида "клиент с таким номером не найден".

Если в "Поле для ввода рекомендателя" введен реферальный код:

• введенное значение перевести из 16-ричной в 10-ричную систему исчисления;

• найти клиента по client_id (searchclient);

• далее если клиент существует и статус карты не "замена карты (донор)" (state не равно 4 и не null):

  • одобрить регистрацию нового клиента-реферала;

  • в функцию addclient необходимо в параметре referrer_client_id передать client_id Рекомендателя полученный в ответе на searchclient.

• иначе выдать сообщение вида "клиент с таким реферальным кодом не найден".

Проверка по пин-коду (коды подтверждения)

Проверка проходит в 2 этапа:

• Отправка кода подтверждения клиенту: askconfirmphone

• Проверка введенного кода: checkconfirmphonecode

Тип способа отправки кода подтверждения = type_confirmation_code (0 - отправка СМС код из 4 символов; 1 - отправка проверочного кода в звонке, 4 последних символов номера телефона, который сделает дозвон на указанный номер).

Считывание карт с динамическим кюар-кодом

Для считывания кьюар-кода карты необходимо передать дополнительный параметр card_apply_dt в методах searchclient и processsale в формате “02.02.2023 11:23:56”.

Параметр card_apply_dt содержит в себе дату и время по UTC 0 момента считывания карты/ввода номера телефона клиента, т.е. первый searchclient.

Поведение следующее:

• При первом считывании карты берется время кассы и приводится к часовому поясу UTC 0, например по московскому (+3) времени “02.02.2023 14:23:56”, тогда время которое должно записаться в параметр card_apply_dt “02.02.2023 11:23:56”.

• Далее это зафиксированное время передавать во все searchclient и processsale.

• Если карта отменяется, то время обнуляется.

Параметр card_apply_dt не нужно передавать, если чек не содержит клиента (карты или номера телефона).

Замена карты

Замена карты выполняется функцией replacecard.

Предлагаем сделать замену карты, если:

• введенный номер телефона уже существует в системе

• введена карта

• разрешена замена карты на кассе.

Если требуется верификация номера телефона по пин-коду подтверждения (определяем из ответа searchclient), то делаем перед отправкой проверку кодом подтверждения.

Обработка чека (документа продажи) без ввода клиента

Создание продажи выполняется тем же методом processsale, как и с клиентом, но т.к. клиента нет в client_id передаем null.

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

Также требуется подтверждение чека confirmsale (п. 4).

Обработка сообщений и ошибок от сервера kilbil

Если при любом запросе статус ответа http 403, тогда считать, что такой запрос некорректен и продолжить работу без системы лояльности.

→ Если это searchclient вывести сообщение кассиру вида "Касса не зарегистрирована в системе лояльности. Обратитесь к системному администратору!" Отменить ввод карты/клиента.

→ Если при поиске клиента result_code = 101, тогда необходимо вывести сообщение для кассира с содержимым result_text, если result_text пусто, тогда статичное сообщение вида "Ошибка запроса! Ввод карты/клиента отменен!" и отменить текущий ввод карты/клиента.

Правовая информация

Возвращает ссылки на документы с "правовой информацией" по Программе лояльности, настроенной в kilbil:

• Правила программы лояльности

• Политику в отношении персональных данных

• Согласие на обработку и передачу персональных данных