Kilbil

Настройка

В карточке магазина указывается признак наличия обмена с Kilbil.  Обмен касс магазина с Kilbil включается только в том случае, если будет указан данный признак.

В карточках точек продаж (POS) заполняются:

В настройке интерфейса кассира следует привязать к горячим клавишам две команды: ‘Идентификация покупателя в ДС’, ‘Запрос промокода’. Эти команды используются для запуска соответствующих процессов.

 

Сценарий идентификации покупателя

Процесс запускается по команде ‘Идентификация покупателя в ДС’. По окончании процесса касса получает идентификатор покупателя. Если идентификатор не будет заполнен, то считается, что покупатель не участвует в программе лояльности.

На экране отображается форма с данными покупателя, информационной строкой, кнопками для выбора действий.

image-1733391386767.png

Поля:

Кнопки:

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

Сначала кассир вводит один из идентификаторов покупателя: номер телефона или номер карты. Номер телефона начинается с цифры 7.

После ввода телефона выполняется запрос в KB. KB по номеру телефона ищет в своей БД запись участника программы. Если поиск завершается успешно, то KB в ответе на запрос возвращает информацию об участнике программы. Касса заполняет остальные поля формы данными из ответа. 

Основные сценарии работы кассира

1. Покупатель является участником программы лояльности

Если покупатель говорит, что он является участником программы лояльности и называет номер телефона. Кассир вводит номер и нажимает клавишу 'Enter'. Касса отправляет в KB запрос. KB по номеру телефона (или номеру карты) ищет в своей БД запись участника программы. Если поиск завершается успешно, то KB в ответе на запрос возвращает информацию об участнике программы. Касса заполняет остальные поля формы данными из ответа. Далее проверяется наличие значения в поле Телефон. Если поле не заполнено, то в информационной строке отображается тест: ‘Требуется подтверждение телефона’. Если телефон заполнен, то в информационной строке появляется сообщение ‘Покупатель является участником программы лояльности’. Если KB присылает отрицательный ответ (подходящая запись в БД не обнаружена), то в информационной строке отображается ответ из KB.

Далее кассир анализирует информацию на экране и действует по одному из следующих сценариев.

Кассир нажимает кнопку ‘Выбрать’. Форма закрывается. Идентификатор покупателя определён.

Кассир вводит номер телефона и нажимает кнопку ‘Подтвердить телефон’.

Сначала касса отправляет запрос для проверки, что данный телефон ещё не зарегистрирован. Если ответ положительный, то в информационной строке отображается текст ‘Покупатель с таким телефоном уже зарегистрирован’. Выполняется возврат в форму. Кассир либо вводит другой номер телефона, либо отменяет идентификацию.

Если ответ отрицательный (т.е. в базе KB нет регистрации данного телефона), то касса отправляет в KB запрос для подтверждения номера. Если ответ отрицательный, то в информационную строку записывается сообщение об ошибке. Выполняется возврат в форму.

В случае положительного ответа отображается новая форма для запроса кода. В форме одно поле ‘Введите код’ и две кнопки: ‘Проверить’, ‘Отмена’. Покупатель называет код, полученный по sms, кассир вводит этот код и нажимает ‘проверить’. Касса отправляет запрос на проверку полученного кода. КВ возвращает результат проверки.
Если коды совпадают, то касса отправляет в KB запрос на изменение данных покупателя. Если ответ положительный, то в информационной строке отображается ‘Телефон подтверждён’. Выполняется возврат в основную форму. В информационной строке появляется сообщение ‘Покупатель является участником программы лояльности’.

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

Если код, названный покупателем, не совпадают с кодом, полученным по запросу, то в форме для запроса отображается ‘неверный код’. Кассир может повторно ввести код и нажать ‘проверить’. Если кассир нажимает ‘Отмена’, то выполняется возврат в основную форму без подтверждения телефона. В информационной строке остаётся текст ‘Требуется подтверждение телефона’.

Дальнейшие действия либо по ветке 2, либо по ветке 3.

2. Покупатель не является участником программы лояльности и не хочет участвовать

Кассир выбирает ‘Отмена’. Форма закрывается, идентификация завершается без заполнения идентификатора покупателя.

3. Покупатель не является участником программы лояльности и хочет зарегистрироваться

Кассир заполняет в форме остальные параметры. Обязательно должны быть заполнены телефон, Имя, Фамилия. Отчество и дата рождения не обязательны к заполнению. Номер карты для регистрации не нужен и будет очищен.

Далее выполняются действия по проверке телефона в базе KB и его подтверждения. Подробно эти действия описаны в ветке 1.2. Алгоритм действий такой же, но после успешного подтверждения телефона регистрация продолжается. Касса отправляет запрос на регистрацию. Если в ответе будет ошибка, то отображается текст ошибки в информационной строке. Выполняется возврат в основную форму. В случае положительного ответа форма закрывается. Идентификатор покупателя определён.

 

