Бонусная система kilbil
Сайт компании kilbil.ru.
Платформа управления лояльностью bonus.kilbil.ru.
Техподдержка support@kilbil.ru.
Описание API functions
Общая информация
Каждый запрос с кассы сопровождается APIKEY - Уникальный идентификатор рабочей станции, который является ключом.
Процесс запроса ключа:
- На кассе запускается специальный EXE , возникает окно ввода
- Название сети магазинов
- Код клиента (для более простого сопоставления с базой данных)
- Название магазина
- Адрес магазина
- Номер рабочего места (внутренний номер в базе клиента)
- ФИО, кто запросил ключ
- телефон для обратной связи
- Комментарий
- по кнопке "запрос ключа" - идет отправка команды на сервер.
- В личном кабинете у администратора бонусных систем на закладке "заявки на подключение" возникает строка, содержащая всю информацию, которая пришла в запросе
- Оператор вручную сопоставляет этому ключу базу данных (по названию клиента) и торговое оборудование из данной базы данных. По сути сопоставляет APIKEY с торговым оборудованием.
- На кассе должна быть также возможность узнать статус запроса ключа: Готов, отклонен, ожидает обработки
В дальнейшем касса, посылая все запросы с ключем APIKEY . Сервис обработки ретранслирует запрос в нужную базу данных с найденным в базе ключей идентификатором торгового оборудования уже без APIKEY ! Таким образом в самой базе данных клиента нет APIKEY , что позволит администрировать ключи посредством сервиса ретрансляции, даже, если база данных находится у клиента .
addclient – создание клиента и активация клиента, для конфигураций с использованием карт и без
Входные параметры:
https://bonus.kilbil.ru/load/addclient?h={ключ}
Входные параметры:
{
"client_id":"4004565",
"phone":"79129999999",
"first_name":"Дарья",
"last_name":"Петрова",
"middle_name":"Владимировна",
"birth_date":"02.10.1997",
"sex":"0",
"email":"ex@email.ru",
"shift_open_dt":"09.11.20 08:01:44",
"special_days": [
{
"id": 90,
"value": "07.07.2017"
},
{
"id": 265,
"value": "03.03.2018"
}
],
"promo_code": "promo2023"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| phone | text | номер телефона |
| sms_code | text | код подтверждения |
| client_id | integer = null::integer | id клиента |
| first_name | text = null::text | Имя |
| middle_name | text = null::text | Отчество |
| last_name | text = null::text | Фамилия |
| birth_date | text = null::text | Дата рождения в любом формате даты |
| sex | integer = null::integer | Пол: 0 – женский, 1- мужской |
| text = null::text | Адрес электронной почты | |
| not_to_send_sms | integer = null::integer | Не отправлять информационных смс (1 - не отправлять) |
| not_to_send_email | integer = null::integer | Не отправлять информационных e-mail (1 - не отправлять) |
| referrer_client_id | integer = null::integer | id клиента издателя (клиента-друга, на которого подписывается данный клиент) |
| outer_systems_interface_type | smallint = null::smallint | Тип интерфейса внешней системы (0-cardPr, 1-IQOS, 2-OneDelivery, 3-OSMI, 4-CardsMobile(Кошелёк), 5-Custom application(Внешнее приложение)) |
| card_code | text | короткий номер карты, который нужно создать (уникальное поле, коды не могут быть одинаковыми) |
| card_barcode | text | номер карты (barcode), для создаваемой карты |
| generate_card | smallint | Генерировать ли для клиента электронную карту (Wallet). Для работы этого параметра необходимо включить соответствующую системную настройку |
| shift_open_dt | timestamp | Дата и время открытия смены (используется для расчёта показателя по активированным клиентам на кассе) |
| special_days | jsonb | Массив специальных дат, id специальных дат нужно брать из ответа функции searchclient параметр special_days_types |
| promo_code | text | промокод при активации клиента, для применения акцияй с типом "При действии с клиентом" |
Описание возвращаемого результата выполнения:
Выходные параметры:
{
"success": 1,
"client_id": 4004565,
"result_code": "0",
"result_text": "Данные клиента изменены"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| success | integer | код результата |
| result_code | integer | код результата 2 |
| result_text | text | текст результата |
| client_id | integer | id клиента |
| error | integer | 0,1 |
| error_text | text | Сообщение об ошибке |
| result_code | result_text | Описание |
|---|---|---|
| 0 | Код подтвержден, данные клиента изменены | Данные клиента изменены |
| 1 | Неверный пин-код | Передана неверный код подтверждения |
| 2 | Данные клиента не изменены, так как не удалось найти клиента по заданному id | Данные клиента не изменены, так как не удалось найти клиента по заданному id |
| 3 | Клиент с указанным номером телефона уже зарегистрирован | В системе уже сохранен действующий клиент с указанным номером телефона (для действующих клиентов номер телефона должен быть уникальным) |
| 4 | Использование электронных карт (Wallet) отключено в системных настройках | Использование электронных карт (Wallet) отключено в системных настройках |
| 5 | Ошибка при сохранении карты | Клиент не создан, так как не удалось сохранить сгенерированную электронную карту (Wallet) |
addclienttags – добавление тегов клиенту
Входные параметры:
https://bonus.kilbil.ru/load/addclienttags?h={ключ}
Входные параметры:
{
"client_id": 7974,
"tags": [
676,
496
]
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| client_id | integer | id клиента |
| tags | jsonb | массив id тегов, можно получить из запроса getlisttags |
Описание возвращаемого результата выполнения:
Выходные параметры:
{
"result_code": 0,
"result_text": ""
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| result_code | integer | код результата, где 0 - успешно |
| result_text | text | текст результата |
askconfirmphone – команда отсылки кода подтверждения
Входные параметры:
https://bonus.kilbil.ru/load/askconfirmphone?h={ключ}
Входные параметры:
{
"client_id":"4004565",
"phone":"79129999999",
"sms_type":1,
"send_type":0
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| client_id | integer | id клиента |
| phone | text | номер телефона |
| sms_type | integer | тип шаблона смс (0 - СМС с пин-кодом подтверждения для регистрации клиента; 1 - CМС с пин-кодом подтверждения для авторизации покупки) |
| is_limited | boolean | если задан лимит в настройка, то смс с параметром true может уходить не чаще заданного лимита (функционал для виджетов, сайтов, приложений), не обязательный параметр, по умолчанию false |
| send_type | integer | Не обязательное поле, указывается в случае принудительной отправки нужного типа (0 - СМС, 1 - звонком (если подключено)) |
Описание возвращаемого результата выполнения:
Выходные параметры:
{
"success": 1,
"result_code": "0",
"result_text": "Код отправлен в СМС",
"type_confirmation_code": "0"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| success | integer | Успешное выполнение отправки СМС |
| result_code | integer | Код результата |
| result_text | text | Описание выполнение результата |
| type_confirmation_code | integer | Тип способа отправки кода подтверждения (0 - отправка СМС код из 4 символов; 1 - отправка проверочного кода в звонке, 5 последних символов номера телефона, который сделает дозвон на указанный номер) |
В случае ошибки будет параметр error
blockcard – блокировка карты клиента
Входные параметры:
https://bonus.kilbil.ru/load/blockcard?h={ключ}
Входные параметры:
{
"card_id": 3968043
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| card_id | integer | id карты клиента (есть в ответе запроса searchclient) |
Описание возвращаемого результата выполнения:
Выходные параметры:
{
"result_code": "1",
"result_text": "Карта заблокирована"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| result_code | integer | Код результата |
| result_text | text | текст результата |
checkconfirmphone – команда проверки кода от пользователя. Как отдельная функция нужна только для подтверждения списания. Для активации код отправляется вместе с регистрационными данными
Входные параметры:
https://bonus.kilbil.ru/load/checkconfirmphone?h={ключ}
Входные параметры:
{
"client_id":"4004565",
"phone":"79129999999",
"code":"8848"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| client_id | integer | id клиента |
| code | text | Код подтверждения |
| phone | text | номер телефона |
Описание возвращаемого результата выполнения:
Выходные параметры:
{
"success": 1,
"result_code": "0"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| success | integer | Успешное выполнение отправки СМС |
| result_code | text | Код результата |
В случае ошибки будет параметр error
checkconfirmphonecode – команда проверки кода от пользователя. Независима от других системных настроек, то есть просто проверяет код подтверждения
Входные параметры:
https://bonus.kilbil.ru/load/checkconfirmphonecode?h={ключ}
Входные параметры:
{
"client_id":"4004565",
"phone":"79129999999",
"code":"8848"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| client_id | integer | id клиента (NULL если ещё нет id клиента, например при активации) |
| phone | text | номер телефона |
| code | text | Код подтверждения |
Описание возвращаемого результата выполнения:
Выходные параметры:
{
"success": 1,
"result_code": "0"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| success | integer | Введен верный код подтверждения |
| result_code | text | Код результата |
В случае ошибки будет параметр error
closesession - информация о закрытии смены
Входные параметры:
https://bonus.kilbil.ru/load/closesession?h={ключ}
Входные параметры:
{
"payments": [
{
"payment_amount": "118",
"type": 0
},
{
"payment_amount": "68.3",
"type": 1
}
],
"shift_close_dt": "27.10.2020 17:58:20",
"shift_number": "554"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| shift_close_dt | timestamp | дата и время закрытия смены |
| shift_number | smallint | номер смены |
| payments | jsonb | виды оплат в закрытой смене (0 - наличные, 1 - банковская карта, 2 - сертификат kilbil, 3 - пользовательская оплата, 99 - другой вид оплаты) |
Описание возвращаемого результата выполнения:
Выходные параметры:
{
"result_code": "0",
"result_text": "Добавлена новая запись смены"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| result_code | integer | код результата |
| result_text | text | текст результата |
confirmsale - подтверждение чека (для конфигураций не требующих пересчета чека при подтверждении)
Входные параметры:
https://bonus.kilbil.ru/load/confirmsale?h={ключ}
Входные параметры:
{
"move_id":"101279",
"doc_open_dt":"09.11.20 17:27:35",
"doc_dt":"09.11.20 17:29:14",
"shift_open_dt":"09.11.20 08:01:44",
"kkm_serial_number":"",
"kkm_doc_number":"",
"kkm_fiscal_sign":null,
"username":"Кассир",
"useruid":"1",
"payments":[
{
"type":0,
"payment_amount":50
},
{
"type":1,
"payment_amount":41.47
}
]
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| move_id | text | id чека на торговом оборудовании (не меньше 4 символов) |
| doc_open_dt | timestamp | Дата и время открытия документа |
| doc_dt | timestamp | Дата и время закрытия документа |
| shift_open_dt | timestamp | Дата и время открытия смены |
| is_offline | smallint | Отправлено ли подтверждение оффлайн-службой: 0 - нет, 1 - да |
| kkm_serial_number | text | Серийный номер Фискального Накопителя (ФН) |
| kkm_doc_number | integer | Номер Фискального Документа (ФД) |
| kkm_fiscal_sign | bigint | Фискальный Признак Документа (ФП) |
| username | text | ФИО кассира, закрывшего документ |
| useruid | text | uuid кассира, закрывшего документ |
| payments | jsonb | Применённые виды оплат на документ (0 - наличные, 1 - банковская карта, 2 - сертификат kilbil, 3 - пользовательская оплата, 99 - другой вид оплаты) |
Описание возвращаемого результата выполнения:
Выходные параметры:
{
"result_code": "0",
"result_text": "Продажа успешно подтверждена"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| result_code | integer | код результата |
| result_text | text | текст результата |
| result_code | result_text | Описание |
|---|---|---|
| 0 | Продажа успешно подтверждена | Неподтвержденная продажа найдена и подтверждена |
| 1 | Неподтвержденная продажа по заданным параметрам не найдена | Неподтвержденная продажа по заданным параметрам не найдена |
deleteclienttags – удаление тегов у клинета
Входные параметры:
https://bonus.kilbil.ru/load/deleteclienttags?h={ключ}
Входные параметры:
{
"client_id": 7974,
"tags": [
676,
496
]
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| client_id | integer | id клиента |
| tags | jsonb | массив id тегов, можно получить из запроса getlisttags |
Описание возвращаемого результата выполнения:
Выходные параметры:
{
"result_code": 0,
"result_text": "Удаление завершено"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| result_code | integer | код результата, где 0 - успешно |
| result_text | text | текст результата |
exchangepossettings - информация о кассовом ПО и параметры настройки
Входные параметры:
https://bonus.kilbil.ru/load/exchangepossettings?h={ключ}
Входные параметры:
{
"pos_program": "Frontol",
"version": "12.0.5",
"autoupdate": 0
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| pos_program | text | Название кассового ПО |
| version | text | Версия скрипта, приложения или доработки |
| autoupdate | smallint = 0::smallint | Автоматическое обновление скрипта (параметр нужно передавать только для Frontol с стандартным скриптом) |
Описание возвращаемого результата выполнения:
Выходные параметры:
{
"success": 1,
"result_code": 0,
"registration_fields": {
"last_name": 1,
"first_name": 1,
"middle_name": 0,
"sex": 1,
"birth_date": 1,
"show_sum_purchases": 1
},
"save_nonbonus_moves": "1",
"osmi_cards_are_used": "1"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| success | integer | код результата |
| result_code | integer | код результата |
| registration_fields | jsonb | параметры для анкетирования |
| save_nonbonus_moves | smallint | сохранение продаж без применения клиентов |
| osmi_cards_are_used | smallint | использование интерфейса OSMI |
generatecard – генерация электронной карты, для уже существующего клиента без карты этого типа (OSMI и CardsMobile)
Входные параметры:
https://bonus.kilbil.ru/load/generatecard?h={ключ}
Входные параметры:
{
"client_id": 89630,
"outer_systems_interface_type": 4
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| client_id | integer | id клиента |
| outer_systems_interface_type | smallint | Тип интерфейса внешней системы (3-OSMI, 4-CardsMobile(Кошелёк)) |
Описание возвращаемого результата выполнения:
Выходные параметры:
{
"result_code": "0",
"result_text": "Карта успешно создана"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| result_code | integer | код результата |
| result_text | text | текст результата |
| card_code | text | номер сгенерированной карты |
| result_code | result_text | Описание |
|---|---|---|
| 0 | Карта успешно создана | Карта успешно сгенерирована |
| 1 | Использование электронных карт (Wallet) отключено в системных настройках | Использование электронных карт (Wallet) отключено в системных настройках |
| 2 | Ошибка при сохранении карты | Клиент не создан, так как не удалось сохранить сгенерированную электронную карту (Wallet) |
getactionslist – метод позволяет получить акции на изменение цены и применению скидок для товаров
Может использоваться например для печати ценников, для определенной торговой точки
Входные параметры:
https://bonus.kilbil.ru/load/getactionslist?h={ключ}
Входные параметры:
{
"trade_object_id": 123,
"goods":[
"4369",
"5712"
]
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| trade_object_id | integer | id торговой сети, в случае хранения товаров по сетям или торговой точки в случае хранения товаров по торговым точкам, в случае хранения по фирмам передать null |
| goods | text | массив кодов товаров, по которым необходимо получить информацию по акциям |
Описание возвращаемого результата выполнения:
Выходные параметры:
{
"result_code": 0,
"result_text": "Выполнено успешно",
"goods": {
"3957": [
{
"action": 20461,
"respond": 91813
},
{
"action": 4613,
"respond": 21479
},
{
"action": 19504,
"respond": 87469
}
],
"4369": [
{
"action": 20461,
"respond": 91813
},
{
"action": 19504,
"respond": 87469
}
]
},
"actions": [
{
"id": 20461,
"action": "Акция цена",
"responds": [
{
"id": 91813,
"value": 89,
"do_type": "Цена",
"unit_type": "%",
"work_type": "Применить и ограничить"
}
],
"auth_type": "Все",
"week_days": [
1,
2,
3,
4,
5,
6,
7
],
"action_end": null,
"action_begin": "28.12.2022",
"trade_objects": [
"ТЕСТОВЫЙ МАГАЗИН"
],
"time_limit_end": "23:59:59",
"run_count_limit": null,
"actions_programs": null,
"time_limit_begin": "00:00:00",
"run_count_limit_client": 0
},
{
"id": 4613,
"action": "Тестовая скидка",
"responds": [
{
"id": 21479,
"value": 5,
"do_type": "Скидка",
"unit_type": "%",
"work_type": "Применить"
}
],
"auth_type": "Авторизованные",
"week_days": [
1,
2,
3,
4,
5,
6,
7
],
"action_end": null,
"action_begin": "26.10.2020",
"trade_objects": [
"1С Касса",
"ТЕСТОВЫЙ2 (Артикс)",
"ТЕСТОВЫЙ3 (Фронтол)",
"Магазин Демо",
"Тестовый3",
"Магазин"
],
"time_limit_end": "23:59:59",
"run_count_limit": null,
"actions_programs": null,
"time_limit_begin": "00:00:00",
"run_count_limit_client": 0
},
{
"id": 19504,
"action": "Расчет покупки (тест)",
"responds": [
{
"id": 87469,
"value": 5,
"do_type": "Скидка",
"unit_type": "%",
"work_type": "Применить"
}
],
"auth_type": "Все",
"week_days": [
1,
2,
3,
4,
5,
6,
7
],
"action_end": null,
"action_begin": "08.12.2022",
"trade_objects": [
"1С Касса"
],
"time_limit_end": "23:59:00",
"run_count_limit": null,
"actions_programs": null,
"time_limit_begin": "00:00:00",
"run_count_limit_client": 0
}
]
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| result_code | integer | код результата |
| result_text | text | описание результата |
| goods | jsonb | Массив кодов товаров, который был отправлен в запросе, содержащих в себе массив объектов с id акций и id действий, в которых участвует товар |
| actions | jsonb | Массив объектов описаний акций, которые присутствуют в goods |
Описание объекта товаров:
Содержит в себе код или sku товара (то что было отправлено в запросе) как ключ параметра, и как значение содержит массив объектов содержащие следующие поля:
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| action | integer | id акции где участвует товар |
| respond | integer | id действия акции где участвует товар |
Описание массива акций:
Содержит в себе объекты акций с описанием:
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| id | integer | id акции |
| action | text | название акции |
| responds | jsonb | массив объектов действий акций |
| auth_type | text | Виды покупателей по авторизации |
| week_days | Array | Массив дней с понедельника (1) по воскресенье (7) |
| action_end | text | Дата окончания акции |
| action_begin | text | Дата начала акции |
| trade_objects | Array | Названия магазинов, участвующих в акции (пусто значит все магазины) |
| time_limit_end | text | Ежедневное время окончания акции |
| run_count_limit | integer | Количество применений акции |
| actions_programs | Array | Массив с ограничений по названиям программам лояльности |
| time_limit_begin | text | Ежедневное время начала акции |
| run_count_limit_client | integer | Количество применений акции для одного покупателя |
Описание объекта действий акций:
Содержит в себе объекты действий акций:
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| id | integer | id действия акции |
| value | integer | значение |
| do_type | text | Описание типа дейсвтия |
| unit_type | text | Описание типа применения |
| work_type | text | Описание приоритетов применения и ограничения |
getclientcards – получение информации по существующим картам клиента
Входные параметры:
https://bonus.kilbil.ru/load/getclientcards?h={ключ}
Входные параметры:
{
"client_id":"11280901"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| client_id | integer | id клиента |
| outer_systems_interface_type | smallint = NULL::smallint | Тип интерфейса внешней системы (0-cardPr, 1-IQOS, 2-OneDelivery, 3-OSMI, 4-CardsMobile(Кошелёк), 5-Custom application(Внешнее приложение), 10-Виртуальная карта), без этого параметра вернутся все действующие карты клиента |
Описание возвращаемого результата выполнения:
Выходные параметры:
{
"result_code": 0,
"cards": [
{
"code": "0031",
"barcode": "300031",
"card_id": 10963298,
"outer_systems_interface_name": null,
"outer_systems_interface_type": null
}
]
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| result_code | integer | код результата |
| cards | jsonb | Массив объектов с реквизитами карт |
getclientfullbalance - получение полного баланса клиента
Входные параметры:
https://bonus.kilbil.ru/load/getclientfullbalance?h={ключ}
Входные параметры:
{
"client_id":"4004565"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| client_id | text | id клиента |
Описание возвращаемого результата выполнения:
Выходные параметры:
{
"0": {
"balance": "24.56",
"begin_dt": null,
"expire_dt": "2021-07-03 11:47:28.727666"
},
"1": {
"balance": "35.40",
"begin_dt": null,
"expire_dt": "2021-07-03 11:49:36.987718"
},
"2": {
"balance": "11.21",
"begin_dt": null,
"expire_dt": "2021-07-03 11:50:15.366485"
},
"3": {
"balance": "5.61",
"begin_dt": null,
"expire_dt": "2021-07-03 11:54:52.768847"
},
"4": {
"balance": "60.62",
"begin_dt": null,
"expire_dt": null
}
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| balance | numeric | код результата |
| begin_dt | timestamp | дата и время начала действия бонусов (заполнен у отсроченных бонусов) |
| expire_dt | timestamp | дата и время окончания действия (“сгорания”) бонусов |
getclienttags – получить список тегов у клиента
Входные параметры:
https://bonus.kilbil.ru/load/getclienttags?h={ключ}
Входные параметры:
{
"client_id": 7974
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| client_id | integer | id клиента |
Описание возвращаемого результата выполнения:
Выходные параметры:
{
"result_code": 0,
"data": [
221,
242
]
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| result_code | integer | код результата, где 0 - успешно |
| data | jsonb | массив id тегов |
getconfirmationcode - получение номера временной карты для авторизации в системе
Входные параметры:
https://bonus.kilbil.ru/load/getconfirmationcode?h={ключ}
Входные параметры:
{
"client_id":"4004565",
"outer_systems_interface_type":"5"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| client_id | integer | id клиента |
| outer_systems_interface_type | smallint | Тип интерфейса внешней системы (5-Custom application(Внешнее приложение)) |
Описание возвращаемого результата выполнения:
Выходные параметры:
{
"confirmation_code": "065189"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| confirmation_code | text | номер временной карты |
getdetailingbymove - получение информации по документу
Входные параметры:
https://bonus.kilbil.ru/load/getdetailingbymove?h={ключ}
Входные параметры:
{
"id": 155912975,
"move_id": "frl-050422-180306-79365",
"move_date": "05.04.2022 18:03:43"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| id | integer | Внутренний id операции |
| move_id | text | Внешний номер операции, присланный с кассы |
| move_date | timestamp | Точная дата документа |
Описание возвращаемого результата выполнения:
Выходные параметры:
{
"move_info": {
"id": 155912975,
"move_id": "frl-050422-180306-79365",
"bonus_in": 218.85,
"discount": 50,
"bonus_out": 0,
"client_id": 15251728,
"move_asum": 2188.4,
"move_actions":[
{
"action_id": 123,
"action_name": "Название акции"
}
],
"move_bonuses":[
{
"bonus_in": 218.85,
"expire_date": null,
"bonus_in_date": "2022.04.05 18:03:43"
}
],
"bonus_presents":[
{
"bonus_in": 100.00,
"action_id": 3872,
"action_name": "Подарочек",
"expire_date": "2023.04.05 18:03:43",
"bonus_in_date": "2022.04.05 18:03:43"
}
],
"move_date": "05.04.2022 18:03:43",
"oper_type": 0,
"move_total": 2188.4,
"is_reserved": false,
"promo_codes": ["20220224001"],
"is_confirmed": true,
"shift_number": 552
},
"move_detail": [
{
"code": "5375",
"name": "Товар 1",
"price": 209.85,
"total": 820.65,
"actions":[
{
"action_id": 456,
"action_name": "Название акции для позиции"
}
],
"barcode": "2400000011125",
"bonus_in": 82.07,
"discount": 18.75,
"quantity": 4,
"bonus_out": 0,
"discounted_price": 205.16,
"discounted_total": 820.65
},
{
"code": "5374",
"name": "Товар 2",
"price": 139.9,
"total": 1367.75,
"actions":[],
"barcode": "2400000011118",
"bonus_in": 136.78,
"discount": 31.25,
"quantity": 10,
"bonus_out": 0,
"discounted_price": 136.78,
"discounted_total": 1367.75
}
],
"result_code": 0,
"result_text": "OK"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| move_info | jsonb | Общая информация по документу |
| id | integer | внутренний id операции |
| move_id | text | номер документа присланный с кассы |
| bonus_in | numeric | количество начисленных бонусов на документ |
| discount | numeric | сумма скидки в операции |
| bonus_out | numeric | списанные бонусы по операции |
| client_id | integer | id клиента в операции |
| move_asum | numeric | сумма операции |
| move_actions | array | массив акций, применённых на документ (не включает в себя акции с бонусными подаркоми) |
| move_bonuses | array | массив с бонусами на документ |
| bonus_presents | array | массив бонусных подарков на чек |
| move_date | date | дата операции |
| oper_type | integer | тип операции (0 - продажа, 1 - возврат, 2 - автоматическая операция, 3 - ручная операция) |
| move_total | numeric | сумма документа без скидок |
| is_reserved | boolean | флаг резервирования операции, true - зарезервированна, false - не зарезервированна |
| promo_codes | array | массив примененных к операции промокодов |
| is_confirmed | boolean | флаг подтвержденной операции, true - подтверждена, false - не подтверждена |
| shift_number | integer | номер смены операции |
| move_detail | jsonb | массив объектов, перечисление номенклатуры в операции |
| code | text | код номенклатуры загруженный из 1С или кассы |
| name | text | наименование номенклатуры |
| price | number | цена номенклатуры |
| total | number | сумма товарной позиции |
| barcode | text | штрихкод номенклатуры |
| bonus_in | number | количество начисленных бонусов за позицию номенклатуры |
| discount | number | размер скидки, примененный на позицию номенклатуры |
| quantity | number | количество номенклатуры в позиции |
| bonus_out | number | количество списанных бонусов на позицию номенклатуры |
| discounted_price | number | цена номенклатуры со скидкой |
| discounted_total | number | сумма номенклатуры позиции со скидкой |
| result_code | integer | код результата |
| result_text | text | описание результата |
Описание массива goods:
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| code | text | код товара |
| name | text | наименование товара |
| price | number | цена товара |
| total | number | стоимость товара |
| actions | array | массив акций, применённых на позицию |
| barcode | text | штрихкод товара |
| bonus_in | number | начислено бонусов за позицию |
| discount | number | скидка в рублях на позицию |
| quantity | number | количество товара |
| bonus_out | number | списано бонусов на позицию |
| discounted_price | number | цена товара со скидкой |
| discounted_total | number | стоимость товара со скидкой |
Описание массива move_actions и actions:
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| action_id | number | id акции |
| action_name | text | наименование акции |
Описание массива move_bonuses:
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| bonus_in | number | сумма начисленных бонусов |
| expire_date | date | дата и время сгорания бонусов |
| bonus_in_date | date | дата и время начала действия бонусов |
Описание массива bonus_presents:
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| bonus_in | number | сумма начисленных бонусов |
| action_id | number | id акции |
| action_name | text | наименование акции |
| expire_date | date | дата и время сгорания бонусов |
| bonus_in_date | date | дата и время начала действия бонусов |
getmovesbyclient – получение списка операций клиента
Входные параметры:
https://bonus.kilbil.ru/load/getmovesbyclient?h={ключ}
Входные параметры:
{
"client_id": 3663560
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| client_id | integer | id клиента |
Описание возвращаемого результата выполнения:
Выходные параметры:
{
"client_moves": [
{
"id": 9350350,
"move_id": null,
"bonus_in": 100,
"discount": 0,
"bonus_out": 0,
"move_asum": 0,
"move_date": "10.07.2019 16:47:37",
"oper_type": 3,
"rows_count": 0,
"trade_object": null,
"bonus_in_date": "10.07.2019 00:00:00",
"bonus_term_date": "11.07.2019 00:00:00",
"oper_description": "Ручное начисление",
"manualadd_description": "Начислили подарочный бонус с розыгрыша 2021"
},
{
"id": 4158157,
"move_id": "32668",
"bonus_in": 3,
"discount": 0,
"bonus_out": 50,
"move_asum": 121.5,
"move_date": "02.04.2019 12:38:32",
"oper_type": 0,
"rows_count": 0,
"trade_object": "ТЕСТОВЫЙ2",
"bonus_in_date": "02.04.2019 12:38:32",
"bonus_term_date": null,
"oper_description": "Продажа",
"manualadd_description": ""
},
{
"id": 4157665,
"move_id": "32659",
"bonus_in": 5,
"discount": 0,
"bonus_out": 0,
"move_asum": 100,
"move_date": "02.04.2019 12:06:30",
"oper_type": 0,
"rows_count": 2,
"trade_object": "ТЕСТОВЫЙ2",
"bonus_in_date": "02.04.2019 12:06:31",
"bonus_term_date": null,
"oper_description": "Продажа",
"manualadd_description": ""
},
{
"id": 4157650,
"move_id": "32658",
"bonus_in": -5,
"discount": 0,
"bonus_out": 0,
"move_asum": -100,
"move_date": "02.04.2019 12:05:36",
"oper_type": 1,
"rows_count": 1,
"trade_object": "ТЕСТОВЫЙ2",
"bonus_in_date": "02.04.2019 12:05:36",
"bonus_term_date": null,
"oper_description": "Возврат",
"manualadd_description": ""
},
{
"id": 4157647,
"move_id": "32657",
"bonus_in": 5,
"discount": 0,
"bonus_out": 0,
"move_asum": 100,
"move_date": "02.04.2019 12:05:16",
"oper_type": 0,
"rows_count": 1,
"trade_object": "ТЕСТОВЫЙ2",
"bonus_in_date": "02.04.2019 12:05:16",
"bonus_term_date": null,
"oper_description": "Продажа",
"manualadd_description": ""
}
],
"result_code": "0"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| result_code | integer | Код результата |
| client_moves | jsonb | массив объектов с операциями |
Описание параметров в операции:
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| id | integer | внутренний id операции |
| move_id | text | номер операции присланный с кассы |
| bonus_in | numeric | начисленные бонусы по операции |
| discount | numeric | сумма скидки в операции |
| bonus_out | numeric | списанные бонусы по операции |
| move_asum | numeric | сумма операции |
| move_date | date | дата операции |
| oper_type | integer | тип операции (0 - продажа, 1 - возврат, 2 - автоматическая операция, 3 - ручная операция) |
| rows_count | integer | количество позиций в документе |
| oper_description | text | описание операции |
| manualadd_description | text | поле описания, которое заполнялось при ручном начислении |
| trade_object | text | название торговой точки, где была операция |
| bonus_in_date | date | дата и время активации бонусов (может отличаться от даты чека из-за отложенных бонусов) |
| bonus_term_date | date | дата и время сгорания бонусов |
Возможные значения параметра oper_description:
- "Подарок подписчику"
- "Подарок издателю"
- "Подарок за активацию клиента"
- "Подарок в день рождения"
- "Подарок в акции"
- "Перенос балансов при замене карты"
- "Инициализация баланса сертификата"
- "Перенос бонусов при миграции из старой бонусной системы"
- "Перенос суммы покупок при миграции из старой бонусной системы"
- "Пополнение баланса при создании карты"
- "Начисление бонусов издателю с продажи подписчика"
- "Бонусный подарок по акции"
- "Пополнение баланса сертификата"
- "Аннулирование баланса клиента"
- "Перенос бонусов и суммы покупок при миграции из старой бонусной системы"
- "Списание сгораемых бонусов"
- "Пополнение подарочной карты"
- "Возврат подарочной карты"
- "Оплата подарочной картой"
getprograms – получение списка программ лояльности
Входные параметры отсутствуют.
https://bonus.kilbil.ru/load/getprograms?h={ключ}
Входные параметры отсутствуют.
Описание возвращаемого результата выполнения:
Выходные параметры:
{
"success": 1,
"result_code": 0,
"data": [
{
"id": "976",
"name": "Дисконтно-бонусная 10%",
"type": "Дисконтно-бонусная",
"bonus_percent": "5.00",
"bonus_pay_percent": "50.00",
"discount_percent": "5.00",
"begin_date": null,
"is_default": "f"
},
{
"id": "289",
"name": "Подарочный сертификат",
"type": "Подарочный сертификат",
"bonus_percent": "0.00",
"bonus_pay_percent": "100.00",
"discount_percent": "0.00",
"begin_date": null,
"is_default": "f"
},
{
"id": "171",
"name": "Дисконтная 20%",
"type": "Дисконтная",
"bonus_percent": "0.00",
"bonus_pay_percent": "0.00",
"discount_percent": "20.00",
"begin_date": null,
"is_default": "f"
},
{
"id": "25",
"name": "Бонусная 10%",
"type": "Бонусная",
"bonus_percent": "10.00",
"bonus_pay_percent": "100.00",
"discount_percent": "0.00",
"begin_date": null,
"is_default": "f"
}
]
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| result_code | integer | код результата |
| data | text | массив с данными |
id - номер программы, name - название программы, type - тип программы, bonus_percent- бонусный процент, bonus_pay_percent - процент оплаты покупки бонусами, discount_percent - процент скидки, begin_date - дата начала действия (если есть), is_default - является ли программой по умолчанию ( t - если является)
getsalesindicesslides - получить список тегов и групп тегов
Входные параметры:
https://bonus.kilbil.ru/load/getsalesindicesslides?h={ключ}
Входные параметры:
{
"group_id": 675
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| group_id | integer | id группы, если нужно получить теги только одной группы, не обязательный параметр. Без id группы |
Описание возвращаемого результата выполнения:
Выходные параметры:
{
"result_code": 0,
"slides": [
"Выручка: 91.47 руб.\r\nСредний чек: 91.47 руб.",
"Продажи с картой 100 %"
],
"info": "Алкоголь можно если старше <ДатаДр18Лет>"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| slides | jsonb | Массив объектов слайдов, каждый слайд как элемент массива |
| info | text | Статичный текст для всех слайдов, переменная <ДатаДр18Лет> говорит, что нужно подставить дату текущая дата - 18 лет (если во входные параметры передана дата, то в ответе будет сразу нужная дата) |
getlisttags - получить список тегов и групп тегов
Входные параметры:
https://bonus.kilbil.ru/load/getlisttags?h={ключ}
Входные параметры:
{
"group_id": 675
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| group_id | integer | id группы, если нужно получить теги только одной группы, не обязательный параметр. Без id группы будет весь список тегов и групп |
Описание возвращаемого результата выполнения:
Выходные параметры:
{
"groupId": 0,
"groups_list": [
{
"group_name": "Город",
"group_id": 675
}
],
"tags_list": [
{
"tag_id": 676,
"tag_name": "Екатеринбург",
"group_id": 675
},
{
"tag_id": 215,
"tag_name": "Инстаграм",
"group_id": 0
},
{
"tag_id": 97,
"tag_name": "не мошенник",
"group_id": 0
},
{
"tag_id": 678,
"tag_name": "Пермь",
"group_id": 675
},
{
"tag_id": 119,
"tag_name": "Сотрудник",
"group_id": 0
},
{
"tag_id": 679,
"tag_name": "Тюмень",
"group_id": 675
},
{
"tag_id": 677,
"tag_name": "Челябинск",
"group_id": 675
}
],
"result_code": 0
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| result_code | integer | Код результата, где 0 - это успешно |
| groupId | integer | id группы тегов, если было передано в запросе |
| groups_list | jsonb | Массив с объектами групп тегов |
| tags_list | jsonb | Массив с объектами тегов |
Описание объекта групп тегов groups_list:
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| group_id | integer | id группы тегов |
| group_name | text | наименование группы тегов |
Описание объекта тегов tags_list:
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| tag_id | integer | id тега |
| tag_name | text | наименование тега |
| group_id | integer | id группы где находится тег, 0 - без группы |
getwalletlink – получить ссылку на карту wallet для клиента
Входные параметры:
https://bonus.kilbil.ru/load/getwalletlink?h={ключ}
Входные параметры:
{
"client_id": 89630
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| client_id | integer | id клиента |
Описание возвращаемого результата выполнения:
Выходные параметры:
{
"result_text": "Клиент найден",
"result_code": 0,
"wallet_link": "https:\/\/card.kilbil.ru\/kilbil\/cards\/load\/aObD0kc-d-fMaz6A0xdic.pkpass"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| result_code | integer | код результата, где 0 - успешно |
| result_text | text | Текст результата |
| wallet_link | text | ссылка на скачивание карты wallet |
goods – загрузка товаров
Входные параметры:
https://bonus.kilbil.ru/load/goods?h={ключ}
Входные параметры:
[
{
"id": "d9ad966b-3098-11e7-922d-002381219ac7",
"is_group": true,
"delete_mark": false,
"code": "1",
"name": "Название группы",
"full_name": "",
"unit": "",
"inside": [
{
"id": "55cd3f03-cb38-11e7-8376-58fb84fa9d6b",
"is_group": false,
"delete_mark": false,
"code": "704",
"BC": ["123456789","2938483274"],
"name": "Наименование товара",
"full_name": "Полное наименование товара",
"unit": "шт",
"price1": 10,
"price2": 20,
"price3": 30
},
{
"id": "7f8431b6-a1e9-11e7-b80e-58fb84fa9d6b",
"is_group": false,
"delete_mark": false,
"code": "608",
"BC": ["987654321"],
"name": "название товара",
"full_name": "Полное название товара",
"unit": "шт",
"price1": 10,
"price2": 20,
"price3": 30
}
]
},
{
"id": "d9ad966b-3098-11e7-922d-002381219ac7",
"is_group": true,
"delete_mark": false,
"code": "5",
"name": "Название группы 3",
"full_name": "",
"unit": "",
"inside": [
{
"id": "55cd3f03-cb38-11e7-8376-58fb84fa9d6b",
"is_group": false,
"delete_mark": false,
"code": "706",
"BC": ["123789456"],
"name": "Наименование товара",
"full_name": "Полное наименование товара",
"unit": "шт",
"price1": 10,
"price2": 20,
"price3": 30
},
{
"id": "7f8431b6-a1e9-11e7-b80e-58fb84fa9d6b",
"is_group": false,
"delete_mark": false,
"code": "610",
"BC": ["789123456","12378943356"],
"name": "название товара",
"full_name": "Полное название товара",
"unit": "шт",
"price1": 10,
"price2": 20,
"price3": 30
}
]
}
]
Описание возвращаемого результата выполнения:
Выходные параметры:
{
"success": 1
}
В случае успешной загрузки в ответ приходит json:
{"success": 1 }
или в случае ошибки:
{"error": 1, "error_message": "Текст ошибки"}
goodslist – загрузка списка товаров
Входные параметры:
https://bonus.kilbil.ru/load/goodslist?h={ключ}
Входные параметры:
[
{
"name": "Комплекты",
"id_1c": "d3016e33-cca1-11ea-881b-4061863647fd",
"ID": "393",
"delete_mark": false,
"calc": false,
"inside": [
{
"name": "Айнзидлер Пилс 1,5 Литр с бутылкой",
"id": "7beb5e7a-610e-11ea-828b-005056bf2642",
"delete_mark": false,
"code": "2137",
"full_name": "Айнзидлер Пилс 1,5 Литр с бутылкой",
"price": 408.9,
"K": 2
},
{
"name": "Айнзидлер Пилс1 Литр с бутылкой",
"id": "dd44e080-610c-11ea-b497-005056bf2642",
"delete_mark": false,
"code": "3957",
"full_name": "Айнзидлер Пилс1 Литр с бутылкой",
"price": 274.9,
"K": 1
},
{
"name": "Американский пэйл эль 1,5 Литра с бутылкой",
"id": "bd6e42ae-4ce1-11ea-fe9f-005056bf2642",
"delete_mark": false,
"code": "85705",
"full_name": "Американский пэйл эль 1,5 Литра с бутылкой",
"price": 338.9,
"K": 1.5
}
]
}
]
Изначально необходимо создать список в бонусной, и указать ID созданного списка в выгрузке в поле "ID".
Параметр "K" в товаре нужен для установки коэффициента для списков товаров для расчёта показателей, для сохранения коэффициента необходимо сначала выбрать Тип списка "Список товаров для расчёта показателей".
Описание возвращаемого результата выполнения:
Выходные параметры:
{
"success": 1
}
В случае успешной загрузки в ответ приходит json:
{"success": 1 }
или в случае ошибки:
{"error": 1, "error_message": "Текст ошибки"}
manualadd – ручное начисление бонусов
Входные параметры:
https://bonus.kilbil.ru/load/manualadd?h={ключ}
Входные параметры:
{
"client_id":"4004565",
"bonus_in": "10",
"bonus_out": "35",
"total": "102.30",
"description": "Продажа товара с сайта",
"expire_date": "15.05.2022"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| client_id | integer = null::integer | id клиента |
| bonus_in | numeric | сумма начисления |
| bonus_out | numeric | сумма списания |
| total | numeric | полная сумма чека без скидок |
| description | text | комментарии к операции |
| expire_date | timestamp | дата сгорания бонусов (сгорит в указанную дату в 00:00:00, т.е. не включительно) |
Описание возвращаемого результата выполнения:
Выходные параметры:
{
"success": 1,
"result_code": 0,
"result_text": "Операция успешно создана"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| result_code | integer | код результата |
| result_text | text | текст результата |
| result_code | result_text | Описание |
|---|---|---|
| 0 | Операция успешно создана | Операция успешно создана |
| 100 | Неполные данные | Неполные данные |
processsale – рассчет чека
Входные параметры:
https://bonus.kilbil.ru/load/processsale?h={ключ}
Входные параметры:
{
"client_id":"4004565",
"type":0,
"bonus_out":"100",
"max_bonus_out":"191.47",
"move_id":"101279",
"shift_number":563,
"doc_open_dt":"09.11.2020 17:27:35",
"client_search_mode":0,
"client_search_value":"79129999999",
"goods_data":[
{
"code":"2137",
"barcode":"2400000005926",
"vendor_code":"2137",
"name":"Брюгер Белое Н/Ф 1л",
"price":130,
"quantity":2,
"total":260,
"minPrice":0,
"maxDiscount":100,
"discounted_price":129.99,
"discounted_total":259.98,
"parent_code":"2082",
"parent_vendor_code":""
},{
"code":"3957",
"barcode":"4870001723859",
"vendor_code":"3957",
"name":".Erzmann Dark темное фильтр паст Арасан 0,45л",
"price":68.32,
"quantity":1,
"total":68.32,
"minPrice":0,
"maxDiscount":100,
"discounted_price":68.32,
"discounted_total":68.32,
"parent_code":"4085",
"parent_vendor_code":""
}
],
"promo_codes":{
"coupons":[
{"coupon":"1001"}
]
}
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| type | integer | тип операции (0 - продажа, 1 - возврат) |
| client_id | integer | id клиента |
| bonus_out | numeric | сумма бонусов для списания |
| max_bonus_out | numeric | максимально возможная сумма для списания бонусов без учета баланса клиента (передается значение выходного параметра max_bill_bonus_out функции searchclient |
| goods_data | jsonb | JSON с позициями чека в полном виде |
| move_id | text | id чека на торговом оборудовании (не меньше 4 символов) |
| doc_open_dt | timestamp | Дата и время открытия документа чека |
| return_move_id | text = NULL::text | id чека на торговом оборудовании, по которому производится возврат (передаётся только для возвратов) |
| return_doc_dt | timestamp | Дата и время в документе чека, по которому производится возврат |
| mode | integer = 0 | режим расчета чека (0 - обычный режим, 1 - расчет только сумм скидок и списываемых бонусов, 2 - расчет только сумм начисленных бонусов) |
| bill_data_in | jsonb = NULL::jsonb | JSON с данными по чеку, рассчитанными на предыдущей стадии расчета |
| params | jsonb = NULL::jsonb | Дополнительные параметры чека |
| is_offline | smallint = NULL::smallint | Отправлена ли продажа оффлайн-службой: 0 - нет, 1 - да |
| promo_codes | jsonb = NULL::jsonb | Список промо-кодов |
| card_apply_dt | timestamp = NULL::timestamp | Дата и время применения карты (в часовом поясе UTC 0) |
| shift_number | smallint = NULL::smallint | Номер смены |
| client_search_mode | integer | для обработки чека в режиме offline, режим поиска (0 – поиск по № телефона, 1 – поиск по внутреннему № карты, 2 – поиск по № карты, 3 - поиск по id клиента), берётся из предыдущего запроса searchclient |
| client_search_value | text | для обработки чека в режиме offline, значение, по которому производится поиск, берётся из предыдущего запроса searchclient |
| is_reserved | boolean | Функция резервирования не подтвержденного документа (чека), актуально для интернет магазинов. Позволяет зарезервировать списание бонусов, акции (акция сработает если вышел срок действия на текущий момент, но на момент резервирования акция работала) |
Товары (параметр goods_data) передаются в виде JSON: [{"code": "1", "parent_code":"2", "name": "Молоко", "full_name": "Молоко", "quantity": 10, "price": 50.50, "total": 505.00,"discounted_price":50.00,"discounted_total":500.00, "barcode": "134344"}, {…}, …]. Промо-коды передаются в переменной promo_codes типа JSON в таком формате: {"coupons":[{"coupon":"№ промо-кода"},{...},...]}. Здесь coupon - номер промо-кода. Старый механизм, далее использоваться не будет. Погашенные купоны передаются в переменной params типа JSON в таком формате: {"coupons":[{"coupon":"№ купона","coupon_spent_sum":500},{...},...]}. Здесь coupon - номер погашенного купона, coupons_spent_sum - сумма скидки, сделанной по этому купону.
Описание возвращаемого результата выполнения:
Выходные параметры:
{
"result_code": "0",
"result_text": "Чек обработан",
"_bill_data": {
"items": [
{
"id": 2816366,
"code": "2137",
"flags": 0,
"price": 130,
"total": 130,
"bonus_in": 6.21,
"discount": 0,
"quantity": 1,
"rounding": 0,
"bonus_out": 67.89,
"bonus_out_money": 67.89,
"client_discount": null,
"discounted_price": 62.09,
"discounted_total": 62.09
},
{
"id": 2817573,
"code": "3957",
"flags": 0,
"price": 68.32,
"total": 68.32,
"bonus_in": 2.94,
"discount": 6.83,
"quantity": 1,
"rounding": 0,
"bonus_out": 32.11,
"bonus_out_money": 32.11,
"client_discount": null,
"discounted_price": 29.38,
"discounted_total": 29.38
}
],
"total": 198.32,
"bonus_in": 9.15,
"discount": 6.83,
"bonus_out": 100,
"discounted_total": 91.47
},
"_bill_body": [
{
"text": "БОНУСНАЯ ПРОГРАММА",
"align": "c"
},
{
"text": "Бонусов списано: 100.00",
"align": "l"
},
{
"text": "Бонусов начислено: 9.15",
"align": "l"
},
{
"text": "Текущий баланс: 232.31",
"align": "l"
}
],
"_bill_header": null,
"_bill_footer": null,
"_responds_quantities_rests_messages": null,
"_coupons_out": null,
"_applied_actions": null,
"_actions_messages": null,
"actions_lc_rests": null,
"possible_action_payment": null
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| result_code | integer | код результата |
| result_text | text | текст результата |
| _bill_data | jsonb | JSON с рассчитанным чеком |
| _bill_body | jsonb | Информация для печати в тело чека |
| _bill_header | jsonb | информация для печати в начале чека |
| _bill_footer | jsonb | информация для печати в конце чека |
| _responds_quantities_rests_messages | jsonb | JSON с сообщениями о недополученных подарках |
| _coupons_out | jsonb | Массив купонов для печати на чеке |
| _applied_actions | jsonb | Массив названий примененных в чеке акций, для которых задано показывать на кассе |
| _actions_messages | jsonb | Массив сообщений, заданных в действиях в акциях |
| actions_lc_rests | jsonb | Информирование по акциям со счетчиками |
| result_code | result_text | Описание |
|---|---|---|
| 0 | OK | Суммы списания рассчитаны |
| 1 | Не удалось рассчитать максимально возможную сумму списания бонусов по параметрам лояльности | Не удалось рассчитать максимально возможную сумму списания бонусов по параметрам лояльности |
| 2 | Торговое оборудование с таким ID не найдено | Торговое оборудование с таким ID не найдено |
| 3 | Торговое оборудование не привязано к торговому объекту | Торговое оборудование не привязано к торговому объекту |
Формат JSON с рассчитанным чеком: [{"move_id":12,"total":1000.00, "discounted_total":1000.00,"bonus_in":50.00,"bonus_out":500.00},{"code": "1", "name": "Рыба", "full_name": «Рыба», "quantity": 4, "price": 50.00, "discounted_price": 50.00, "total": 200.00, "discounted_total": 200.00, "bonus_in": 4.00, "bonus_out": 100.00}, …] Здесь первое значение в массиве – шапка чека, остальные – строки чека. В processsale надо передавать параметр max_bonus_out, который равен значению выходного параметра max_bonus_out функции searchclient, это нужно чтобы списываемые бонусы правильно распределились по позициям когда сумма списания отлична от max_bonus_out (считается коэффициент, на который умножается каждая позиция). Используя параметр mode, можно применять к чеку скидки на кассе. Для этого: 1.товары чека нужно сначала передать в режиме mode = 1; 2.получив чек с рассчитанными суммами списаний и скидок в переменной bill_data, применить свои скидки, уменьшив тем самым параметры discounted_price и discounted_total позиций чека и параметр discounted_total всего чека; 3.передать полученный результат (измененное значение _bill_data) в режиме mode = 2 для расчета сумм начисленных бонусов.
replacecard - замена карты
Входные параметры:
https://bonus.kilbil.ru/load/replacecard?h={ключ}
Входные параметры:
{
"search_mode":1,
"search_value":"300023",
"client_id":"4004565"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| search_mode | integer | режим поиска новой карты (0 – поиск по № карты, 1 – поиск по внутреннему № карты) |
| search_value | text | поисковое значение |
| client_id | integer | id клиента, которому производится замена карты |
| sms_code | text | код подтверждения |
Описание возвращаемого результата выполнения:
Выходные параметры:
{
"success": 1,
"result_code": "0",
"result_text": "OK"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| success | integer | код выполнения |
| result_code | integer | код результата |
| result_text | text | текст результата |
| result_code | result_text | Описание |
|---|---|---|
| 0 | OK | Произведена замена карты |
| 1 | Карта не найдена. | Не найдена новая карта |
| 2 | Новая карта не должна быть привязана к другому клиенту. | По новой карте уже осуществлены операции или заполнены данные (допускается замена только на пустую карту) |
| 3 | Новая карта должна быть в состоянии: "Рабочая". | Новая карта или заменена или заблокирована, то есть не может быть использована для замены |
| 4 | Клиент не найден. | По заданному id не найден клиент |
reservedpromocode – резервирование одноразовых промокода
Используется для резервирования промокода, сделать не активным для дальнейшего применения, пока не снимется резерв. Актуально для долгой обработки заказа. Применимо для одноразового активного (не погашенного) промокода. Для многоразовых промо кодов функция не имеет смысла.
Входные параметры:
https://bonus.kilbil.ru/load/reservedpromocode?h={ключ}
Входные параметры:
{
"promo_code":"test123",
"set_reserved":true
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| promo_code | text | Номер промокода для установки статуса |
| set_reserved | boolean | установка флага резервирования промо кода true - зарезервировать, false - снять с резервирования |
Описание возвращаемого результата выполнения:
Выходные параметры:
{
"result_code": "0",
"result_text": "Промокод зарезервирован."
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| result_code | integer | код результата |
| result_text | text | текст результата |
Ожидаемый результат выполнения
| result_code | result_text | Описание |
|---|---|---|
| 0 | Промокод зарезервирован. | Успешное резервирование промокода |
| 0 | Промокод снят с резерва. | Успешное снятие промокода с резерва |
| 1 | Промокод не найден. | Указанный промокод не найден. |
| 2 | Промокод погашен. | Промокод погашен, его нельзя поставить или снять с резерва |
| 3 | Промокод многоразовый и не может быть зарезервирован. | Промокод многоразовый, его нельзя поставить или снять с резерва |
| 4 | Промокод уже зарезервирован. | Промокод уже зарезервирован его нельзя поставить в резерв повторно |
| 4 | Промокод не зарезервирован. | Промокод уже снят с резерва его невозможно снять с резерва повторно |
searchclient – поиск клиента, получение его id и состояния
Входные параметры:
https://bonus.kilbil.ru/load/searchclient?h={ключ}
Входные параметры:
{
"search_mode":0,
"search_value":"79129999999",
"goods_data":[
{
"code":"2137",
"barcode":"2400000005926",
"vendor_code":"2137",
"name":"Брюгер Белое Н/Ф 1л",
"price":130,
"quantity":2,
"total":260,
"minPrice":0,
"maxDiscount":100,
"discounted_price":129.99,
"discounted_total":259.98,
"parent_code":"2082",
"parent_vendor_code":""
},{
"code":"3957",
"barcode":"4870001723859",
"vendor_code":"3957",
"name":".Erzmann Dark темное фильтр паст Арасан 0,45л",
"price":68.32,
"quantity":1,
"total":68.32,
"minPrice":0,
"maxDiscount":100,
"discounted_price":68.32,
"discounted_total":68.32,
"parent_code":"4085",
"parent_vendor_code":""
}
],
"promo_codes":{
"coupons":[
{
"coupon":"1001"
}
]
},
"card_apply_dt":"09.11.20 17:28:23",
"full_data":true
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| search_mode | integer | режим поиска (0 – поиск по № телефона, 1 – поиск по внутреннему № карты, 2 – поиск по № карты, 3 - поиск по id клиента) |
| search_value | text | значение, по которому производится поиск |
| goods_data | jsonb | JSON с позициями чека в полном виде |
| promo_codes | jsonb = NULL::jsonb | Список промо-кодов |
| card_apply_dt | timestamp = NULL::timestamp | Дата и время применения карты (в часовом поясе UTC) |
| move_id | text | Номер зарезервированного документа переданный в processale, для правильного обсчета акций и списанных зарезервированных бонусов |
| full_data | bool | не обязательный параметр, передается для получения дополнительной информации по клиенты о всех картах и интерфейсах (например телеграм) |
Товары (параметр goods_data) передаются в виде JSON: [{"code": "1", "parent_code":"2", "vendor_code":"003","parent_vendor_code":"004","name": "Молоко", "full_name": "Молоко", "quantity": 10, "price": 50.50, "total": 505.00,"discounted_price":50.00,"discounted_total":500.00, "is_certificate": 0 }, {…}, …].
Здесь параметр "parent_code" - это код группы товаров, в которую непосредственно входит товар с кодом code (группа первого уровня вложенности). Передавать этот параметр необходимо, чтобы при наличии новых товаров в чеке (отсутствующих в справочнике товаров бонусной системы) они при добавлении в справочник товаров бонусной системы сразу попадали в группу товаров, к которой они относятся и получали дисконтно-бонусные параметры родительских групп товаров. При появлении новых групп товаров необходимо выполнить процедуру загрузки товаров, чтобы добавились эти новые группы и назначить им при необходимости дисконтно-бонусные параметры.
Параметры "vendor_code" и "parent_vendor_code" выполняют те же функции, что и параметры "code" и "parent_code", но используются в конфигурациях где код товара на кассе не совпадает с кодом товара в учетной системе, из которой производится загрузка товаров в справочник товаров бонусной системы. Таким образом, в эти параметры передаются коды, обеспечивающие связь между товаром на кассе и товаром в учетной системе. Код товара в бонусной системе принимается равным коду товара в учетной системе.
"maxDiscount" - это максимальный возможный процент суммарной скидки после применения скидок и списаний бонусов (списание бонусов тоже относится к этому ограничению) в бонусной системе.
"minPrice" - похожее ограничение, но оно ограничивает с другой стороны - устанавливает минимальный порог цены со скидкой для товара. Также отличие между этими двумя параметрами, что первый - это процентное ограничение, а второй - суммовое ограничение.
Промо-коды передаются в переменной promo_codes типа JSON в таком формате: {"coupons":[{"coupon":"№ промо-кода"},{...},...]}. Здесь coupon - номер промо-кода.
Описание возвращаемого результата выполнения:
Выходные параметры:
{
"state": "1",
"client_id": "4004565",
"first_name": "Дарья",
"middle_name": "Владимировна",
"last_name": "Петрова",
"full_name": "Дарья Владимировна Петрова",
"birth_date": "1997-10-02",
"phone": "79129999999",
"sex": "0",
"client_email":"ex@email.ru",
"card_state": "0",
"card_id": "3968102",
"card_barcode": "9990012000826",
"card_code": "200082",
"bonus_percent": "10.00",
"discount_percent": null,
"program_type": "0",
"program_name": "Бонусная 10%",
"max_bonus_out": "323.16",
"max_bill_bonus_out": "328.30",
"discounted_total": "328.30",
"discount": "0.00",
"accumulated_values_messages": null,
"promo_codes": "",
"activate_client_type": "2",
"replace_card_type": "2",
"referral_system_is_used": "0",
"bonus_balance": 323.15999999999997,
"bonus_out_percent": null,
"purchases_sum": "7333.17",
"status_name": null,
"next_period_status_name": null,
"next_status_name": null,
"next_status_purchases_sum": null,
"next_status_bonus_percent": null,
"next_status_discount_percent": null,
"progressive_scale_type": null,
"sum_to_next_status": null,
"phone_is_free": "0",
"outer_systems_interface_type": null,
"special_days_types": [
{
"id": 90,
"aname": "День свадьбы"
},
{
"id": 265,
"aname": "День рождение ребёнка"
}
],
"not_to_send_sms": 0,
"not_to_send_email": 0,
"cards": [
{
"code": "123",
"barcode": "123123123",
"card_id": 123,
"outer_systems_interface_name": null,
"outer_systems_interface_type": null
}
],
"interfaces": [
{
"interface_id": "1234567890",
"interface_os": "",
"interface_name": "Telegram",
"interface_type": 0
}
],
"tags": null,
"program_write_off_type": "0",
"top_sales": null,
"result_code": "0",
"result_text": "Клиент найден",
"bonus_sum_termless": 323.15999999999997,
"use_sms_code": "0",
"use_discount_sms": "0",
"allow_manual_card_spend": 0,
"sms_code_sum": 0,
"use_activation_sms_code": "0",
"only_with_cards": "0",
"_bill_data": {
"items": null
}
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| result_code | integer | код результата |
| result_text | text | текст результата |
| client_id | integer | id клиента |
| state | integer | состояние клиента (NULL - не найден, 0 – пустой, 1 – активирован, 2 – заблокирован, 3 - зарегистрирован, 4 - замена карты (донор)) |
| bonus_percent | numeric | бонусный процент клиента с учётом всех факторов |
| discount_percent | numeric | дисконтный процент клиента с учётом всех факторов |
| bonus_balance | numeric | Баланс клиента |
| bonus_sum_termless | numeric | Баланс клиента с учетом бонусов, которые записаны в базу, но еще не добавлены к балансу |
| bonus_out_percent | numeric | Максимальный процент оплаты бонусами по программе лояльности с учетом прогрессивной шкалы |
| program_name | text | Название программы лояльности |
| program_type | smallint | Тип программы лояльности (0 - бонусная, 1 - дисконтная, 2 - дисконтно-бонусная, 3 - подарочный сертификат) |
| max_bill_bonus_out | numeric | Максимальная сумма списания на текущий чек без учета баланса клиента |
| max_bonus_out | numeric | Максимальная сумма списания с учетом баланса клиента |
| only_with_cards | integer | Используются ли в бонусной системе только карты: 0,1 |
| use_sms_code | integer | Используются ли смс для подтверждения операций списания бонусов (0 - нет, 1 - при вводе телефона, 2 - при вводе карты и телефона) |
| use_discount_sms | integer | Используются ли смс для подтверждения операций по дисконтной программе лояльности (0 - нет, 1 - при вводе телефона, 2 - при вводе карты и телефона) |
| use_activation_sms_code | integer | (Устаревшая, использовать activate_client_type) Используются ли смс для подтверждения активации клиента. Значения: 0, 1 |
| sms_code_sum | numeric | Минимальная сумма списания, при которой надо запрашивать код подтверждения операции |
| card_id | integer | id карты клиента |
| card_state | integer | Состояние карты (0 - рабочая, 2 - заблокирована, 3 - заменена) |
| card_code | text | Короткий номер карты |
| card_barcode | text | Внутренний номер карты |
| phone | text | Номер телефона клиента |
| birth_date | date | Дата рождения клиента |
| first_name | text | Имя клиента |
| middle_name | text | Отчество клиента |
| last_name | text | Фамилия клиента |
| full_name | text | ФИО клиента |
| sex | smallint | Пол клиента (0 - женский, 1 - мужской) |
| client_email | text | Адрес електронной почты |
| discounted_total | numeric | Сумма чека со скидкой |
| discount | numeric | Скидка по чеку |
| accumulated_values_messages | text [] | Массив сообщений на кассе по накопленным объёмам товаров в рамках акций по накопленному объёму с отношением "За каждые" |
| promo_codes | jsonb | Список промо-кодов |
| activate_client_type | smallint | Тип активации клиента на кассе (0 - без кода подтверждения, 1 - по коду подтверждения, 2 - запрещена) |
| replace_card_type | smallint | Тип замены карты на кассе (0 - без кода подтверждения, 1 - по коду подтверждения, 2 - запрещена) |
| referral_system_is_used | smallint | Используется ли реферальная система (0 - нет, 1 - да) |
| purchases_sum | numeric | Сумма покупок за всё время |
| status_name | text | Статус текущего периода по прогрессивной шкале |
| next_period_status_name | text | Накопленный статус следующего периода |
| next_status_name | text | Следующий статус следующего периода |
| next_status_purchases_sum | numeric | Сумма покупок, которую нужно совершить в текущем периоде для получения следующего статуса следующего периода |
| next_status_bonus_percent | numeric | бонусный процент в следующем статусе прогрессивной шкалы |
| next_status_discount_percent | numeric | дисконтный процент в следующем статусе прогрессивной шкалы |
| progressive_scale_type | smallint | null - нет прогрессивной шкалы, 0 - шкала за все время, 1 - шкала за месяц |
| sum_to_next_status | numeric | Сумма покупок, которую осталось совершить до достижения суммы next_status_purchases_sum |
| phone_is_free | smallint | При поиске по номеру телефона: 1 - телефона свободен, 0 - телефон занят; при поиске по другим реквизитам значение равно null. |
| outer_systems_interface_type | smallint | Тип интерфейса карты |
| special_days_types | jsonb | Массив специальных дат, доступных для программы лояльности покупателя, содержит в себе id и наименование. id можем использовать для функции addclient, что бы при активации клиента уточнить специальные даты |
| not_to_send_sms | smallint | Не отправлять информационных смс (1 - не отправлять) |
| not_to_send_email | smallint | Не отправлять информационных e-mail (1 - не отправлять) |
| tags | jsonb | Теги клиента |
| top_sales | jsonb | Любимые покупки клиента |
| program_write_off_type | jsonb | Тип оплаты подарочным сертификатом (0 - Скидкой, 1 - Оплатой) |
| allow_manual_card_spend | integer | Настройка списание по ручному вводу карты разрешено (для Эвотор) |
| _bill_data | jsonb | Используется для предварительного расчёта акций с ценой, возвращает id применённых акций, которые в дальнейшем нужно отправить в processsale |
| cards | jsonb | Параметр будет если передать входной параметр full_data со значением true. Массив всех карт клиента |
| interfaces | jsonb | Параметр будет если передать входной параметр full_data со значением true. Массив всех интерфейсов клиента |
Описание массива cards:
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| code | text | код карты |
| barcode | text | внутренний код карты (штрихкод) |
| card_id | integer | уникальный id карты в системе лояльности |
| outer_systems_interface_name | text | Наименование интерфейса внешней системы карты (0-cardPr, 1-IQOS, 2-OneDelivery, 3-OSMI, 4-CardsMobile(Кошелёк), 5-Custom application(Внешнее приложение)) |
| outer_systems_interface_type | integer | Тип интерфейса внешней системы карты (0-cardPr, 1-IQOS, 2-OneDelivery, 3-OSMI, 4-CardsMobile(Кошелёк), 5-Custom application(Внешнее приложение)) |
Описание массива interfaces:
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| interface_id | text | уникальный id карты в системе лояльности |
| interface_os | text | наименование операционной системы при налиции |
| interface_name | text | имя интерфейса (0-Telegram, 3-Mobile App, 4-Wallet, 5-Мой склад) |
| interface_type | integer | тип интерфейса (0-Telegram, 3-Mobile App, 4-Wallet, 5-Мой склад) |
searchgiftcard – поиск подарочного сертификата
Входные параметры:
https://bonus.kilbil.ru/load/searchgiftcard?h={ключ}
Входные параметры:
{
"barcode":"5551234567890"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| barcode | text | штрихкод или qr подарочного сертификата |
Описание возвращаемого результата выполнения:
Выходные параметры:
{
"result_code": "0",
"result_text": "Подарочный сертификат найден",
"gc_code": "1234567890",
"gc_barcode": "5551234567890",
"gc_state": "3",
"gc_state_text": "Использован",
"gc_write_off_type": "1",
"gc_balance": "0.00",
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| result_code | integer | код результата |
| result_text | text | текст результата |
| gc_code | text | код подарочного сертификата |
| gc_barcode | text | ктрихкод или qr подарочного сертификата |
| gc_state | integer | код статуса подарочного сертификата (0-новый, 1-продан, 2-частично использован, 3-использован, 4-истёк срок действия) |
| gc_state_text | text | текстовое описание статуса подарочного сертификата |
| gc_write_off_type | integer | вид списания подарочного сертификата (пока всегда 1-оплатой) |
| gc_balance | number | текущий баланс подарочного сертификата |
| result_code | result_text | Описание |
|---|---|---|
| 0 | Подарочный сертификат найден | Подарочный сертификат найден, возвращены его параметры |
| 2 | Подарочный сертификат не найден | Подарочный сертификат не найден в базе данных |
searchpromocode – поиск промокода
Входные параметры:
https://bonus.kilbil.ru/load/searchpromocode?h={ключ}
Входные параметры:
{
"promo_code":"101"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| promo_code | text | Номер промокода, по которому производится поиск |
Описание возвращаемого результата выполнения:
Выходные параметры:
{
"result_code": "0",
"result_text": "Промокод найден",
"_coupon_sum": null
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| result_code | integer | код результата |
| result_text | text | текст результата |
| _coupon_sum | numeric | Номинал промокода |
| result_code | result_text | Описание |
|---|---|---|
| 0 | Промокод найден | Промокод найден, возвращены его параметры |
| 1 | Промокод не найден | Промокод не найден |
| 2 | Промокод уже использован | Промокод уже был использован ранее |
| 3 | Срок действия промокода истек | Срок действия промокода истек |
| 4 | Промокод зарезервирован | Промокод зарезервирован функцией reservedpromocode |
webhooks - отправка вебхуков при изменение информации по клиенту и операциям
Отправка данных происходит по адресу, настроенному в "Интеграция" - "Исходящие вебхуки" в виде POST запроса.
В header передается параметр Api Key в token (в зависимости от настроек php может быть Token) для авторизации.
| Название настройки | Описание |
|---|---|
| Api URL | адрес домена для отправки вебхуков |
| Api Key | ключ для интеграции (передается в header POST запроса как параметр token) |
| Событие "Изменение данных клиента" | отправка данных при событии "Изменение данных клиента" |
| Событие "Операция" | отправка данных при событии "Операция" |
Выходные параметры для События "Изменение данных клиента":
https://your_domain/updateclients
Выходные параметры:
{
"client_id":"123546",
"first_name":"Имя",
"middle_name":"Отчество",
"last_name":"Фамилия",
"birth_date":"01.02.2003",
"phone":"71234567890",
"email":"0123@email.com",
"client_state":"0",
"sex":"0",
"discount_percent":"0",
"bonus_percent":"10",
"client_balance":"123",
"client_cards": [
{
"code": "1234",
"state": 0,
"barcode": "330123458",
"interface_type": 0
},
{
"code": "330123457",
"state": 0,
"barcode": "330123457",
"interface_type": 5
},
{
"code": "TST0004",
"state": 0,
"barcode": "TST0004",
"interface_type": 3
}
]
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| client_id | integer | id клиента системы лояльности |
| first_name | text | Имя клиента |
| middle_name | text | Отчество клиента |
| last_name | text | Фамилия клиента |
| birth_date | date | Дата рождения клиента |
| phone | text | Номер телефона клиента |
| text | e-mail клиента | |
| client_state | integer | состояние клиента (0 – пустой, 1 – активирован, 2 – заблокирован, 3 - зарегистрирован) |
| sex | smallint | Пол клиента (0 - женский, 1 - мужской) |
| discount_percent | text | дисконтный процент по программе лояльности |
| bonus_percent | text | бонусный процент по программе лояльности |
| client_balance | text | баланс клиента |
| client_cards | jsonb | массив объектов с картами клиента |
Содержание параметра client_cards:
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| code | text | Короткий номер карты |
| state | smallint | Состояние карты (0 - рабочая, 2 - заблокирована, 3 - заменена) |
| barcode | text | Внутренний номер карты |
| interface_type | smallint | Тип интерфейса внешней системы (0-cardPr, 1-IQOS, 2-OneDelivery, 3-OSMI, 4-CardsMobile(Кошелёк), 5-Custom application(Внешнее приложение), 10-Виртуальная карта) |
Описание возвращаемого результата выполнения:
Входные параметры:
{
"result_code": 0,
"result_text": "Успешно"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| result_code | integer | код результата (0 - успешно, остальное коды ошибок) |
| result_text | text | текст результата или ошибки |
Выходные параметры для События "Операция" :
https://your_domain/operations
Выходные параметры:
{
"move_data":"23.12.2020 11:02:50",
"move_id":"101622",
"move_asumm":"820.65",
"move_actions":[
{
"action_id": 123,
"action_name": "Название акции"
}
],
"move_bonuses":[
{
"bonus_in": 82.07,
"expire_date": null,
"bonus_in_date": "2020.12.23 11:02:50"
}
],
"bonus_presents":[
{
"bonus_in": 100.00,
"action_id": 3872,
"action_name": "Подарочек",
"expire_date": "2021.01.23 23:59:59",
"bonus_in_date": "2020.12.23 11:02:50"
}
],
"discount":"18.75",
"bonus_in":"82.07",
"bonus_out":"0.00",
"client_id":12699409,
"oper_type":"0",
"oper_description": "Продажа",
"program_nm":"Бонусная 10%",
"fiscal_sign":"123456789098",
"trade_object":"ТЕСТОВЫЙ2",
"goods":[
{
"code": "5375",
"name": "Товар 1",
"price": 209.85,
"total": 820.65,
"actions":[
{
"action_id": 456,
"action_name": "Название акции для позиции"
}
],
"barcode": "2400000011125",
"bonus_in": 82.07,
"discount": 18.75,
"quantity": 4,
"bonus_out": 0,
"discounted_price": 205.16,
"discounted_total": 820.65
}
],
"discount_percent":"",
"bonus_percent":"10",
"phone": "79129999999",
"client_balance":"555"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| move_data | date | дата и время операции |
| move_id | text | номер операции присланный с кассы |
| move_asumm | text | сумма операции |
| move_actions | array | массив акций, применённых на документ (не включает в себя акции с бонусными подаркоми) |
| move_bonuses | array | массив с бонусами на документ |
| bonus_presents | array | массив бонусных подарков на чек |
| discount | text | сумма скидки в операции |
| bonus_in | text | начисленные бонусы по операции |
| bonus_out | text | списанные бонусы по операции |
| client_id | integer | id клиента системы лояльности |
| oper_type | integer | тип операции (0 - продажа, 1 - возврат, 2 - автоматическая операция, 3 - ручная операция) |
| oper_description | text | описание операции |
| program_nm | text | название программы лояльности у клиента |
| fiscal_sign | text | фискальный признак документа, если он был передан с кассы |
| trade_object | text | название торговой точки, где была операция |
| goods | Array | array с объектами информации о товаре в документе |
| discount_percent | text | дисконтный процент по программе лояльности |
| bonus_percent | text | бонусный процент по программе лояльности |
| phone | text | номер телефона клиента в документе, если он есть |
| client_balance | text | баланс клиента |
Описание массива goods:
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| code | text | код товара |
| name | text | наименование товара |
| price | number | цена товара |
| total | number | стоимость товара |
| actions | array | массив акций, применённых на позицию |
| barcode | text | штрихкод товара |
| bonus_in | number | начислено бонусов за позицию |
| discount | number | скидка в рублях на позицию |
| quantity | number | количество товара |
| bonus_out | number | списано бонусов на позицию |
| discounted_price | number | цена товара со скидкой |
| discounted_total | number | стоимость товара со скидкой |
Описание массива move_actions и actions:
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| action_id | number | id акции |
| action_name | text | наименование акции |
Описание массива move_bonuses:
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| bonus_in | number | сумма начисленных бонусов |
| expire_date | date | дата и время сгорания бонусов |
| bonus_in_date | date | дата и время начала действия бонусов |
Описание массива bonus_presents:
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| bonus_in | number | сумма начисленных бонусов |
| action_id | number | id акции |
| action_name | text | наименование акции |
| expire_date | date | дата и время сгорания бонусов |
| bonus_in_date | date | дата и время начала действия бонусов |
Возможные значения параметра oper_description:
- "Подарок подписчику"
- "Подарок издателю"
- "Подарок за активацию клиента"
- "Подарок в день рождения"
- "Подарок в акции"
- "Перенос балансов при замене карты"
- "Инициализация баланса сертификата"
- "Перенос бонусов при миграции из старой бонусной системы"
- "Перенос суммы покупок при миграции из старой бонусной системы"
- "Пополнение баланса при создании карты"
- "Начисление бонусов издателю с продажи подписчика"
- "Бонусный подарок по акции"
- "Пополнение баланса сертификата"
- "Аннулирование баланса клиента"
- "Перенос бонусов и суммы покупок при миграции из старой бонусной системы"
- "Списание сгораемых бонусов"
- "Пополнение подарочной карты"
- "Возврат подарочной карты"
- "Оплата подарочной картой"
Описание возвращаемого результата выполнения:
Входные параметры:
{
"result_code": 0,
"result_text": "Успешно"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| result_code | integer | код результата (0 - успешно, остальное коды ошибок) |
| result_text | text | текст результата или ошибки |
Выходные параметры для События "Push сообщение" :
https://your_domain/push
Выходные параметры:
{
"phone": "71234567890",
"message": "Отправка тестового сообщения",
"client_id": 123546,
"mailing_name": null
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| phone | text | номер телефона клиента в документе, если он есть |
| message | text | текст сообщения |
| client_id | integer | id клиента системы лояльности |
| mailing_name | text | заданное имя рассылки, если это рассылка |
Описание возвращаемого результата выполнения:
Входные параметры:
{
"result_code": 0,
"result_text": "Успешно"
}
| Название параметра | Тип параметра | Описание параметра |
|---|---|---|
| result_code | integer | код результата (0 - успешно, остальное коды ошибок) |
| result_text | text | текст результата или ошибки |
Ошибки по socket
Возвращаемые коды ошибок по socket от сервера:
| Код | Описание |
|---|---|
| 403 | Forbidden -- Не зарегистрирован ApiKey. |
| 404 | Not Found -- Проверьте адрес обращения а Api |
| 500 | Internal Server Error -- Функция не найдена, проверьте название функции. |
Описание алгоритма работы на кассе с API interface
Обращение происходит по адресу https://bonus.kilbil.ru/load/{название_функции}?h={ключ}
Интерфейс должен учитывать, что на кассах нет мышки или манипулятора, установлена программируемая (специфическая) клавиатура
Авторизация клиента на кассе
Ввод карты или номера телефона (далее авторизация клиента) происходит после регистрации позиций в чек (можно вводить только одну карту в один чек одновременно, номер телефона при передаче на сервер должен начинаться с 7 и иметь длину 11 знаков)
При авторизации клиента выполняется обращение на сервер функцией searchclient с данными search_mode - вид поиска, search_value - значение поиска и с корзиной товаров объектом goods_data в виде массива (код, группа, наименование, цена, количество, сумма, цена со скидкой, сумма со скидкой)
После авторизации клиента возвращаются все данные по клиенту, на основании ответа от сервера рисуем окно для кассира с информацией по клиенту и возможностью списать бонусы (списание бонусов зависит от настройки в бонусной, и не должно превышать значения max_bonus_out). Если клиент нашелся, переходим к processsale, если нет то к активации, если она разрешена на кассе. (для неактивированной карты списание бонусов запрещается)
- После нажатия ОК выполняется функция processsale (эта функция рассчитывает и создаёт чек в бонусной). Передаются данные о чеке (номер документа, тип операции, количество списанных бонусов какое было количество максимальных бонусов к списанию, тип и значение поиска клиента) и так же содержание чека как в searchclient. (Если продаже без авторизации клиента, то используется сразу processsale по завершению всех действий кассира по регистрации товара, например при переходе оплату ) В ответ с сервера приходят данные по расчёту чека, цена и сумма со скидкой, которые необходимо назначить позиции в чеке (высчитать размер скидки и применить к товару) по каждой позиции в чеке суммовая. А так же может быть установлена цена на товар.
При отмене карты, примененные скидки и цены должны отмениться.
- После удачного закрытия чека подтверждаем его с тем же номером документа функцией confirmsale.
Активация карты/клиента
Если клиент не найден и на кассе разрешена активация клиента, переходим к заполнению анкеты
активация может быть с подтверждение по СМС и без (так же и замена, это другой параметр) Если номер телефона занят, переходим к замене, при замене не предлагаем анкетирование, используется функция replacecard (только если поиск по карте) если с подтверждением, после ввода номера телефона отправляем смс функцией askconfirmphone, затем рисуем окно для ввода кода подтверждения
проверку введенного кода проверяем функцией checkconfirmphonecode, и если успешно переходим к анкетированию.
Дальше опрашиваем Фамилию, Имя, пол, дату рождения
После опроса отправляем данные по активации клиента функцией addclient.