Общие требования
1. Модуль интеграции реализовывается для взаимодействия интернет-магазинов с системой лояльности Mloyalty, по следующим бизнес-процессам:

- авторизация модуля интеграции в API и сохранение настроек подключения к API

- регистрация клиента интернет-магазина в качестве нового участника программы лояльности

- получение и отображение информации об участнике программы лояльностии его активности

- изменение личных данных участника программы лояльности;

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

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

- возврат заказа участником после его оплаты (полный и частичный возврат)

- отмена заказа участником до его оплаты (полная или частичная отмена);

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

- отправка проверочных смс-кодов


Доп. функционал, по желанию (не входит в основной релиз):

- создание и отправка смс-рассылок

- создание и отправка push-рассылок

- создание и отправка e-mail рассылок

- получение аналитической информации по программе лояльности

- создание и настройка акций

- генерация купонов/промокодов

- генерация электронных подарочных сертификатов



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

- компонент, отвечающий за реализацию взаимодействия с шаблоном и сущностями интернет-магазина
- компонент, отвечающий за реализацию взаимодействия с API

3. Взаимодействие с шаблоном и сущностями интернет-магазина:

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

4. Модуль интеграции должен работать со всеми актуальными конфигурациями/версиям/релизами/редакциями cms интернет-магазинов.

5. Все поощрения системы лояльности должны применяться как скидка к стоимости позиции, а не как уменьшение цены (это принципиально)

6. Ошибки, которые возвращает API системы лояльности, необходимо отображать пользователю, как есть.




ПАНЕЛЬ НАСТРОЕК
После установки модуля интеграции в проект интернет-магазина в административной части управления интернет-магазином должна появиться отдельная страница, на которой будут размещаться типовые и не типовые настройки модуля. Также, необходимо предусмотреть возможность создания дополнительных страниц, на которых будут отображаться аналитические данные из системы лояльности и страницы, на которых будет осуществляться настройка акций/рассылок и других активностей.


Типовые настройки

1. Авторизационные настройки:

- адрес API системы лояльности
- логин пользователя в API системы лояльности
- пароль пользователя API системы лояльности
- максимальное время ожидания ответа от API системы лояльности

2. Настройки формы регистрации

- регистрация с смс-кодом (да/нет)
- регистрация с телефоном друга (да/нет)
- регистрация с промокодом друга (да/нет)

3. Настройки формы авторизации

- авторизация по номеру телефона (да/нет)
правила работы с API
Описание
Работа с токенами
Скриншоты
1. Для вызова метода API требуется отправить к нему POST-запрос по протоколу HTTP.

2. Параметры вызываемых методов API передаются в теле POST-запроса.

3. Для работы с API необходимо пройти авторизацию и получить JWT-токены

4. Пример запроса для вызова метода авторизации (Managerlogin):

- POST/ManagerLogin/HTTP/1.1

- Host: url-адрес веб-сервиса Mloyalty

- Сontent-type: application/x-www-form-urlencoded

- Cache-Control: no-cache

- grant_type=password&username=значение&password=значение

5. В ответ на запрос авторизации получаем JWT-токены:

- Access_token – токен, в котором зашифрована информация о пользователе;

- Token_type – тип токена;

- Expires_in – срок жизни токена;

- Refresh_token – токен обновления авторизация

6. Авторизованный в API пользователь вызывает все другие методы API с использованием access_token

7. Пример запроса авторизованного пользователя:

- POST/наименование метода веб-сервиса/HTTP/1.1

- Host: адрес веб-сервиса Mloyalty

- Сontent-type: application/json

- Authorization: тип токена + токен

- Cache-Control: no-cache


8. Авторизации пользователя обновляется с помощью refresh_token после получения в ответ на очередной запрос ошибки с кодом 401.

9. Пример для вызова метода обновления токена:

- POST/ ManagerLogin/HTTP/1.1

- Host: адрес веб-сервиса Mloyalty

- Content-Type: application/x-www-form-urlencoded

