Интеграция с WEB

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

Если ваш сайт на Битриксе, используйте  наш готовый модуль⁠ .


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

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

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

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

Если вы разрабатываете интернет-магазин на языке PHP, то рекомендуем использовать нашу интеграционную библиотеку:  https://github.com/cloudloyalty/client-php .

  • Ссылка на актуальный API:  https://docs.maxma.com/api/ 
  • Тестовые ключи можно запросить тут:  support@maxma.com 
  • Инструкция по использованию платформы:  https://help.maxma.com/p/Erl7Qicz1AkRef/MAXMA 

Для удобства мы разбили это руководство на два этапа:
    .1На первом этапе описаны базовые механики, которые точно понадобятся при любой интеграции — без них не обойтись;
    .2На втором этапе перечислены дополнительные функции, от некоторых из которых можно отказаться, чтобы сэкономить время и силы.

Первый этап (основной функционал)

1. Регистрация новых клиентов

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

Клиент в MAXMA идентифицируется по одному из полей (или обоим сразу):
  • номеру телефона;
  • внешнему ID клиента (ваш идентификатор в базе сайта).
Как минимум одно из этих полей является обязательными.

Кроме них передаются дополнительные сведения (максимум того, что доступно):
  • email;
  • имя клиента;
  • пол;
  • дата рождения;
  • и т.д.

Backhand Index Pointing Right cм. метод API  /new-client 

Важно в запросе также указать место регистрации клиента (блок shop), чтобы MAXMA отличала клиентов, зарегистрированных на сайте, от всех прочих.

Также нужно быть готовым, что клиент, который создается в MAXMA, может уже существовать (например, зарегистрировался в розничном магазине), поэтому алгоритм создания клиента в MAXMA должен быть такой:
    .1создать клиента в MAXMA с указанным номером телефона;
    .2если клиент с таким номером телефона уже существует, то обновить клиента, проставив ему внешний ID, а также дозаполнив те поля, которые не заполнены (email, имя, пол, дата рождения и так далее).


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

При авторизации клиента на сайте вы можете получить подробности о нем из системы MAXMA:

Backhand Index Pointing Right cм. метод API  /get-balance 

Если окажется так, что авторизованного клиента нет в MAXMA, нужно его создать там, как описано в разделе  регистрация клиента⁠ .

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


3. Расчет корзины

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

При этом скидки, назначаемые самим сайтом, также могут быть учтены при расчете (применяются до скидок MAXMA). Передавайте такие скидки в запросе на расчет.


3.1. Расчет скидок и бонусов

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

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

Backhand Index Pointing Right cм. метод API  /v2/calculate-purchase 

Скидки должны примениться к корзине и отобразиться покупателю. MAXMA возвращает следующие виды скидок:
  • auto, manual — это скидки, в расчете которых MAXMA не участвовала, они просто продублированы из запроса. Это те скидки, которые применены вне MAXMA, например, движком сайта;
  • offer — скидка по акционной механике, настроенной в MAXMA;
  • promocode — скидка по промокоду, эта механика описана во второй части этого руководства;
  • bonuses — скидка, назначенная благодаря примененным бонусам;
  • rounding — скидка, обычно несколько копеек, назначенная, чтобы округлить итоговую сумму.

Если покупатель авторизован, при запросе расчета корзины используется его номер телефона и/или ID.

Для неавторизованных пользователей делается расчет с указанием трафаретного номера телефона. Трафаретный номер телефона — это вымышленный номер, например +7 777 7777777, который применяется, чтобы составить корректный запрос к процессингу MAXMA, когда нет данных о реальном номере телефона покупателя.


3.2. Применение бонусов

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


Количество бонусов, доступных к списанию, а также прогноз бонусов к начислению нужно взять из ответа на запрос  /v2/calculate-purchase .

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

Backhand Index Pointing Right cм. метод API  /v2/calculate-purchase 

Расчет при списании бонусов может завершиться ошибкой, например, если вы запросили к списанию больше бонусов, чем есть на счету у клиента, или если для текущей корзины нельзя списать запрошенное количество. Такая ошибка возвращаются сервером в блоке bonuses, ее нужно вывести покупателю. Смотрите подробнее в  разделе "обработка ошибок"⁠ .

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

4. Оформление заказа и его цикл жизни

4.1. Оформление

После того как покупатель оформит заказ, необходимо передать его на сервер MAXMA.

Backhand Index Pointing Right cм. метод API  /v2/set-order 