Запрос промокода

Процесс запускается по команде ‘Запрос промокода’. По окончании процесса касса получает название промокода. Если название промокода не заполнено, то считается, что промокода нет.

На экране отображается форма с одним полем ‘Промокод’ и двумя кнопками ‘Подтвердить’ и ‘Отмена’.  Никакие проверки введённой строки не выполняются.

Промокод будет применён в запросах в КВ для расчёта скидок.

Никаких ограничений на доступ к команде нет. Доступность команды не зависит от наличия обмена с КВ или идентификации покупателя.

Промокод на чек может быть только один. Повторный ввод промокода удаляет предыдущий.

Процесс Расчёт скидок

Данный процесс является неотъемлемой частью основных кассовых процессов заполнения и оплаты чека.

Условно процесс делится на четыре этапа:

Этапы процесса выполняются при следующих условиях:

Для запроса баллов и расчёта скидок за баллы дополнительно требуется успешная идентификация покупателя. Если покупатель не идентифицирован как участник программы лояльности, то баллы не запрашиваются.

Регулярный расчёт скидок по чеку

После каждого изменения содержания чека (добавление и удаление товаров, изменение количества) касса отправляет в КВ запрос на расчёт чека. Число баллов в запросе равно 0, чтобы КВ при расчёте скидок не учитывал баллы. В случае положительного ответа от КВ касса разбирает ответ и изменяет фактические цены товаров. Если КВ не ответил или вернул отрицательный ответ, то цены не меняются.

При отсутствии связи с КВ на экране красным цветом загорается соответствующий сигнальный символ. Если связь прервалась после предыдущего успешного запроса, то на экране высвечивается сообщение для кассира ‘Сервер лояльности недоступен’. Если на предыдущий запрос также не было ответа, то повторно сообщение не высвечивается.

Запрос баллов

Выполняется только при условии успешной Идентификации покупателя.

В процессе Идентификации КВ вернул число баллов. Эти баллы можно потратить для оплаты чека – на товары может быть рассчитана дополнительная скидка в рублях, равная числу баллов.

После перехода в режим оплаты на экране появляется окно с предложением ввести количество баллов для оплаты чека. По умолчанию в поле находится имеющееся значение баллов. Кассир по согласованию с покупателем может уменьшить это число. В форме имеются две кнопки: ‘Подтвердить’ и ‘Отмена’. Если кассир нажал ‘Подтвердить’, то число баллов для оплаты принимается равным введённому значению. Выбор кнопки ‘Отмена’ означает отказ от списания баллов.

Финальный расчёт чека

Выполняется только при условии успешной Идентификации покупателя, после запроса баллов. Касса отправляет в KB финальный запрос для расчёта скидок. В запросе должен быть заполнен тег с числом балов, чтобы KB при расчёте скидок учитывал баллы. Значение берётся из ответа на предыдущий запрос расчета чека.

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

Если покупатель отказывается от оплаты и возвращается в редактирование чека, то следует сбросить расчёт с учётом баллов. Для этого касса отправляет в KB запрос на расчёт чека с нулевым количеством баллов.

Подтверждение оплаты чека

Выполняется после полного оформления чека, когда покупатель оплатил покупку и чек отправлен на ФР.

Касса отправляет в KB запрос для подтверждения покупки.

Если KB вернул ошибку, то повторяем расчет чека и ещё раз подтверждение покупки. Если опять ошибка, то чек сохраняется в списке неотправленных чеков.

Если связь с KB отсутствует, то чек также сохраняется в списке неотправленных чеков.

Список неотправленных чеков нужен только для тех чеков, по которым был выполнен расчёт скидок, покупатель оплатил чек, но информация о покупке в КВ не была передана. Т.е. КВ расчёты выполнил, но запрос на создание покупки не получил.

 

Процесс Возврат товара

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

Кассир вводит реквизиты чека продажи (фискальный номер, дата, номер смены). Поиск чека сначала выполняется в базе кассы. Если чек не обнаружен, то выполняется поиск в ЦБД. Цель поиска - определить реквизиты чека продажи в Домино для формирования номера этого чека в КВ.

При создании чека в КВ номер чека был создан по следующему шаблону: <Код структурного подразделения> - <код кассы> - <номер смены> - <дата чека> - <номер чека>.

Выполняется запрос покупки в КВ. Если КВ вернул чек, то работаем с ним. В противном случае (например, нет связи с КВ) считаем, что чек продажи не определён. Для оформления возврата нужны номера позиций в чеке.  В запросе указываются изменённые позиции. 

После окончания денежных расчётов касса отправляет в КВ запрос для оформления возврата и списания бонусов. Запрос создаётся только в том случае, если известен чек продажи. Если возврат создан без чека продажи, то невозможно заполнить идентификатор чека в КВ, и, следовательно, запрос не отправляется.

