Интеграция с кассой

Этот документ предназначен для разработчиков кассового ПО. Он описывает, как встроить MAXMA в кассу.


1. Информация о платформе

MAXMA — облачный сервис для управления программой лояльности, состоящей из:
  • скидочных акций
  • бонусной механики  (накопление бонусов, оплата ими покупки)
  • промокодов (код, который клиент называет на кассе, чтобы участвовать в акции)

Если в кассовом ПО имеется собственная реализация программы лояльности, MAXMA полностью замещает ее. Совместная работа нескольких программ не исключена, но обсуждается и прорабатывается отдельно.

Ниже перечислены типовые бизнес-сценарии, в которые необходимо встроить обращения к API MAXMA, чтобы реализовать функции программы лояльности. Часть сценариев обязательны к реализации, другие - рекомендуемые. Необходимый набор сценариев для реализации оговаривается заранее для каждого проекта.

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

1.1. Сетевое взаимодействие

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

Для доступа к функциям MAXMA со стороны кассового ПО используется API.

  • описание API:  https://docs.maxma.com/api/ 
  • тестовые ключи можно запросить, отправив письмо на данный email:  support@maxma.com 

Все вызовы делаются в направлении от кассы к серверу по протоколу HTTPS, сообщение и ответ кодируются в формате JSON. Подробнее — в описании по ссылке выше. На подключение к серверу и ожидание ответа устанавливается тайм-аут от 2 до 30 секунд, в зависимости от качества интернет-соединения на кассе.


1.2. Схема интеграции

2. Регистрация клиента

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

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

Кассир нажимает кнопку “регистрация клиента”.

Пример реализации кнопки

Открывается форма со следующим перечнем полей:
  • Номер телефона (текстовое поле с маской)
  • Штрихкод карты (числовое поле)
  • Имя клиента (текстовое поле)
  • Пол клиента (выбор из вариантов)
  • Дата рождения (текстовое поле с маской)
  • Согласие на рассылки (галочки)
  • Другие поля (полный перечень возможных данных - в описании API)

Пример реализации диалога для ввода сведений о клиенте

Обязательно к заполнению только поле с номером телефона. Обязательность других полей оговаривается индивидуально для каждого проекта.

Пока открыто окно, если отсканировать штрихкод ручным сканером, считанный код должен попадать в поле “Штрихкод карты”.

2.1. Подтверждение номера телефона

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

Пример реализации фрагмента интерфейса для отправки кода

Касса отправляет клиенту проверочный код.
⇒ Метод API  /send-confirmation-code 

После нажатия на кнопку отправки открывается дополнительное окно для ввода кода, который клиент называет кассиру. Сейчас в MAXMA используются коды из трех цифр 0-9.

Пример реализации фрагмента интерфейса для ввода кода

Когда все требуемые поля в окне регистрации заполнены, кассир нажимает кнопку подтверждения.

Касса создает бонусный счет на сервере.
⇒ Метод API  /new-client 

Сервер может ответить ошибкой. Обработайте ошибку так, как это описано в разделе 

3. Продажа

Когда клиент подходит к кассе, чтобы оплатить покупки, кассир формирует документ продажи (чек) и добавляет в него товары. Пока кассир работает над чеком, касса хранит дополнительные сведения, связанные с этим чеком, которые относятся к программе лояльности:
  • уникальный идентификатор чека
  • телефон клиента
  • номер карты клиента
  • введенный промокод
  • кол-во бонусов, которое клиент пожелал применить к покупке
  • максимальное количество бонусов, которое клиент может применить к этой покупке (поле maxBonuses из ответа set-purchase сервера)
  • кол-во бонусов на счете клиента до покупки (поле bonuses из ответа get-client)
  • данные для печати на чеке после продажи (поля clientBonuses из ответа set-purchase)
  • ticket (поле ticket из ответа set-purchase)

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

3.1. Расчет акционных скидок

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

Пример реализации кнопки

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

Касса отправляет состав и параметры чека на сервер.
⇒ Метод API  /set-purchase 

Скидки, рассчитанные сервером, отображаются кассиру.

