NAV

Бонусная система kilbil

Сайт компании kilbil.ru.

Платформа управления лояльностью bonus.kilbil.ru.

Техподдержка support@kilbil.ru.

Описание API functions

Общая информация

Каждый запрос с кассы сопровождается 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",
    "shift_open_dt":"09.11.20 08:01:44"
}
Название параметра Тип параметра Описание параметра
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- мужской
not_to_send_sms integer = null::integer Не отправлять информационных смс
not_to_send_email integer = null::integer Не отправлять информационных e-mail
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 Дата и время открытия смены (используется для расчёта показателя по активированным клиентам на кассе)

Описание возвращаемого результата выполнения:

Выходные параметры:

{
  "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)

addshop – добавление торговой точки

Входные параметры:

https://bonus.kilbil.ru/load/addshop?h={ключ}

Входные параметры:

{
    "name":"Магазин №5",
    "address":"г. Екатеринбург, ул. Советская",
    "parent_id":""
}
Название параметра Тип параметра Описание параметра
name text название торговой точки
address text адрес торговой точки
parent_id integer = null::integer id торговой сети

Описание возвращаемого результата выполнения:

Выходные параметры:

{
  "success": 1,
  "result_code": 0,
  "result_text": "Торговая точка создана"
}
Название параметра Тип параметра Описание параметра
result_code integer код результата
result_text text текст результата
result_code result_text Описание
0 Торговая точка создана
100 Неполные данные

askconfirmphone – команда отсылки СМС с кодом подтверждения

Входные параметры:

https://bonus.kilbil.ru/load/askconfirmphone?h={ключ}

Входные параметры:

{
    "client_id":"4004565",
    "phone":"79129999999",
    "sms_type":1
}
Название параметра Тип параметра Описание параметра
client_id integer id клиента
phone text номер телефона
sms_type integer тип шаблона смс (0 - СМС с пин-кодом подтверждения для регистрации клиента; 1 - CМС с пин-кодом подтверждения для авторизации покупки)
is_limited boolean если задан лимит в настройка, то смс с параметром true может уходить не чаще заданного лимита (функционал для виджетов, сайтов, приложений), не обязательный параметр, по умолчанию false

Описание возвращаемого результата выполнения:

Выходные параметры:

{
  "success": 1,
  "result_code": "0",
  "type_confirmation_code": "0"
}
Название параметра Тип параметра Описание параметра
success integer Успешное выполнение отправки СМС
result_code integer Код результата
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,
    "payments":[
        {
            "type":0,
            "payment_amount":50
        },
        {
            "type":1,
            "payment_amount":41.47
        }
    ]
}
Название параметра Тип параметра Описание параметра
move_id text id чека на торговом оборудовании
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 Фискальный Признак Документа (ФП)
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 Неподтвержденная продажа по заданным параметрам не найдена Неподтвержденная продажа по заданным параметрам не найдена

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 integer id клиента
outer_systems_interface_type smallint Тип интерфейса внешней системы (3-OSMI, 4-CardsMobile(Кошелёк))

Описание возвращаемого результата выполнения:

Выходные параметры:

{

}
Название параметра Тип параметра Описание параметра
result_code integer код результата
result_text text текст результата
card_code text номер сгенерированной карты
result_code result_text Описание
0 Карта успешно создана Карта успешно сгенерирована
1 Использование электронных карт (Wallet) отключено в системных настройках Использование электронных карт (Wallet) отключено в системных настройках
2 Ошибка при сохранении карты Клиент не создан, так как не удалось сохранить сгенерированную электронную карту (Wallet)

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(Внешнее приложение)), без этого параметра вернутся все действующие карты клиента

Описание возвращаемого результата выполнения:

Выходные параметры:

