Документация API находится по ссылке

Обработка документа продажи с клиентом (с вводом номера карты/телефона/электронной карты)

1. Ввод карты клиента (телефона, если без карт)

1. Ввод номера карты/телефона осуществляется в одном интерфейсном окне. При этом необходимо запретить ввод карты клиента вручную, только с оборудования и разрешить ручной ввод только для номера телефона.
2. После получения номера карты/телефона выполняем запрос searchclient с соответствующим search_mode (0 – поиск по № телефона, 1 – поиск по внутреннему № карты), также с заполненными параметрами goods_data и promo_codes, эти параметры передаются для предварительного расчета чека для возврата доступной суммы списания с учетом акций и ограничений.

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

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

Пример окна с возможностью списания бонусов, окно без списания бонусов такое же, но без ввода. Основная информация:

• ФИО клиента
• название программы лояльности
• сумма по чеку (которая пришла из kilbil после расчётов discounted_total)
• бонусный баланс
• лимит списания бонусов на чек
• если включена настройка показывать сумму покупок, тогда выводим purchases_sum
• если статус клиента не пуст, тогда выводим статус last_month_status
• если есть сообщение с тегами, выводим его tags
• если есть сообщение с любимыми товарами тогда выводим его top_sales

После всех проверок пп 2.1 и 2.2 и в случае необходимости клиента активировали или нет выводим бонусное окно (не выводим для дисконтной программы лояльности program_type не равно 1), при этом:

• показываем бонусное окно со списанием если: введена карта или only_with_cards = 0 или use_sms_code > 0
• может быть параметр требования кода подтверждения в зависимости от суммы списания, смотрим на параметр sms_code_sum, если он больше 0 то запрашиваем код подтверждения от суммы больше или равно суммы в sms_code_sum
• в остальных случаях без возможности списания

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

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

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

Проверяем состояние клиента и карты, если state = 2, значит клиент заблокирован, или card_state не равно 0, тогда информируем кассира о состоянии клиента/карты и отменяем ввод карты.

Если тип программы лояльности подарочный сертификат (program_type = 3), тогда проверяем на какой тип списания настроено (program_write_off_type), если program_write_off_type = 1, означает что тип списания видом оплаты, тогда информируем что подарочный сертификат настроен на тип оплаты, и применять как бонусную карту его нельзя, отменить ввод карты.

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

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

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

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

Клиент считается активированным, если state = 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_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_footer   реклама для подвала чека

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

Для случаев когда сервер kilbil не доступен, например нет интернета на кассе.

Если сервер не доступен на стадии поиска клиента searchclient, необходимо сообщить продавцу “Нет связи с системой лояльности. Не удалось получить данные о клиенте. Нажмите ОК”, дальнейшие запросы processsale и confirmsale сохраняем для дальнейшей отправки. Кассиру не разрешаем списывать бонусы и не показываем бонусное окно, так как нет никакой информации.

Если сервер не доступен на стадии создания документа в kilbil processsale, сообщаем кассиру о том что нет связи с системой лояльности, при этом если было указано списание бонусов, необходимо обнулить списание, так как скидка не распределилась, и сохранить запрос для дальнейшей отправки. confirmsale сохраняется без попытки подключения к серверу.

Если сервер не доступен на стадии подтверждения чека 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.

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

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

Аналогично как с активацией нового клиента может понадобиться проверка кодом подтверждения (п. 6).

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

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

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

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

7. Считывание электронной карты в виде динамического QR-кода

Для считывания 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 определяет самостоятельно применение тех или иных акций, в том числе акции для авторизованных и неавторизованных клиентов.

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

Обработка сообщений и ошибок от системы лояльности

Если при любом запросе статус ответа http 403 тогда считать, что такой запрос некорректен и продолжить работу без системы лояльности. Если это searchclient вывести сообщение кассиру "Рабочее место не зарегистрировано в системе лояльности! Обратитесь к системному администратору." И  отменить ввод карты.

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