Ответ из КВ заносится в протокол. Касса продолжает работу в обычном режиме.

 

Список запросов в KilBil

Общие положения по обмену с KB

https://ru.sailplay.dev/reference/ogranicheniya-api

Запуск запроса: https://bonus.kilbil.ru/load/{название_функции}?h={ключ}

Тело запроса должно соответствовать формату JSON.

Время ожидания ответа от KB указывается в карточке компании. Касса отправляет запрос и ждёт ответа указанное время. Если KB не отвечает, то данная ситуация считается ошибкой ‘Сервер лояльности недоступен’. Касса продолжает работу без обмена с KB.

Если в ответе на запрос приходит код 200, то ответ положительный. Любые другие значения кода ответа и отсутствие ответа трактуются как отрицательный ответ.

Действия при получении отрицательного ответа зависят от  запроса и места вызова.

Запрос

Место

Действие при ошибке

searchklient

Открытие смены

Выставить состояние ‘связь отсутствует’

 

Начало чека при отсутствии связи

Ничего не делать

searchklient

Форма идентификации покупателя

Отобразить ответ в информационной строке

askconfirmphone

checkconfirmphone

Форма идентификации покупателя

Отобразить ответ в информационной строке

 addclient

Форма идентификации покупателя

Отобразить ответ в информационной строке

processsale

При изменении чека

Выставить состояние ‘связь отсутствует’

 

В конце чека

Выставить состояние ‘связь отсутствует’

confirmsale

После оплаты

Выставить состояние ‘связь отсутствует’

Поместить чек в список неотправленных чеков

getdetailingbymove

Запрос чека продажи

Выставить состояние ‘связь отсутствует’

Тексты запросов и подробные ответы протоколируются в логах кассы.

Действия в случае отсутствия связи с KB

В карточке компании указывается время ожидания ответа на запрос к KB. По истечении указанного времени считается, что связь с KB отсутствует. На экране появляется сообщение для кассира об отсутствии связи с программой лояльности. Соответствующий сигнальный символ в левом верхнем углу экрана загорается красным цветом. Сообщение о потере связи отображается только один раз – при первом неудачном запросе. Для последующих запросов сообщение не выводится. После восстановления связи лампочка загорается зеленым цветом.

Связь с KB проверяется в начале чека запросом searchklient для телефона 70000000000. Если связь отсутствует, то при работе с данным чеком запросы в KB не посылаются.

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

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

Информация об участниках (клиентах) программы лояльности

Запись клиента имеет два уникальных идентификатора: номер карты, номер телефона. Для старых клиентов номер карты будет заполнен, а номер телефона может быть пустым.

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

Ввод адреса электронной почты, объединение клиентов будут выполняться только в личном кабинете КВ.  https://help.kilbil.ru/93-1075-614--kak-dobavit-klienta-cherez-lichnyj-kabinet/

Запрос ‘Получить информацию о клиенте’                                                       searchclient

https://bonus.kilbil.ru/load/searchclient

Запрос:

Параметр

описание

search_mode

0 – поиск по № телефона

2 – поиск по № карты

search_value

 

значение, по которому производится поиск, если по номеру телефона, это должно быть 11 символов первая 7-ка

Ответ:

Параметр

описание

result_code

код результата, где 0 - успешно

client_id

id клиента, null если не найден

bonus_balance

количество бонусов у клиента

card_code

номер карты, null если нет

phone

номер телефона клиента, null если не заполнено

birth_date

дата рождения клиента, null если не заполнено

first_name

имя клиента, null если не заполнено

middle_name

отчество клиента, null если не заполнено

last_name

фамилия клиента, null если не заполнено

max_bill_bonus_out

максимальная сумма списания на текущий чек без учета баланса клиента, параметр нужен для дальнейшего использования в processsale
Запрос ‘Отправить код подтверждения’                                                   askconfirmphone

https://bonus.kilbil.ru/load/askconfirmphone

Запрос:

Параметр

Описание

client_id

id клиента

phone

номер телефона клиента 11 символов, первая 7

sms_type

тип шаблона сообщения

0 - сообщение с пин-кодом подтверждения для регистрации клиента

1 - сообщение с пин-кодом, например для списания бонусов

Ответ:

Параметр

Описание

success

код выполнения

result_code

код результата, где 0 - успешно
Запрос ‘Проверить код подтверждения’                                              checkconfirmphone

https://bonus.kilbil.ru/load/checkconfirmphonecode

Запрос:

Параметр

Описание

client_id

id клиента

phone

номер телефона клиента 11 символов, первая 7

code

код подтверждения

Ответ:

Параметр

Описание

success

код выполнения

result_code

код результата, где 0 - успешно
Запрос ‘Добавление (обновление) клиента’                                             addclient           