- Cache-Control: no-cache

- grant_type=refresh_token&refresh_token=c4fef608-d2d3-452f-8380-897b73b6b7f3

10. В ответ на запрос обновления токена, получаем новые JWT-токены:

- Access_token – токен, в котором зашифрована информация о пользователе;

- Token_type – тип токена;

- Expires_in – срок жизни токена;

- Refresh_token – токен обновления.

Отправка запроса на авторизацию в API и получение токенов
POST /managerlogin HTTP/1.1
Host: dev.lctest.ru
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache
grant_type=password&username=holikatula&password=holikatula
В случае успешной авторизации получаем JWT-токены (access_token и refresh_token)
{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJodHRwOi8vd3d3LnczLm9yZy8yMDAxLzA0L3htbGRzaWctbW9yZSNobWFjLXNoYTM4NCJ9.eyJyb2xlIjpbIkFuYWx5dGljcyIsIkFuYWx5dGljc0NsaWVudCIsIlNhbGVzIiwiQ2xpZW50cyIsIkNsaWVudHNBbGxDbGllbnRzIiwiVG90YWwiLCJTZW50TWVzc2FnZSIsIlNtc1NlbnRNZXNzYWdlIiwiRXN0aW9zIl0sInVzZXIiOiJlc3Rpb3MiLCJvcGVyIjoiMTIiLCJwYXJ0bmVyIjoiNDEiLCJwb3MiOiIyOTAiLCJwb3Njb2RlIjoiZXN0aW9zIiwicGVybWlzc2lvbmNvZGUiOiJSZWFkV3JpdGVBbGwiLCJpc3MiOiJodHRwOi8vbG9jYWxob3N0LyIsImF1ZCI6IkFueSIsImV4cCI6MTU5MDUxODUzMiwibmJmIjoxNTkwNDAzMzMyfQ.LjnbSQV2H1eiRAMBgI2qYrnwOrr8o-WOwQK3IC_iBK51EwCZx3crC2ukWYV2Z1WZ",
    "token_type": "bearer",
    "expires_in": 115199,
    "refresh_token": "382ae342-8237-455a-a019-a4cdfc7da7b8"
}
Для получения нужных нам данных для работы с API расшифровываем access_token (BASE 64 URL, средняя строка), получаем данные и сохраняем их для дальнейшего использования при вызове методов API.
Ниже пример расшифрованного токена (указаныпараметры, которые нужны в данном контексте)
{
"oper":"4",          // идентификатор оператора, который нужно сохранить 
"partner":"28",     // идентификатор партнера, который нужно сохранить 
"poscode":"HTula1" // идентификатор торговой точки, который нужно сохранить 
}
Как только в ответ на очередной запрос получили код ошибки 401 (это значит срок жизни токена истёк), необходимо получить новый access_token и refresh_token с помощью ранее записанного в настройки refresh_token (получили его из первого запроса на авторизацию)
POST /managerlogin HTTP/1.1
Host: dev.lctest.ru
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache
grant_type=refresh_token&refresh_token=c4fef608-d2d3-452f-8380-897b73b6b7f3
В случае успешного запроса, получаем новые JWT-токены (access_token и refresh_token), сохраняем их и выполняем предыдущий не успешный запрос.
{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJodHRwOi8vd3d3LnczLm9yZy8yMDAxLzA0L3htbGRzaWctbW9yZSNobWFjLXNoYTM4NCJ9.eyJyb2xlIjoidW5rc2l0ZSIsInVzZXIiOiJ1bmtzaXRlIiwib3BlciI6IjMiLCJwYXJ0bmVyIjoiNiIsInBvcyI6IjM2MyIsInBvc2NvZGUiOiJ1bmtzaXRlIiwicGVybWlzc2lvbmNvZGUiOiJSZWFkV3JpdGVBbGwiLCJpc3MiOiJodHRwOi8vbG9jYWxob3N0LyIsImF1ZCI6IkFueSIsImV4cCI6MTU5MDUyMTU3OCwibmJmIjoxNTkwNDA2Mzc4fQ.jJU9j_0aMtgDmHdcnPcMsusH4ZGA2Zk1-EvluzU8DeFBXrIM2XHUfChh-I4X_JZW",
    "token_type": "bearer",
    "expires_in": 115199,
    "refresh_token": "0156a67a-2a1f-4daf-a865-eb8d47c5716c"
}