{
 "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 дата и время окончания действия (“сгорания”) бонусов

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 Тип интерфейса внешней системы (0-cardPr, 1-IQOS, 2-OneDelivery, 3-OSMI, 4-CardsMobile(Кошелёк), 5-Custom application(Внешнее приложение))

Описание возвращаемого результата выполнения:

Выходные параметры:

{
  "confirmation_code": "065189"
}
Название параметра Тип параметра Описание параметра
confirmation_code text номер временной карты

getdetailingbymove - получение списка товаров документа

Входные параметры:

https://bonus.kilbil.ru/load/getdetailingbymove?h={ключ}

Входные параметры:

{
    "id": 85330029,
    "move_date": "15.02.2021 13:07:53"
}
Название параметра Тип параметра Описание параметра
id integer внутренний id операции
move_date timestamp Точная дата документа

Описание возвращаемого результата выполнения:

Выходные параметры:

{
 "move_detail": [
  {
   "code": "2137",
   "name": "Наименование товара",
   "price": 130,
   "total": 105,
   "barcode": "2400000005926",
   "bonus_in": 10.53,
   "discount": 11.7,
   "quantity": 1,
   "bonus_out": 0
  }
 ],
 "result_code": "0",
 "result_text": "Получено 1 элементов..."
}
Название параметра Тип параметра Описание параметра
move_detail jsonb массив объектов, перечисление номенклатуры в операции
result_code integer код результата
result_text text описание результата

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,
      "trade_object": null,
      "bonus_in_date": "10.07.2019 00:00:00",
      "bonus_term_date": "11.07.2019 00:00:00",
      "oper_description": "Ручное начисление"
    },
    {
      "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,
      "trade_object": "ТЕСТОВЫЙ2",
      "bonus_in_date": "02.04.2019 12:38:32",
      "bonus_term_date": null,
      "oper_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,
      "trade_object": "ТЕСТОВЫЙ2",
      "bonus_in_date": "02.04.2019 12:06:31",
      "bonus_term_date": null,
      "oper_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,
      "trade_object": "ТЕСТОВЫЙ2",
      "bonus_in_date": "02.04.2019 12:05:36",
      "bonus_term_date": null,
      "oper_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,
      "trade_object": "ТЕСТОВЫЙ2",
      "bonus_in_date": "02.04.2019 12:05:16",
      "bonus_term_date": null,
      "oper_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 - ручная операция)
oper_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={ключ}

Входные параметры:

{
    "date": "23.12.2020"
}
Название параметра Тип параметра Описание параметра
date timestamp дата, от которой будет производится расчёт переменной <ДатаДр18Лет> (не обязательный параметр)

Описание возвращаемого результата выполнения:

Выходные параметры:

{
  "result_code": 0,
  "slides": [
    "Выручка: 91.47 руб.\r\nСредний чек: 91.47 руб.",
    "Продажи с картой 100 %"
  ],
  "info": "Алкоголь можно если старше <ДатаДр18Лет>"
}
Название параметра Тип параметра Описание параметра
slides jsonb Массив объектов слайдов, каждый слайд как элемент массива
info text Статичный текст для всех слайдов, переменная <ДатаДр18Лет> говорит, что нужно подставить дату текущая дата - 18 лет (если во входные параметры передана дата, то в ответе будет сразу нужная дата)

getsoldgoods – Получение списка проданных на робокассе товаров за период

Входные параметры:

https://bonus.kilbil.ru/load/getsoldgoods?h={ключ}

Входные параметры:

{

}
Название параметра Тип параметра Описание параметра
dt1 timestamp Временная метка начала периода
dt2 timestamp Временная метка окончания периода
trade_equipment_id integer id кассы
trade_object_id integer = null::integer id магазина

Описание возвращаемого результата выполнения:

Выходные параметры:

{

}
Название параметра Тип параметра Описание параметра
code text Код товара
vendor_code text SKU товара
name text Название товара
is_active boolean Активность товара (активны только товары, присутствующие в последней загрузке)
quantity numeric Количество товара
bonus_out numeric Сумма оплаты бонусами на робокассе

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",
                "name": "Наименование товара",
                "full_name": "Полное наименование товара",
                "unit": "шт",
                "price1": 10,
                "price2": 20,
                "price3": 30,

            },
            {
                "id": "7f8431b6-a1e9-11e7-b80e-58fb84fa9d6b",
                "is_group": false,
                "delete_mark": false,
                "code": "608",
                "name": "название товара",
                "full_name": "Полное название товара",
                "unit": "шт",
                "price1": 10,
                "price2": 20,
                "price3": 30,
            }
        ]
    },
        {
        "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",
                "name": "Наименование товара",
                "full_name": "Полное наименование товара",
                "unit": "шт",
                "price1": 10,
                "price2": 20,
                "price3": 30,
            },
            {
                "id": "7f8431b6-a1e9-11e7-b80e-58fb84fa9d6b",
                "is_group": false,
                "delete_mark": false,
                "code": "608",
                "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": "Продажа товара с сайта"
}
Название параметра Тип параметра Описание параметра
client_id integer = null::integer id клиента
bonus_in numeric сумма начисления
bonus_out numeric сумма списания
total numeric полная сумма чека без скидок
description text комментарии к операции

Описание возвращаемого результата выполнения:

Выходные параметры:

{
  "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.20 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\":1,\"total\":130,\"minPrice\":0,\"maxDiscount\":100,\"discounted_price\":129.98000000000002,\"discounted_total\":129.98,\"parent_code\":\"2082\",\"parent_vendor_code\":\"\"},{\"code\":\"3957\",\"barcode\":\"4870001723859\",\"vendor_code\":\"3957\",\"name\":\".Erzmann Dark темное фильтр паст Арасан 0,45л\",\"price\":68.32000000000001,\"quantity\":1,\"total\":68.32000000000001,\"minPrice\":0,\"maxDiscount\":100,\"discounted_price\":68.32000000000001,\"discounted_total\":68.32000000000001,\"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_bonus_out функции searchclient
goods_data jsonb JSON с позициями чека в полном виде
move_id text id чека на торговом оборудовании
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)
shift_number smallint = NULL::smallint Номер смены