По структуре данных этот запрос очень похож на  /v2/calculate-purchase , но, в отличие от него, создает или заменяет заказ на стороне MAXMA. Метод  /v2/set-order  можно вызывать многократно, при этом каждый очередной вызов с одним и тем же orderId отменяет эффект от предыдущего вызова и записывает новые данные о заказе.

Передаются следующие сведения:
  • состав корзины (включая полную информацию о товарах);
  • информация о покупателе (номер телефона, ID);
  • количество примененных бонусов;
  • информация о торговой точке, где создан заказ (домен сайта);
  • примененный промокод (подробности во втором этапе этого руководства).

Метод возвращает результаты финального расчета, сделанного непосредственно при записи заказа. Эти результаты аналогичны тем, которые возвращались при вызове  /v2/calculate-purchase , и можно использовать те же механизмы, чтобы записать рассчитанные скидки в заказ.

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


4.2. Подтверждение заказа менеджером

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

Backhand Index Pointing Right cм. метод API  /v2/set-order 


4.3. Отмена заказа

Если заказ на данном этапе отменяется, необходимо прислать запрос на отмену заказа на сервер MAXMA.

Backhand Index Pointing Right cм. метод API  /cancel-order 

Отмененный в MAXMA заказ больше нельзя вернуть в работу. Вызов  /v2/set-order  для него будет завершаться ошибкой.


4.4. Выкуп заказа

Как только заказ считается завершенным (доставлен курьером и оплачен, оплачен сразу после оформления или выкуплен в пункте самовывоза), интернет-магазин отправляет подтверждающий запрос в MAXMA.

Он необходим для завершения заказа на стороне MAXMA, для окончательного начисления/списания бонусов (до этого момента бонусы находятся в резерве).

Backhand Index Pointing Right cм. метод API  /confirm-order 

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

Backhand Index Pointing Right cм. метод API  /v2/set-order 


5. Возврат заказа/товара

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

Backhand Index Pointing Right cм. метод API  /apply-return 

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

6. Описание программы лояльности

Чтобы посетители могли заранее ознакомиться с условиями программы лояльности, разместите её описание на отдельной странице сайта. Текст условий мы предоставим.


7. Обработка ошибок

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

Низкоуровневые ошибки транспортного уровня:
  • ошибка разрешения домена,
  • таймаут соединения,
  • таймаут ожидания ответа,
  • HTTP-код ответа, отличный от 200.

Они означают, что сервер не получил запрос (или получил, но не смог прислать ответ). При возникновении такой ошибки текущую операцию на сайте следует прервать, ошибку записать в лог, а пользователю показать сообщение с нейтральным текстом без уточнения деталей, например: "При обработке запроса произошла ошибка".
Логические ошибки процессинга, например:
  • "Клиент не найден";
  • "Превышено кол-во бонусов, которое можно применить";
  • "Условия применения промокода не выполнены" и т.д.

Они означают, что сервер принял запрос, но не смог выполнить запрошенную операцию. Для такой ошибки сервер возвращает код (поле code), описание ошибки на русском языке (message) и подсказку для разработчика на английском языке (hint).

В ответ на запросы  /v2/calculate-purchase ,  /v2/set-order  процессинг может вернуть логическую ошибку в трех местах:
  • на уровне всего запроса — операция не выполнена;
  • в блоке bonuses — расчет заказа произведен, но не удалось применить бонусы;
  • в блоке promocode — расчет заказа выполнен, но не удалось применить промокод.

Некоторые логические ошибки ваш сайт может обрабатывать по-особому, например, ошибку "Клиент не найден" обрабатывать автоматически и создавать нового клиента в MAXMA. В этом случае опираться нужно на возвращаемый код ошибки, а не на ее текст.

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

Второй этап (дополнительный функционал)

1. Подтверждение телефона через SMS-код

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


MAXMA берет на себя функцию генерации и отправки кода.

Backhand Index Pointing Right cм. метод API  /send-confirmation-code 

На стороне сайта нужно реализовать следующее:
    .1когда пользователь ввел свой номер телефона, сделать вызов  /send-confirmation-code ;
    .2сохранить полученные в ответе  /send-confirmation-code  код в сессии;
    .3сравнить введенный клиентом код с тем, что ранее был сохранен в сессии;

Рекомендуется предусмотреть повторный запрос кода (но не ранее чем через 30 секунд после предыдущей попытки) на случай, если первый код по какой-либо причине не дошел.