Скриншоты из Postman
  • Получение токена и авторизация в API (скрин: header + body)
  • Обновление access_token с помощью refresh_token (скрин: header + body)

отправка смс-кода
Для отправки смс-кода вызываем метод dev.lctest.ru/api/client/GetSendVerificationCode
{
  "operator":4,         // идентификатор оператора, из токена
  "poscode": "Htula1", //идентификатор торговой точки, из токена
  "Phone":7777777777 //номер телефона участника программы
   
}
В ответ получаем либо ошибку, текст которой отображаем пользователю, либо 0, что значит "успешно"
{
    "ErrorCode": 0,
    "Message": ""
}
Валидация смс-кода
Для валидации смс-кода вызываем метод dev.lctest.ru/api/client/GetConfirmCode
 {
  "Phone": 7777777777, // номер телефона клиента
  "Code": "4227"      // проверочный код
}
Успешный ответ на вызов метода dev.lctest.ru/api/client/GetConfirmCode
{
    "ErrorCode": 0,
    "Message": ""
}
Регистрация участника
Описание
Json
Скриншоты
1. Регистрация нового участника должна быть возможна двумя способами:

- если это новый клиент для интернет-магазина, то через форму регистрации
- если это существующий клиент интернет-магазина, то через личный кабинет клиента


2. Требования к изменению формы регистрации

- в форме регистрации должны появиться дополнительные поля:

а) номер телефона (в случае если этого поля нет)
б) номер телефона друга (поле отображается или нет, определяется настройками, в панели настроек)
в) номер промокода друга (поле отображается или нет, определяется настройками, в панели настроек)


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

- после подтверждения смс-кода, создаём клиента в интернет-магазине и вызываем метод регистрации нового участника программы в API системы лояльности

