Список запросов в 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	количество