Документация 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 Промокоды (промокод на документ)

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

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

Важно! 

• Промокод можно вводить только в документе “Продажа”
• На один документ применяем только один промокод
• Промокод вводим до запроса processsale

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

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

Выполняем функцию 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 (при работе в обычном режиме, когда связь есть, можно не передавать). Дополнительных признаков оффлайна для других функций не требуется.

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

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

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

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

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

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

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

5. Активация нового клиента

Активация клиента выполняется методом addclient.

Кассир заполняет на кассе поля анкеты, данные анкетирования отправляются на сервер.

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

5.1. Активация нового клиента с использованием реферальной механики “Приведи друга”

В kilbil предусмотрен механизм учета рекомендаций (Приведи друга). Используются следующие определения:

• Рекомендатель = кто был ранее зарегистрирован в программе лояльности и порекомендовал магазин/заведение своему другу.
• Реферал = приглашенный новый клиент, который регистрируется в программе лояльности по рекомендации своего друга.

Если в личном кабинете 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.
• иначе выдать сообщение, что клиент с таким реферальным кодом не найден.

5.2. Замена карты клиента

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

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

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

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

6. Проверка кодом подтверждения

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

• Отправка кода подтверждения клиенту - askconfirmphone
• Проверка введенного кода - checkconfirmphonecode

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

7. Считывание карты в виде динамического QR-кода (используется в картах Telegram и мобильных приложениях)

Для считывания QR-кода карты необходимо передать дополнительный параметр 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  не нужно передавать, если чек не содержит клиента (карты или номера телефона).

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

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

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

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

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

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

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

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