Для регистрации нового участника вызываем метод dev.lctest.ru/api/values/ClientCreate
{
"Operator": 4,    //идентификатор оператора, из токена
"Partner": 28,    // идентификатор партнера, из токена
"PosCode": "htula1",  //идентификатор торговой точки, из токена
"Phone": 7777777777, //номер телефона участника
"Card":25200157,  //номер пластиковой карты участника
"Name": "Имя",   //имя участника
"Surname": "Фамилия", //фамилия участника
"Patronymic": "Отчество", //отчество участника
"Email": "ligamin@yandex.ru",   //e-mail участника
"Birthdate": "1990-01-01", // день рождения участника
"AllowSms": 1, //разрешение на коммуникацию по каналу смс; всегда = 1
"AllowEmail": 1, //разрешение на коммуникацию по каналу e-mail; всегда = 1
"AllowPush": 1, //разрешение на коммуникацию по каналу push;  всегда = 1
"Gender": 0, // пол клиента: 1 = мужской, -1 = женский, 0 = не указан
"AgreePersonalData": 1, // разрешение на обработку ПД в системе лояльности; всегда = 1
"FriendPhone":6666666666, // номер телефона друга
"Promocode":123456 // промокод друга
}
В случае не успеха получаем ошибку и отображаем пользователю; в случае успеха получаем и сохраняем идентификатор клиента, номер телефона и номер карты
{
    "ErrorCode": 0, 
    "Message": "",
    "Phone": 7777777777,  // номер телефона зарегистрированного участника
    "Card": 25200157,    // номер карты зарегистрированного участника
    "Client": 97788     // идентификатор зарегистрированного участника
}
Получение информации об участнике
Для получения информации об участнике вызываем метод dev.lctest.ru/api/сlient/сlientinfo
{
    "operator":"4", // идентификатор оператора из токена
    "phone":7777777777 // номер телефона участника
Успешный ответ на вызов метода dev.lctest.ru/api/сlient/сlientinfo
{
    "ErrorCode": 0,
    "Message": "",
    "Card": 25200157,   // номер карты
    "Phone": 7777777777, // номер телефона
    "Surname": "Фамилия", // фамилия
    "Name": "Имя", //имя
    "Patronymic": "Отчество", //отчество
    "Email": "a@mail.ru", //email
    "Birthdate": "2019-11-06T00:00:00",// день рождения
    "LastPurchaseDate": "2020-03-06T15:39:27", //дата последней покупки
    "LastPurchaseAmount": 600.00, // сумма последней покупки
    "AllowSms": true, // разрешение на рассылки по смс
    "AllowEmail": true, // разрешение на рассылки по email
    "FullBalance": 1594.15, // полный баланс бонусов на карте
    "Condition": "5.00%", // уровень поощрения клиента
    "Id": 2,  //идентификатор клиента в системе лояльности
    "Gender": -1, // пол клиента (1 = мужской, -1 = женский, 0 = пол не указан)
    "PhoneValidated": true, //признак провалидированности номера телефона
    "EmailValidated": false, // признак провалидированности email
    "RegDate": "2017-09-05T00:00:00", // дата регистрации в программе лояльности
    "Promocode": "35205304", // персональный промокод, который передаётся друзьям
    "AllowPush": false // разрешение на push-рассылки
}
Обновление данных участника
Для обновление данных участника вызываем метод dev.lctest.ru/api/client/ChangeClient
Передаём в него все имеющиеся параметры (и новые и старые)
{
  "ClientData": {
    "id": 2, // id клиента в БД Оператора
    "password": "honor23", // новый пароль клиента 
    "firstname": "Александр", //новое имя клиента
    "middlename": "Петрович", //новое отчество клиента
    "lastname": "Лигомин", // новая фамилия клиента
    "gender": -1, //новый пол клиента (1=мужской, -1 = женский)
    "birthdate": "2019-09-11", // новый день рождения клиента
    "email": "ra@ml5454oyaдлty.ru", // новый e-mail клиента
    "allowsms": 1, // новые данные о разрешении на рассылку по смс (1 = да; 0 = нет)
    "allowemail": 1, // новые данные о разрешении на рассылки по e-mail (1 = да; 0 = нет)
    "allowpush": 1 // новые данные о разрешении на push-рассылки (1 = да; 0 = нет)
 },
 "Operator": 4
}
Успешный ответ на вызов метода dev.lctest.ru/api/client/ChangeClient
{
    "ErrorCode": 0,
    "Message": ""
}
получение данных по бонусам за покупки участника
Запрос: dev.lctest.ru/api/client/GetCheques
{
  "Operator": 12, // идентификатор оператора, из токена
  "Client": 2, // идентификатор клиента, из бд
  "Page": 1, // от какой записи фильтровать историю; 1= с самой последней
  "PageSize": 10, //по сколько записей от последней возвращать; 10 = 10 чеков
  }

Ответ: dev.lctest.ru/api/client/GetCheques
{
    "ErrorCode": 0,
    "Message": "",
    "PageCount": 0,
    "RecordTotal": 99000,
    "RecordFilterd": 99000,
    "ChequeData": [
          
        {
            "Id": 3329529,
            "Number": "f00002053",
            "Date": "2020-05-21T08:24:04",
            "OperationType": "Покупка",
            "Summ": 71446.00,
            "SummDiscount": 0.0,
            "Bonus": 35723.00,
            "PaidByBonus": 0.0,
            "Discount": 0.00,
            "Partner": "Медоборы",
            "Shop": "pobeda1",
            "CardNumber": 25812893,
            "PosName": "Победа",
            "Phone": 9153992642,
            "Items": [
                {
                    "Name": "Морковный чизкейк",
                    "Code": "N-000011098",
                    "Price": 91.00,
                    "Qty": 440.00,
                    "Amount": 40040.00,
                    "AddedBonus": 20020.00,
                    "RedeemedBonus": 0.00,
                    "Discount": 0.00,
                    "Coupon": "MAY_2020"
                },
                {
                    "Name": "Малиновый чизкейк",
                    "Code": "N-000102416",
                    "Price": 88.00,
                    "Qty": 312.00,
                    "Amount": 27456.00,
                    "AddedBonus": 13728.00,
                    "RedeemedBonus": 0.00,
                    "Discount": 0.00,
                    "Coupon": "MAY_2020"
                },
                {
                    "Name": "Tорт Ай-Петри",
                    "Code": "O-13062 ",
                    "Price": 3950.00,
                    "Qty": 1.00,
                    "Amount": 3950.00,
                    "AddedBonus": 1975.00,
                    "RedeemedBonus": 0.00,
                    "Discount": 0.00,
                    "Coupon": "MAY_2020"
                }
            ]
        },
        {
            "Id": 3329528,
            "Number": "f000002053",
            "Date": "2020-05-21T08:24:04",
            "OperationType": "Покупка",
            "Summ": 71446.00,
            "SummDiscount": 0.0,
            "Bonus": 35723.00,
            "PaidByBonus": 0.0,
            "Discount": 0.00,
            "Partner": "Медоборы",
            "Shop": "pobeda1",
            "CardNumber": 25812893,
            "PosName": "Победа",
            "Phone": 9153992642,
            "Items": [
                {
                    "Name": "Арбуз",
                    "Code": "N-000011098",
                    "Price": 91.00,
                    "Qty": 440.00,
                    "Amount": 40040.00,
                    "AddedBonus": 20020.00,
                    "RedeemedBonus": 0.00,
                    "Discount": 0.00,
                    "Coupon": "MAY_2020"
                },
                {
                    "Name":  "Дыня",
                    "Code": "N-000102416",
                    "Price": 88.00,
                    "Qty": 312.00,
                    "Amount": 27456.00,
                    "AddedBonus": 13728.00,
                    "RedeemedBonus": 0.00,
                    "Discount": 0.00,
                    "Coupon": "MAY_2020"
                },
                {
                    "Name":  "Персик",
                    "Code": "O-13062 ",
                    "Price": 3950.00,
                    "Qty": 1.00,
                    "Amount": 3950.00,
                    "AddedBonus": 1975.00,
                    "RedeemedBonus": 0.00,
                    "Discount": 0.00,
                    "Coupon": "MAY_2020"
                }
            ]
        }
    ]
}
получение данных по бонусам не за покупки участника
Запрос: dev.lctest.ru/api/client/CardBonuses
{
	"operator":4,   //идентификатор из токена
	"card":25812893  // номер карты клиента
}
Ответ: dev.lctest.ru/api/client/CardBonuses
{
    "CardBonuses": [
        {
            "Id": 4556975,
            "Bonus": 150.00,
            "BonusType": "Welcome Bonus",
            "BonusTime": "2020-05-04T13:14:00"
        },
        {
            "Id": 4556976,
            "Bonus": 300.00,
            "BonusType": "Promo Bonus",
            "BonusTime": "2020-05-04T13:14:00"
        },
        {
            "Id": 4556977,
            "Bonus": 300.00,
            "BonusType": "Promo Bonus",
            "BonusTime": "2020-05-04T13:14:00"
        },
       ,
        {
            "Id": 4556974,
            "Bonus": 100.00,
            "BonusType": "Operator Bonus",
            "BonusTime": "2018-07-29T16:12:59"
        }
    ],
    "ErrorCode": 0,
    "Message": ""
}
Расчёт поощрений, которые можно применить к заказу
Заказ без списания бонусов
ЗАКАЗ со списанием бонусов
ВОзврат заказа
Отмена заказа
начисление бонусов за отзыв
Made on
Tilda