Готовые интеграции с кассовыми программами

Техническое задание на интеграцию СкидкаБота с кассовой программой

1. Общее описание.

Скидкабот - дисконтный сервис в телеграмме. Кассир читает сканером штрихкода предъявленный покупателем QR код. Программа расшифровывает JSON содержащийся в этом qr-коде.

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

После этого кассир выбирает: начислить бонусы клиенту с новой покупки, или списать существующие и сделать скидку.

Кассовая программа вызывает соответствующие api функции скидкабота, в зависимости от выбора кассира.

2. Настройка модуля.

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

3. Сканирование QR-кода покупателя.

После сканирования QR-кода сканером вы получите JSON следующего вида:

{"type":"Skidkabot","vendor":4,"client":83532824,"secret":31766}

Либо ошибку, с кодом и описанием.

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

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

Следует иметь в виду, что период дейстивия сгенерированного QR кода составляет одни сутки. Это сделано для защиты клиентов от случайного копирования. Через сутки клиенту придется сгенерировать новый QR код. При этом secret меняется.

4. Запрос информации о покупателе.

Для получения баланса дисконтной карты, отправьте на https://skidkabot.ru/api_get_balance.php POST запрос

POST параметры запроса:

Код магазина. Имя параметра "fk_vendor". - Из настроек

Секретный код магазина. Имя параметра "vendor_secret". - Из настроек

Номера получателя. Имя параметра "fk_client". - Из прочитанного QR-кода

Контрольная цифра QR-кода. Имя параметра "qr_secret". -Из прочитанного QR-кода

В ответ вы получите JSON следующего вида, либо ошибку.

{ "code": 0, "first_name": "Александр", "last_name": "Татарченко", "balance": 2365, "p_plus": 2, "p_minus": 10 }

5. Вывод на экран диалогового окна.

Выводим на экран кассы информацию об имени клиента, его балансе, а также баллы к начислению или списанию рассчитанные по вашим внутренним алгоритмам, либо используя проценты p_plus и p_minus, которые задаются в личном кабинете Скидкабота.

(Если вы хотите вести дополнительный классификатор клиентов в вашей учетной системе, то уникальный номер клиента можно брать из отсканированного QR-кода)

И две кнопки. "Начислить бонусы" и "Списать бонусы"

Рекомендация из опыта других клиентов: если при списании бонусов сумма списываемых бонусов меньше суммы чека, т.е. клиенту необходимо часть покупки оплатить деньгами, следует начислить бонусы на ту часть оплаты, которая оплачена деньгами.

6. Функция Начислить бонусы.

Для начисления бонусов клиенту отправьте POST запрос на https://skidkabot.ru/api_plus_balance.php

POST параметры запроса:

fk_vendor - код магазина из настроек

vendor_secret - секретный код магазина, из настроек

fk_client - код клиента из прочитанного QR-кода

qr_secret - секретный номер из прочитанного QR-кода

kassa - номер кассы (int) для дополнительной аналитики, если несколько магазинов в сети.

summa - сумма начисляемых бонусов

В ответ вы получите новый баланс клиента или сообщение об ошибке

{ "code": 0, "first_name": "Александр", "last_name": "Татарченко", "balance": 2375 }

7. Функция Списать бонусы.

Для списания бонусов клиента отправьте POST запрос на https://skidkabot.ru/api_minus_balance.php

POST параметры запроса:

fk_vendor - код магазина из настроек

vendor_secret - секретный код магазина, из настроек

fk_client - код клиента из прочитанного QR-кода

qr_secret - секретный номер из прочитанного QR-кода

kassa - номер кассы (int) для дополнительной аналитики, если несколько магазинов в сети.

summa - сумма списываемых бонусов

В ответ вы получите новый баланс клиента или сообщение об ошибке

{ "code": 0, "first_name": "Александр", "last_name": "Татарченко", "balance": 2365 }

8. Коды ошибок.

{"code": 0} - Ошибок нет, всё в порядке.

{"code": 1, "text": "Не хватает обязательного параметра: Код магазина (fk_vendor)"}

{"code": 2, "text": "Не хватает обязательного параметра: Код клиента (fk_client)"}

{"code": 3, "text": "Не хватает обязательного параметра: Секретный ключ магазина (vendor_secret)"}

{"code": 4, "text"" "Не хватает обязательного параметра: Временный ключ QR-кода (qr_secret)"}

{"code": 5, "text": "Магазин с таким сочетанием кода и секретного ключа не найден"}

{"code": 6, "text": "Клиент не зарегистрирован в базе данных"}

{"code": 7, "text": "QR-код не зарегистрирован в базе данных"}

{"code": 8, "text": "Неверная контрольная сумма QR-кода. Перевыпустите QR-код."}

{"code": 9, "text": "QR-код устарел. Перевыпустите QR-код."}

{"code": 10} - в начислении и списании баллов не применяется.

{"code": 11, "text": "Не хватает обязательного параметра: Сумма прибавляемых бонусов (summa)"}

{"code": 12, "text": "Не хватает обязательного параметра: Сумма списываемых бонусов (summa)"}

{"code": 13, "text": "У клиента не хватает баллов для списания."}

{"code": 14} - в начислении и списании баллов не применяется.

{"code"=>15, "text"=>"Извините, на вашем счете отрицательный баланс и СкидкаБот не работает. Пополните ваш баланс на сайте http://skidkabot.ru))"

Скачать техзадание

Описание API функций СкидкаБота!

Имя тестового бота https://t.me/Skidkabotmymagbot

Код тестового магазина 4

Секретный код тестового магазина 31337

Остальные параметры, такие как fk_client и qr_secret читайте в предъявляемом клиентом QR-коде