Пример реализации вывода скидок
Пример реализации вывода скидок - детализация

Некоторые акции доступны только для клиентов, которые авторизовались (представились) с помощью карты или номера телефона. Чтобы такие акции срабатывали, клиента нужно ввести.

3.2. Ввод клиента

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

Для ввода данных клиента делается отдельная кнопка.

Пример реализации кнопки

При нажатии на нее открывается окно для ввода штрихкода карты или номера телефона.

Пример реализации диалогового окна для ввода карты или номера телефона

При использовании ручного сканера штрихкодов, поле со штрихкодом должно заполняться с его помощью - при этом окно после сканирования автоматически закрывается.

Касса производит поиск клиента на сервере.
⇒ Метод API  /get-balance 

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

Пример реализации диалога с вопросом

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

После успешной регистрации клиента кассир возвращается обратно к продаже. Зарегистрированного клиента нужно автоматически авторизовать для текущего чека.

Другие ошибки обрабатывается так, как описано в разделе   Обработка ошибок от сервера⁠  .

Кассиру отображается баланс бонусов и имя авторизованного клиента - эта информация есть в ответе сервера.

Пример реализации фрагмента интерфейса - вывод сведений о клиенте

После ввода клиента касса обязательно обновляет пречек для текущего чека.
⇒ Метод API  /set-purchase 

3.3. Ввод промокода

Для ввода промокода делается отдельная кнопка.

Пример реализации кнопки

При нажатии на нее, открывается окно с единственным полем ввода для кода. Код состоит из русских и латинских символов, цифр и знаков минус (-). Код нечувствителен к регистру.

Пример реализации диалога для ввода промокода

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

Касса обязательно обновляет пречек для текущего чека.
⇒ Метод API  /set-purchase 

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

Ошибки применения промокода возвращаются сервером в поле 
calculationResult->promocode->error. Если сервер вернул ошибку, промокод не считается примененным. Если промокод применился, во всех последующих вызовах set-purchase нужно указывать примененный к чеку промокод.

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

3.4. Оплата с бонусного счета

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

Функцию оплаты бонусами можно оформить или как отдельную кнопку, или совместить с штатным окном оплаты, которое уже есть в кассовом ПО. 

Пример реализации кнопки

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

Для расчета максимального количества бонусов к применению делается запрос  set-purchase . Искомое число возвращается сервером в ответе в поле maxBonuses.

Пример реализации диалога для ввода бонусов к списанию

Введя количество, кассир нажимает кнопку подтверждения.

После ввода количества бонусов касса обязательно обновляет пречек.
⇒ Метод API  /set-purchase 

Ошибки списания бонусов возвращаются сервером в поле calculationResult->bonuses->error. Если сервер вернул ошибку, бонусы не считаются примененными. Если бонусы применились без ошибок, во всех последующих вызовах set-purchase нужно указывать введенное количество бонусов для списания.

3.5. Проведение чека

Проведение чека - это его фискализация и сопутствующие действия. В самом этом процессе ничего не изменяется.

Перед проведением чека обязательно делается запрос  set-purchase  на сервер. Если вызов сервера завершился с ошибкой, например, при отсутствии связи, кассиру задается вопрос о том, нужно ли провести чек без учета внешних скидок и бонусов:

Пример реализации диалога

Если кассир ответил “Продолжить”, из чека убирается вся информация, связанная с программой лояльности, то есть продажа проходит так, как если бы интеграции с MAXMA не было. Метод  /confirm-ticket  для такого чека не вызывается. Отсутствие связи с сервером не должно запрещать проводить чек обычным способом.

Если кассир ответил “Отмена”, проведение отменяется, кассир возвращается к работе над чеком.

После успешного проведения чека в кассовом ПО, его подтверждение производится на стороне MAXMA.

Касса вызывает подтверждение чека на сервере.
⇒ Метод API  /confirm-ticket 

Если проведение чека в кассовом ПО не состоялось, метод API не вызывается.

3.6. Аннулирование чека

При удалении непроведенного чека в кассовом ПО, он также удаляется на стороне MAXMA.

Касса вызывает удаление чека на сервере.
⇒ Метод API  /discard-ticket 