Товары (параметр 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 не найден клиент

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.32000000000001,\"quantity\":1,\"total\":68.32000000000001,\"minPrice\":0,\"maxDiscount\":100,\"discounted_price\":68.32000000000001,\"discounted_total\":68.32000000000001,\"parent_code\":\"4085\",\"parent_vendor_code\":\"\"}]",
  "promo_codes":{
    "coupons":[
      {
        "coupon":"1001"
      }
    ]
  },
  "card_apply_dt":"09.11.20 17:28:23"
}
Название параметра Тип параметра Описание параметра
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)

Товары (параметр 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",
  "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,
  "sum_to_next_status": null,
  "phone_is_free": "0",
  "outer_systems_interface_type": null,
  "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 - зарегистрирован)
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 - мужской)
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 Сумма покупок, которую нужно совершить в текущем периоде для получения следующего статуса следующего периода
sum_to_next_status numeric Сумма покупок, которую осталось совершить до достижения суммы next_status_purchases_sum
phone_is_free smallint При поиске по номеру телефона: 1 - телефона свободен, 0 - телефон занят; при поиске по другим реквизитам значение равно null.
outer_systems_interface_type smallint Тип интерфейса карты
tags jsonb Теги клиента
top_sales jsonb Любимые покупки клиента
program_write_off_type jsonb Тип оплаты подарочным сертификатом (0 - Скидкой, 1 - Оплатой)
allow_manual_card_spend integer Настройка списание по ручному вводу карты разрешено (для Эвотор)
_bill_data jsonb Используется для предварительного расчёта акций с ценой, возвращает id применённых акций, которые в дальнейшем нужно отправить в processsale

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 Срок действия промо-кода истек Срок действия промо-кода истек

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_id integer id клиента системы лояльности
first_name text Имя клиента
middle_name text Отчество клиента
last_name text Фамилия клиента
birth_date date Дата рождения клиента
phone text Номер телефона клиента
email text e-mail клиента
client_state integer состояние клиента (0 – пустой, 1 – активирован, 2 – заблокирован, 3 - зарегистрирован)
sex smallint Пол клиента (0 - женский, 1 - мужской)
discount_percent text дисконтный процент по программе лояльности
bonus_percent text бонусный процент по программе лояльности
client_balance text баланс клиента

Описание возвращаемого результата выполнения:

Входные параметры:

{
  "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":"130.00",
  "discount":"0.00",
  "bonus_in":"0.00",
  "bonus_out":"0.00",
  "client_id":"NULL",
  "oper_type":"0",
  "oper_description": "Продажа",
  "program_nm":"",
  "trade_object":"ТЕСТОВЫЙ2",
  "discount_percent":"",
  "bonus_percent":"",
  "client_balance":""
}
Название параметра Тип параметра Описание параметра
move_data date дата и время операции
move_id text номер операции присланный с кассы
move_asumm text сумма операции
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 название программы лояльности у клиента
trade_object text название торговой точки, где была операция
discount_percent text дисконтный процент по программе лояльности
bonus_percent text бонусный процент по программе лояльности
client_balance text баланс клиента

Возможные значения параметра oper_description:

Описание возвращаемого результата выполнения:

Входные параметры:

{
  "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={ключ} Интерфейс должен учитывать, что на кассах нет мышки или манипулятора, установлена программируемая (специфическая) клавиатура

Авторизация клиента на кассе

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

  2. При авторизации клиента выполняется обращение на сервер функцией searchclient с данными search_mode - вид поиска, search_value - значение поиска и с корзиной товаров объектом goods_data в виде массива (код, группа, наименование, цена, количество, сумма, цена со скидкой, сумма со скидкой)

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

  1. После нажатия ОК выполняется функция processsale (эта функция рассчитывает и создаёт чек в бонусной). Передаются данные о чеке (номер документа, тип операции, количество списанных бонусов какое было количество максимальных бонусов к списанию, тип и значение поиска клиента) и так же содержание чека как в searchclient. (Если продаже без авторизации клиента, то используется сразу processsale по завершению всех действий кассира по регистрации товара, например при переходе оплату ) В ответ с сервера приходят данные по расчёту чека, цена и сумма со скидкой, которые необходимо назначить позиции в чеке (высчитать размер скидки и применить к товару) по каждой позиции в чеке суммовая. А так же может быть установлена цена на товар.

При отмене карты, примененные скидки и цены должны отмениться.

  1. После удачного закрытия чека подтверждаем его с тем же номером документа функцией confirmsale.

Активация карты/клиента

Если клиент не найден и на кассе разрешена активация клиента, переходим к заполнению анкеты

активация может быть с подтверждение по СМС и без (так же и замена, это другой параметр) Если номер телефона занят, переходим к замене, при замене не предлагаем анкетирование, используется функция replacecard (только если поиск по карте) если с подтверждением, после ввода номера телефона отправляем смс функцией askconfirmphone, затем рисуем окно для ввода кода подтверждения

проверку введенного кода проверяем функцией checkconfirmphonecode, и если успешно переходим к анкетированию.

Дальше опрашиваем Фамилию, Имя, пол, дату рождения

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