https://bonus.kilbil.ru/load/addclient

Запрос:

Параметр

Описание

client_id

id клиента

phone

номер телефона клиента 11 символов, первая 7, клиент не будет активирован без номера телефона

Ответ:

Параметр

Описание

success

код выполнения

client_id

id клиента

result_code

код результата, где 0 - успешно

Расчёт скидок

Для промежуточных расчётов применяется запрос processsale. Непосредственно перед оплатой следует запросить число баллов и отправить финальный запрос processsale для учёта баллов.

Подтверждение покупки в KB выполняется отдельным запросом.

Запрос ‘Рассчитать документ’                                                                       processsale

https://bonus.kilbil.ru/load/processsale

Параметр

Описание

client_id

id клиента, null – если покупатель не идентифицирован

type

тип операции: 0 – продажа, 1 - возврат

bonus_out

количество списанных бонусов в операции

max_bonus_out

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

good_data

Массив товаров

    code

Код товара

    vendor_code

Артикул

   name

Наименование товара

   price

цена

   quantity

количество

   total

Сумма за позицию

   minPrice

Минимальная цена

   discounted_price

Цена за позицию, равна price

   discounted_total

Сумма за позицию, равна total

move_id

Номер чека

doc_open_dt

Дата чека

return_move_id

номер чека продажи, по которому производится возврат (передаётся только для возвратов)

return_doc_dt

Дата чека продажи (передаётся только для возвратов)

promo_codes

Список промокодов

     coupons

Массив купонов

           coupon

промокод

Move_id потребуется для возврата и он должен быть уникальным. Заполняем из следующих параметров: <Код структурного подразделения> - <код кассы> - <номер смены> - <дата чека> - <номер чека>.

Поскольку применяются только скидки через систему лояльности, то price=discounted_price, Total= discounted_total.

Промокод может быть только один. Кассир его ввёл в процессе ‘запрос промокода’.

Ответ:

Параметр

Описание

result_code

код результата, где 0 – успешно

bill_data

информация по расчету документа

   items

Массив товаров

      code

Код товара

      discounted_price

Новая цена

      price

Цена

      bonus_out

Количество списанных бонусов на позицию

   bonus_out

Количество списанных бонусов на документ
Запрос ‘Подтвердить документ’                                                                     confirmsale

https://bonus.kilbil.ru/load/confirmsale

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

Параметр

Описание

move_id

Номер чека

doc_open_dt

Дата чека

doc_dt

Дата закрытия чека

Ответ:

Параметр

Описание

result_code

код результата, где 0 – успешно

Возврат товаров

Для создания чека возврата применяется запрос ‘Рассчитать документ’ (processsale с type=1).

Предварительно в базе KB запрашивается чек продажи.

Запрос ‘Получить документ’                                                                 getdetailingbymove

https://bonus.kilbil.ru/load/getdetailingbymove

Параметр

Описание

move_id

Номер чека

Ответ:

Параметр

Описание

result_code

код результата, где 0 – успешно

move_info

общая информация по чеку

   oper_type

Тип операции: 0 –продажа

move_detail

Массив товаров

   code

Код товара

   price

Цена

   total

Сумма по позиции

   quantity

количество

 

Выгрузка справочника товаров в KilBil

https://docs.kilbil.ru/#tag/Nomenklatura/operation/goods

Предусмотрены два режима выгрузки товаров в КВ:

  1. Полная выгрузка
  2. Инкрементальная выгрузка

Полная выгрузка запускается вручную из меню. Выгружаются все товары в КВ.

Товары выгружаются порциями по 2000 товаров.

Инкрементальная выгрузка обрабатывает только изменения товаров с момента предыдущей выгрузки. Запускается либо вручную из меню, либо автоматически планировщиком.

Совместно с карточками товаров выгружаются группы и категории, 4 уровня классификатора.

Запрос:

Параметр

Описание

partial

0 – полная, 1 – инкрементальная

is_group

True – для групп и категорий

False – для товаров

delete_mark

True в случае инкрементальной выгрузки

code

 

Код товара в Домино или код группы/категории

name

 

Наименование товара или наименование группы/категории

Inside

Следующий уровень группы/категории внутри группы или товар внутри категории.

Включает параметры is_group, delete_mark, code, name, inside

Ответ:

Параметр

Описание

Success

1 – успешно

result_code

0 - успешно

Пример:
{"is_group": true,

"delete_mark": false,

"code": "1",

"name": "Название группы",

"inside": []

},

    {

    "is_group": true,

    "delete_mark": false,

    "code": "5",

    "name": "Название группы 3",

    "inside": [

         {

         "is_group": false,

         "delete_mark": false,

         "code": "706",

         "name": "Наименование товара"

          },

         {

         "is_group": false,

          "delete_mark": false,

           "code": "610",

           "name": "название товара"

           }

    ]

}