3.7. Печать на чеке

На чеке печатается информация о скидках и бонусах. Информация для печати берется из последнего ответа  set-purchase , полученного от сервера перед проведением чека.

Печатаются строки:
  • Начислено бонусов
  • Списано бонусов
  • Всего бонусов
  • Доступно для списания бонусов
  • Примененный промокод

Пример вывода информации о бонусах на чеке

4. Возврат товара

Для бизнеса, в котором возможны возвраты товаров клиентами, необходимо добавить вызов API MAXMA после того, как в кассовом ПО успешно проведен документ возврата.

Для сервера MAXMA нет различия между возвратами в день покупки или возвратами, сделанными уже после закрытия смены - вызов сервера строится идентично.

Касса вызывает метод, делающий возврат бонусов.
⇒ Метод API  /apply-return 

5. Замена карты/телефона

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

Для открытия окна обновления профиля предусмотрена отдельная кнопка.

Пример реализации кнопки

При нажатии на кнопку открывается окно, похожее на окно регистрации клиента. На нем представлены те же поля, предварительно заполненные текущими параметрами клиента.

Пример реализации диалогового окна редактирования клиента

Для получения текущих данных о клиенте касса отправляет запрос.
⇒ Метод API  /get-balance 

Пока открыто окно, если отсканировать штрихкод ручным сканером, считанный код должен попадать в поле “Штрихкод карты”.

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

Когда все требуемые поля в окне обновления профиля заполнены, кассир нажимает кнопку подтверждения.

Касса вызывает метод на сервере, который обновляет информацию о клиенте.
⇒ Метод API  /update-client 

Сервер может ответить ошибкой. Обработайте ошибку так, как это описано в разделе   Обработка ошибок от сервера⁠  .

6. Обработка ошибок от сервера

6.1. Ошибки процессинга

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

Информация состоит из следующих полей:
  • errorCode - числовой код ошибки
  • description - текстовое описание ошибки
  • hint - подробности, почему произошла ошибка

Иногда при получении определенной ошибки требуется выполнить какие-нибудь особенные действия. Например, когда производится поиск клиента на сервере и сервер вернул ошибку с кодом errorCode=3 (“Клиент не найден”), то кассиру открывается диалог, позволяющий сразу же создать клиента, которого искали. В таких случаях логику программы следует основывать на кодах ошибки (в данном случае — на коде 3).

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

Пример реализации окна с сообщением

Кроме того, рекомендуется записывать ошибку в журнал (лог).

6.2. Ошибки сетевого соединения

В случае если произошла сетевая ошибка — не удалось подключиться к серверу или HTTP-код ответа сервера не 200 — можно отобразить диалоговое окно с предложением повторить запрос. При утвердительном ответе запрос (в том же самом виде) повторно отправляется на сервер.

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

7. Передача товарного каталога

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

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

Подробнее смотрите в  Загрузка номенклатуры в MAXMA⁠ .

8. Чеклист тестирования

Налейте чашечку вкусного кофе и сообщите  support@maxma.com , что приступаете к тестированию. Мы поможем вам все проверить.

Регистрация клиента

Выдача карты — заполнить все поле (включая код из SMS), проверить их передачу в MAXMA

Продажа

Продажа без карты
Продажа с картой, без списания бонусов – проверяем сумму и бонусы в MAXMA
Продажа с бонусами (применяем больше, чем доступно) – проверяем сумму и бонусы в MAXMA
Продажа (без карты) – проверяем, не привязалась ли карта от прошлой покупки
Промокод «TEST» – проверяем на покупке (без карты лояльности) дается ли скидка 50%; проверяем корректность изменения информации в столбцах: Выручка; Применений
Печать бонусов на чеке – проверяем есть ли эта информация

Замена карты

Редактирование в MAXMA – изменить все поля, проверить данные в кассовом ПО
Редактирование в кассовом ПО – изменить все поля, проверить передачу в MAXMA  

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

Возврат (день в день) покупки со списание бонусов – вернулись ли бонусы   
Возврат (после закрытия смены) – вернулись ли бонусы