Метод  /send-confirmation-code  можно вызывать несколько раз для одного и того же клиента/номера телефона. С каждым вызовом клиенту будет сгенерирован и отправлен новый код, при этом ранее отправленный код аннулируется.

На стороне MAXMA есть ряд проверок, которые помогут защитить сайт от злоупотребления функцией отправки SMS. Ошибка возникнет, если:
  • запрашивать код слишком часто (менее 30 секунд после предыдущей отправки);
  • запросить подряд слишком много кодов на один и тот же номер;
  • превысить максимально разрешенное кол-во отправок SMS в час;
  • превысить кол-во запросов к процессингу за секунду.

2. Обновление данных о клиенте в MAXMA

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

Backhand Index Pointing Right cм. метод API  /update-client 


При необходимости этим же запросом можно поменять и номер телефона. В таком случае при вызове  /update-client  указывается прежний номер в поле phoneNumber, а новый номер — внутри блока client. При этом также важно  провалидировать новый номер⁠ .

4. Вывод информации в корзине о начисляемых бонусах

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


Рассчитайте скидки и бонусы для текущей корзины методом  /v2/calculate-purchase , как описано в разделе  Расчет скидок и бонусов⁠ . В ответе от сервера MAXMA будет достаточно данных, чтобы для каждой строки корзины вывести, какое количество бонусов будет начислено за выкуп товара.

Хорошим решением будет не выводить "+0 бонусов", если для какой-то из строк начисления нет.

5. Применение промокода

Промокод — это короткая строка, состоящая из цифр и букв, которая дает определенные преимущества покупателю при оформлении заказа.

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

На сайте может быть встроенная механика применения купонов/промокодов, в этом случае алгоритм обработки промокода может быть таким:
    .1введенный промокод проверяется движком сайта;
    .2если сайт не распознал введенный код, промокод обрабатывается через MAXMA.

На экране с корзиной нужно разместить поле для ввода промокода.


Когда пользователь ввел промокод, делается перерасчет корзины так же, как описано в разделе  расчет скидок и бонусов⁠ , однако теперь в запросе  /v2/calculate-purchase  также передается введенный код.

При оформлении или изменении заказа методом  /v2/set-order  (как описано в  разделе про оформление⁠ ) в запросе также указывается введенный покупателем промокод.

Запрос на расчет с промокодом может завершиться ошибкой. Ошибки, связанные с применением промокода (например, промокод не найден или не выполнены условия для его применения), возвращаются сервером в блоке promocode. Смотрите подробнее в  разделе "обработка ошибок"⁠ .

6. Личный кабинет

Личный кабинет или персональный раздел — это страница сайта, доступная покупателю после авторизации.

6.1. Бонусный счет

Подключая программу лояльности к сайту, в личном кабинете нужно вывести:
  • бонусный счет клиента, то есть, сколько он накопил бонусов;
  • уровень в программе лояльности (если применимо).

Эти данные можно получить из MAXMA.

Backhand Index Pointing Right cм. метод API  /get-balance 


Дополнительно можно вывести:
  • информацию о клиенте, возвращаемую в блоке client;
  • ближайшую дату сгорания бонусов;
  • ссылку на скачивание Wallet-карты (если подключены);
  • сумму накоплений на текущем уровне;
  • оставшуюся сумму до следующего уровня лояльности.

6.2. История бонусов

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

Backhand Index Pointing Right cм. метод API  /get-history 

7. Реферальная программа

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

В личном кабинете для каждого авторизованного покупателя выводится его уникальный реферальный код. Получить его можно из MAXMA выполнив запрос  /issue-promocode .

Backhand Index Pointing Right cм. метод API   /issue-promocode 

Сгенерированный код покупатель передает "другу", а "друг" применяет его в корзине при оформлении заказа точно так же, как и  любой другой промокод⁠ .

8. Промо-страница для программы лояльности

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


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

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

Регистрация

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

Совершение покупки

Покупка под неавторизованным пользователем (если функционал сайта позволяет) — проверить начисление бонусов за покупку; 
Покупка с применением бонусов / Полный выкуп заказа – начисление бонусов;  
Проверить корректность вывода бонусной информации в карточке товара; 
Проверить корректность вывода бонусной информации в корзине заказа:
Проверить корректность вывода бонусной информации в личном кабинете покупателя; 
Провести заказ с применением промокода ( при наличии их в логике программы лояльности )