Skip to main content

Интеграция Касса - Лояльность

Задание на реализацию обмена данных между Кассовой системой и АВМ Loyalty

Суть задачи - организовать регулярный автоматический (без участия человека) обмен данными между кассовой системой Клиента и системой лояльности АВМ Loyalty.

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

В систему АВМ Loyalty передаются все транзакции, как идентифицированные, так и неидентифицированные.

Обмен данными между кассовой системой и системой АВМ Loyalty должен быть реализован в двух режимах:

  • Online - взаимодействие кассы и системы АВМ Loyalty происходит в режиме реального времен)
  • Offline- в случае невозможности взаимодействия кассы и системы АВМ Loyalty в онлайн режиме(например отсутствие интернет соединение) касса должна записывать транзакции в очередь с номерами карт (проверяя их по маске)и при восстановлении соединения с АВМ Loyalty передавать их. Если при отправке транзакции из очереди в систему лояльности, система лояльности возвращает ошибку, что карта не найдена, запрос отправляется повторно, как неидентифицированная покупка.

Данные передаются методами RESTful API по протоколу https.

Для взаимодействия кассы и Лояльности используются методы API:

POST /partner/operation/user/registration – регистрирует нового участника программы лояльности;

GET /partner/operation/user/{token}/card-user-info - отдаёт информацию о статусе карты и держателе этой карты, если карта присвоена к счету;

POST /partner/card/card-update - используется для изменения статуса карты на кассе;

POST /partner/operation/pre-check - предрасчёт по чеку;

POST /partner/operation/check-confirm - запрос подтверждения продажи;

POST /partner/operation/check-return – запрос на возврат;

Операции продажи:

Перечень операций продаж на кассе:

  1. Режим online - когда есть непрерывный доступ к сети Internet
    1. Покупка товара 
    2. Возврат товара (полный, частичный, повторный)
  2. Режим offline - нет доступа к сети Internet - данные по продаже не могут отправиться в CRM Лояльности непосредственно во время продажи. 

Порядок выполнения операций продажи:

Карт-юзер-инф

  1. Получить ответ предрасчета POST /v2/partner/operation/pre-check.
  2. Вывести сообщение сколько можно списать бонусов за этот чек, если можно списать бонусы - значение из параметра "receipt_bonus_amount": С вопросом списать ли бонусы (Ответ Да, и Ответ Нет).
  3. Если Ответ Да. Вывести поле для ввода количества к списанию, при этом отображать максимальное допустимое количество к списанию. Если пользователь ввел сумму бонусов больше, чем допустимая - выдавать соответствующее сообщение и не отправлять данные. Добавить кнопку после ввода - Отправить (выполнить второй предрасчет POST /v2/partner/operation/pre-check) и Отмена - не списывать бонусы (вывести сумму к оплате на чек и количество начисленных бонусов попозиционно и общее количество на чек) При нажатии отправить вывести сумму к оплате на чек и количество начисленных и списанных бонусов попозиционно и общее количество на чек).
  4. Если Ответ Нет вывести сумму к оплате на чек и количество начисленных бонусов попозиционно и общее количество.
  5. После введения суммы к оплате - подтверждение операции продажи POST    /v2/partner/operation/check-confirm

При любых изменениях в продажи - посылать запрос POST /v2/partner/operation/pre-check

Описание методов так же доступно по ссылке:

канал API:    https://api.sandbox.abmloyalty.app

ключ (токен):

версия: v2

тип авторизации: Basic Authentication (можно использовать поле имени пользователя как токен(ключ) доступа и пропустить пароль)

ключ:

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

Описание всех методов доступно по ссылке:

https://documenter.getpostman.com/view/10073265/TzJuAdf5

Регистрация нового участника программы лояльности(ПЛ) на кассе

Запрос на регистрацию нового участника ПЛ (без верификации по смс)

POST /partner/operation/user/registration

  • Создает новый счет в системе, заполняет анкету нового участника программы.
  • В параметрах необходимо передать анкетные данные клиента.
    Обязательными параметрами являются те поля анкеты, которые установлены как обязательны к заполнению (в данном примере 5 параметров).
  • Метод возвращает телефон и guid нового, созданного в системе участника программы лояльности.
Название

Тип данных

Описание

Соответствует значению у Клиента

phone

string

Номер мобильного телефона в формате 380#########

  

first_name

integer

Имя участника ПЛ

middle_name

string

Отчество участника ПЛ

  

last_name

string

Фамилия участника ПЛ

  

birth_day

string

Дата рождения участника ПЛ в формате 1989-03-17

  

id_region

integer

Глобальный справочник региона проживания

  

id_city

integer

Глобальный справочник города проживания, связан с регионом.

gender

integer

Пол:

1 - мужчина

2- женщина

  

sms_notify

integer

Подписаться на смс рассылку:

1-Согласен

0-Не согласен

  

email_notify

integer

Подписаться на email рассылку:

1-Согласен

0-Не согласен

  

email

string

Электронная почта в формате abm@abmcloud.com

  

address

string

Адрес участника ПЛ

  

channel_reg

integer

Канал регистрации. Для кассы: 5.

  

Пример ответа, при успешном запросе:

{

"success": true,

"status": 201,

"data": {

"phone": "380931000013",

"guid": "68c147a2-edbd-4df5-a8b2-dadfb3a70ebc",

}

}

Регистрация участника ПЛ (с верификацией по смс)
      1. Регистрация с смс при наличии карты
        1. Проверка номера карты

Метод проверяет есть ли такая карта в программе лояльности, если карта есть в параметре availability возвращается 1, если не карты нет-0.

GET /client/card/{number}/availability

Название

Тип данных

Описание

Соответствует значению у Клиента

number

string

Номер карты участника ПЛ

  
  • Запрос списка обязательных полей

GET /client/profile-params – возвращает список полей основной анкеты и их обязательность к заполнению. 

  • Запрос списка дополнительных полей

GET /system/profile-fields- возвращает список дополнительных полей анкеты и их обязательность к заполнению.

  • Запрос списка регионов

GET /v2/client/geo/{country}/regions - возвращает все регионы и их ID

{country} - ID страны

  • Запрос списка городов

GET /v2/client/geo/{country}/{city}/search-city - поиск по части названия города, возвращает города (регионы, страны) заданной country, max = 10шт

{country} - ID страны

{city} - часть названия города

{country} - ID страны прописать в запросе по умолчанию и не выводить в интерфейс пользователя для выбора.

Например, ID страны Казахстан = 81

  • Проверка номера телефона участника

POST /v2/client/check-phone – метод проверяет есть ли этот номер телефона уже в программе лояльности, если есть, то в параметр is_exist в ответ приходит true, если нет-false.

Название

Тип данных

Описание

Соответствует значению у Клиента

phone

string

Номер мобильного телефона в формате 380#########

  
  • Регистрация с смс

POST /v2.1/client/registration – метод регистрирует номер телефона и отправляет на номер смс с кодом подтверждения

Название

Тип данных

Описание

Соответствует значению у Клиента

phone

string

Номер мобильного телефона в формате 380#########

  

password

string

Постоянный пароль, можно вносить стандартный 111111

  
  • Подтверждение регистрации паролем с смс

POST /v2.1/client/registration-confirm -метод отправляет код с смс и подтверждает регистрацию

Название

Тип данных

Описание

Соответствует значению у Клиента

code

string

Код с смс

  

sms_id

integer

Id sms, получен в предыдущем запросе

  
  • Присвоение карты пользователю

POST /v2/client/card/set-card – метод присваивает указанный номер карты участнику(по токену)

Название

Тип данных

Описание

Соответствует значению у Клиента

number

string

Номер карты участника ПЛ

  
  • Генерация виртуальной карты (в случае, если пластик не выдается на кассе)

GET /v2/client/card/generate-card – метод генерирует виртуальную карту участнику ПЛ (по токену)

  • Отправка анкетных данных

PUT /v2/client /profile– метод присваивает указанные данные участнику(по токену)

Название

Тип данных

Описание

Соответствует значению у Клиента

first_name

integer

Имя участника ПЛ

  

middle_name

string

Отчество участника ПЛ

  

last_name

string

Фамилия участника ПЛ

  

birth_day

string

Дата рождения участника ПЛ в формате 1989-03-17

  

id_region

integer

Глобальный справочник региона проживания

  

id_city

integer

Глобальный справочник города проживания, связан с регионом.

gender

integer

Пол:

1 - мужчина

2- женщина

  

email

string

Электронная почта в формате abm@abmcloud.com

  

sms_subscribe

integer

Подписаться на смс рассылку:

1-Согласен

0-Не согласен

  

email_subscribe

integer

Подписаться на email рассылку:

1-Согласен

0-Не согласен

  

childrens

integer

Количество детей:

0-no children;

1-1;

2-2;

3-3;

4- more 3;

  

channel_reg

integer

Канал регистрации. Для кассы: 5.

  

family_stat

integer

Семейное положение:

0- undefined;

1- maried;

2 - single,

  

has_auto

integer

Наличие автомобиля:

0 - undefined;

1 -no auto;

2 - passenger car;

3 - minibus;

4 - freight car;

5 -other car,

  

work_status

integer

Вид занятости:

0 - undefined;

1 - businessman;

2 - goverment official;

3 - office worker;

4 - student;

5 - pensioner;

6 - housewife;

7 - other ,

  

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

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

GET /partner/operation/user/{token}/card-user-info

{token} - номер карты по которой запрашивается инфо

Метод возвращает инфо по карте + инфо по участнику ПЛ, если карта привязана к счету.

Пример ответа, при успешном запросе:

{

    "success": true,

    "status": 200,

    "data": {

        "token": "63", //Номер карты

        "user_data": {

            "guid": "533a7a29-6928-4aad-a1b3-051bb1717af4",

            "mobile": "380631024903", // номер телефона

            "email": "Alyonahavrylenko@gmail.com", // email-адрес

            "first_name": "Helen", //имя

            "middle_name": "", //Отчество

            "last_name": "Guru", //Фамилия

            "created": 1578488728, // дата регистрации;

            "birth_day": "1999-08-08",//Дата рождения

            "gender": 2, //Пол

            "sms_notify": 1, // согласие на sms-рассылку (0 - не согласен; 1 - согласен);

            "email_notify": 1, //согласие на email -рассылку (0 - не согласен; 1 - согласен);

            "id_region": 86, //id региона

            "id_city": 1116, //id города

            "address": "Peremogy Avenu 12",// Адрес

            "blocked": 0 //Количество блокировок участника

        },

        "user_status": [],

        "profile": {

            "work_status": 3,

            "children": 0,

            "has_auto": 1,

            "family_stat": 2

        },

        "accounts_data": [

            {

                "account": 2620020401, // номер кошелька;

                "currency": "BON", // название валюты лояльности;

                "balance": 0, // количество бонусов на счету;

                "avialable": 0 // количество доступных бонусов на счету;

            }

        ],

        "cards_data": [

            {

                "number": "2020000000259", // номер карты;

                "status": 3, // статус карты (0 - новая; 1 - не заполнена; 2 - заблокирована; 3 - платежная);

                "created": 1579167842, // дата создания карты (генерации);

                "date_activated": 1580741547, // дата активации (дата первой операции по карте или дата привязки карты к кошельку);

                "issue_date": null, // дата выдачи карты;

                "issue_branch": null, // торговая точка в которой выдана карта;

                "date_blocked": 0, // дата перевода карты в статус "заблокирована";

                "type": 1 // тип карты (1 - основная карта, 2 - брелок);

            },

            {

                "number": "63",

                "status": 3,

                "created": 1579166828,

                "date_activated": 1579178912,

                "issue_date": null,

                "issue_branch": null,

                "date_blocked": 0,

                "type": 1

            },

            {

                "number": "67",

                "status": 2,

                "created": 1579166828,

                "date_activated": 1579167114,

                "issue_date": null,

                "issue_branch": null,

                "date_blocked": 1579167187,

                "type": 1

            },

            {

                "number": "2020-80477",

                "status": 3,

                "created": 1578498242,

                "date_activated": 1578910691,

                "issue_date": null,

                "issue_branch": null,

                "date_blocked": 0,

                "type": 1

            }

        ],

        "gift_bonuses": [ //Информация по подарочным бонусам

            {

                "id": 268, //ID операции

                "name": "For books",//Название начисления

                "bonus": 1000, //Количество начисленных бонусов

                "opened_at": 1581948299 //Дата активации бонусов

            }

        ],

        "card_statuses": {

            "0": "New",

            "1": "Active",

            "3": "Payment",

            "2": "Blocked"

        },

        "card_types": {

            "1": "Main",

            "2": "Slave"

        },

        "total_amount_spent": 13398 // общая сумма покупок участника.   

"groups": [ //список групп, в который участвует УПЛ

"Кайбылдаева",

"0555409355",

"фильтр",

"Чуй обл группа рассылки",

"testoce2",

"All clients",

"омурбеков тест2",

"Тест 2",

"Горобец М, два магазина, квартал",

"Мужчины все ",

"Кроме 996701037770",

"Гавриленко тест",

"Иван Иванов",

"мужчины от 20 до 30",

"тест титан",

"Для рассылки Пуш",

"\t0000001433663",

"0684607869",

"Для_Задания_2",

"Титан мужчины 2 магазина",

"Лекарь тест",

"Женщины за рулем ",

"Чуй конструктор",

"Титан все клиенты",

"Лаки Лук 1",

"1010109147909",

"Ж 20-30, МП_Горобец",

"мужчины по заданию",

"Печенье весовое",

"мужчины до 30",

"Валерия",

"5% скидка"

]

 }

}

Рекомендация:

Если в ответе получили статус карты "2": "Blocked", то проводить продажу как неидентифицированному покупателю (в пречеке не передавать номер карты)

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

GET /partner/operation/user/{type}/{token}/user-info

{type} - card или phone

{token} - если {type} - card, то заполнять значением номеру карты, если {type} -  phone, то заполнять значением номера телефона участника ПЛ

Пример ответа, при успешном запросе:

{

    "success": true,

    "status": 200,

    "data": {

        "token": "63", //Номер карты

        "user_data": {

            "guid": "533a7a29-6928-4aad-a1b3-051bb1717af4",

            "mobile": "380631024903", // номер телефона

            "email": "Alyonahavrylenko@gmail.com", // email-адрес

            "first_name": "Helen", //имя

            "middle_name": "", //Отчество

            "last_name": "Guru", //Фамилия

            "created": 1578488728, // дата регистрации;

            "birth_day": "1999-08-08",//Дата рождения

            "gender": 2, //Пол

            "sms_notify": 1, // согласие на sms-рассылку (0 - не согласен; 1 - согласен);

            "email_notify": 1, //согласие на email -рассылку (0 - не согласен; 1 - согласен);

            "id_region": 86, //id региона

            "id_city": 1116, //id города

            "address": "Peremogy Avenu 12",// Адрес

            "blocked": 0 //Количество блокировок участника

        },

        "user_status": [],

        "profile": {

            "work_status": 3,

            "children": 0,

            "has_auto": 1,

            "family_stat": 2

        },

        "accounts_data": [

            {

                "account": 2620020401, // номер кошелька;

                "currency": "BON", // название валюты лояльности;

                "balance": 0, // количество бонусов на счету;

                "avialable": 0 // количество доступных бонусов на счету;

            }

        ],

        "cards_data": [

            {

                "number": "2020000000259", // номер карты;

                "status": 3, // статус карты (0 - новая; 1 - не заполнена; 2 - заблокирована; 3 - платежная);

                "created": 1579167842, // дата создания карты (генерации);

                "date_activated": 1580741547, // дата активации (дата первой операции по карте или дата привязки карты к кошельку);

                "issue_date": null, // дата выдачи карты;

                "issue_branch": null, // торговая точка в которой выдана карта;

                "date_blocked": 0, // дата перевода карты в статус "заблокирована";

                "type": 1 // тип карты (1 - основная карта, 2 - брелок);

            },

            {

                "number": "63",

                "status": 3,

                "created": 1579166828,

                "date_activated": 1579178912,

                "issue_date": null,

                "issue_branch": null,

                "date_blocked": 0,

                "type": 1

            },

            {

                "number": "67",

                "status": 2,

                "created": 1579166828,

                "date_activated": 1579167114,

                "issue_date": null,

                "issue_branch": null,

                "date_blocked": 1579167187,

                "type": 1

            },

            {

                "number": "2020-80477",

                "status": 3,

                "created": 1578498242,

                "date_activated": 1578910691,

                "issue_date": null,

                "issue_branch": null,

                "date_blocked": 0,

                "type": 1

            }

        ],

        "gift_bonuses": [ //Информация по подарочным бонусам

            {

                "id": 268, //ID операции

                "name": "For books",//Название начисления

                "bonus": 1000, //Количество начисленных бонусов

                "opened_at": 1581948299 //Дата активации бонусов

            }

        ],

        "card_statuses": {

            "0": "New",

            "1": "Active",

            "3": "Payment",

            "2": "Blocked"

        },

        "card_types": {

            "1": "Main",

            "2": "Slave"

        },

        "total_amount_spent": 13398 // общая сумма покупок участника.    }

}

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

PUT /partner/operation/user/{type}/{token}/user-info

Название

Тип данных

Описание

Соответствует значению у Клиента

phone

string

Номер мобильного телефона в формате 380#########

  

first_name

string

Имя участника ПЛ

middle_name

string

Отчество участника ПЛ

  

last_name

string

Фамилия участника ПЛ

  

birth_day

string

Дата рождения участника ПЛ в формате 1989-03-17

  

id_region

integer

Глобальный справочник региона проживания

  

id_city

integer

Глобальный справочник города проживания, связан с регионом.

gender

integer

Пол:

1 - мужчина

2- женщина

  

sms_notify

integer

Подписаться на смс рассылку:

1-Согласен

0-Не согласен

  

email_notify

integer

Подписаться на email рассылку:

1-Согласен

0-Не согласен

  

email

string

Электронная почта в формате abm@abmcloud.com

  

Пример ответа, при успешном запросе:

{

"success": true,

"status": 200,

"data": {

"guid": "77f8f2d6-afad-4123-bd52-0db68df28e74",

"mobile": "380931000013",

"email": "titkin1@ua-2.com",

"first_name": "Artur",

"middle_name": "Ivanovich",

"last_name": "Titkin",

"created": 1521451738,//Дата создания

"birth_day": "1979-04-28",

"gender": "2",

"sms_notify": "0",

"email_notify": "0",

"id_region": "91",

"id_city": "1586",

"blocked": 1 //Количество блокировок карты

}

}

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

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

GET /partner/operation/user/{token}/card-user-info

{token} - номер карты по которой запрашивается инфо

Метод возвращает инфо по карте + инфо по участнику ПЛ, если карта привязана к счету.

Пример ответа, при успешном запросе представлен в разделе Информация о участнике программы лояльности.

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

GET /partner/operation/card/{token}/card-info

{token} - номер карты по которой запрашивается инфо

Метод возвращает инфо по карте

Пример ответа, при успешном запросе представлен в разделе Информация о участнике программы лояльности.

{

"success": true,

"status": 200,

"data": {

"token": "2208801711684",// Номер карты

"card_data": {

"number": "2208801711684",// Номер карты

"status": 0, //Статус карты

"created": 1563365120,// Дата создания(генерации карты в системе)

"date_activated": 0,// Дата активации карты(перехода карты в статус "Не заполнена")

"date_blocked": 0,// Дата блокировки карты( переда карты в статус "Заблокирована")

"user_guid": "Not found",// Guid участника программы которому принадлежит карта

"type": 1,// Тип карты (1-основная, 2-брелок)

"main_card_number": "", // Номер основной карты если есть карты брилоки

"slave_card_number": "", // Номер карты брилока если есть.

"card_guid": null,// GUID самой катрты

"issue_date": null,// Дата выдачи карты участнику программы

"issue_branch": null// Магазин выдачи карты участнику программы

},

"statuses": { // Статусы карт

"0": "New",// Новая (карта не имеет бонусного счета, при первой продаже на такую карту она автоматически перейдет в статус )

"1": "Active", //Карта имеет бонусный счет, но еще не зарегистрирована полностью. Может только накапливать бонусы, но не списывать

"2": "Blocked", // Заблокированная. Не может ни накапливать ни списывать бонусы.

"3": "Payment" // Платежная. Может накапливать и списывать бонусы.

},

"types": { //Типы карт:

"1": "Main",// Основная

"2": "Slave"// Карта брилок привязанная к основной карте.

}

}

}

Изменение статуса карты на кассе

Запрос обновляет данные карты:

  • Устанавливает/изменяет статус карты;
  • Устанавливает/изменяет дату выдачи;
  • Устанавливает/изменяет точку выдачи;
  • Присваивает карту существующему участнику программы.

POST     /v2/partner/card/card-update

Перечень параметров в запросе:

Название

Тип данных

Описание

Соответствует значению у Клиента

card_issue_branch

string

Код торговой точке, где выдали карту

  

card_issue_date

integer

Дата и время выдачи карты, передаётся в формате unix time

card_number

string

Номер карты участника ПЛ, по которой обновляются данные

  

card_status

integer

Статусы карты:

1 - Активная/ Новая

2 - Заблокирована

3 - Платежная

  

user_card

string

Номер карты участника ПЛ

Используется для привязки доп карты

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

user_phone

string

Номер телефона участника ПЛ к которому будет привязана карта, указанная в параметре card_number

Пример ответа, при успешном запросе:

{

"success": true,

"status": 200,

"data": {

"card_number": "10000009"

}}

Продажа

Запросить предрасчет по чеку

POST /v2/partner/operation/pre-check

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

Данные полученные в pre-check нужно кешировать для дальнейшей печать чека и отправки данных о продажах в учетную систему клиента.

Данные параметра meta в receipt_details соответствуют значением товара описание деталей  клиент .

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

В запросе необходимо заполнять существующий параметр "coupon"

Перечень параметров в запросе:

Название

Тип данных

Описание

Соответствует значению у Клиента

branch_id

string

Код (id) торговой точки

Предварительно должен быть создан в CRM Лояльности

  

card

integer

Номер карты участника ПЛ

  

coupon

string

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

  

offline

boolean

Определяет режим проведения операции : 1 - офлайн, 0-онлайн

Списать бонусы в режиме офлайн невозможно

  

operator_id

string

Код кассира

Предварительно должен быть создан в CRM Лояльности

  

phone

string

Номер телефона участника ПЛ

  

receipt_bonus_amount

number

Количество бонусов за чек, которые покупатель хочет списать.

  

receipt_currency

string

Валюта бонусов

Передавать значение BON

receipt_datetime

Integer (тип: 1470825537)

Дата и время покупки по UTC (GMT) в формате UNIX time

  

receipt_description

string

Описание типа покупки

Звичайний продаж 

receipt_details

string

Детали покупки (полный список товаров и их свойства в квитанции) в виде массива JSON. «position» - позиция в чеке. "prod_cat" - код группы товаров. «prod_code» - код SKU. «prod_name» - полное название продукта. «prod_price» - цена товара. "prod_amount" - количество товара. «prod_sum» - общая стоимость продукта (обычно равна prod_amount * prod_price), 

“bonus_restrict”:true -  исключить позицию с начисления и списания бонусов,

“bonus_accrual_restrict”:true - исключить позицию с начисления бонусов

“discount_restrict”:true - исключить позицию со списания бонусов, external_discount - размер ( в деньгах) внешней скидки

"meta":"{\"параметр1\":\"значение\", \"параметр2\":\"значение\"}"

  

session_id

integer

Код сессии

  

terminal_id

string

Код кассы

  

variables

string

Доп. св-тва товара в виде массива JSON Пример: {"key1":1, "key2":1}

  

Важно!!!:

1.bonus_restrict - Если товар продается по акции, настроенной в учетной или кассовой системе, передавать 1 в параметр bonus_restrict, чтобы механики лояльности по данному товару не срабатывали.В остальных позициях этот параметр не передавать.

2. Если на продукт срабатывает скидка, бонусы на этот продукт не начисляются и не списываются.

Пример ответа, при успешном запросе (значение в параметре "pre_check_id" необходимо сохранить, для передачи в операции подтверждения продажи )

{

"success": true,

"status": 201,

"data": {

"pre_check": {

"pre_check_id": "1548149007.104900.03",// id который необходимо будет подтвердить методом check-confirm

"payment": {

"money": 899.03, // "чистая"сумма к оплате (сколько денег необходимо заплатить пользователю, за вычетом дисконтных и бонусных скидок

"bonus_redeemed": 1, // сколько бонусов использовано на оплату покупки

"discount": 0// размер скидки в деньгах

},

"currency": "BON",// валюта начисления бонусов

"coupon": [

{

"code": "3863NUM6",

"success": false,

"message": "Coupon configuration is not active"

},

{

"code": "6556PRE",//номер купона

"success": true,

"message": "",

"reward_type": "1"

}

], // купон использованный с этим чеком

"branch_id": "001", // id торговой точки

"terminal_id": "terminal_1",// id кассы

"operator_id": "operator_1",// id кассыра

"session_id": null, // id сессии

"receipt_amount": 900.03, // полная сумма чека

"payment_bonus": 63.86, // всего бонусов начислено по чеку

"base_bonus": 63.86, //размер базового бонуса (кэшбэк)

"receipt_description": "Precheck test",// описание чека

"birthday_bonus": 0, // бонус в день рождения

"userStatusFixBonus": 0, // бонус за статус (только фиксированная сумма вознаграждения, не %)

"receipt_details": [

{

"position": 1, // номер позиции в чеке

"prod_cat": "20316",// категория продукта (если товара нет в CRM, то возвращается как "0")

"prod_code": "13997",// sku продукта

"prod_name": "КОНФ ВЕСОВЫЕ АССОРТИ",// название продукта (если товара нет в CRM, то возвращается как "no name product")

"prod_price": "100.01",// цена продукта

"prod_amount": "3",// количество продукта(шт.)

"prod_sum": 300.03, // общая стоимость по позиции продукта

"bonus_restrict": "ok",

"discount_limit": 300.03, // максимально возможная скидка на позицию

"discount": 0, // размер примененной скидки на позицию

"parameters": [],// дополнительные параметры позиции, установленные в настройках товаров(цена, мрц, ограничения по начислению и списанию бонусов)

"discount_success": [],// информация по успешно примененным дисконтным акциям

"discount_bonus": 0, // размер скидки предоставленный бонусами в деньгах

"bonus": 0, // количество бонусов начисленных на позицию

"bonus_success": []// подробная информация по бонусным начислениям на позицию

},

{

"position": 2,

"prod_cat": "20316",

"prod_code": "86163",

"prod_name": "Tekila Patron silver 0.5",

"prod_price": "100",

"prod_amount": "2",

"prod_sum": 200,

"discount_limit": 0,

"discount": 0,

"parameters": {

"price": 100,

"mrp": null,

"discount": 0,

"max_calculation_bonus": 4,

"max_payment_bonus": 0

},

"discount_success": [ // подробная информация по скидкам на позицию

{

"rule": "coupon",// тип начисления, купон

"action_id": 0, // id акции (для начисления по акции)

"action_title": "",//название акции

"info": "6556PRE",

"discount": 7.11, // размер скидки в деньгах

"priority": 1// приоритет акции

}

],

"discount_bonus": 0,

"bonus": 4,

"bonus_success": [

{

"rule": "cashback",

"action_id": 0,

"action_title": "",

"bonus": 4,

"priority": 999998

}

]

},

{

"position": 3,

"prod_cat": "20316",

"prod_code": "77765",

"prod_name": "ПАКЕТ МАЙКА ФИРМЕННЫЙ ЕЛИСЕЙ 12КГ",

"prod_price": "100",

"prod_amount": "2",

"prod_sum": 200,

"discount_limit": 200,

"discount": 0,

"parameters": [],

"discount_success": [],

"discount_bonus": 0.5,

"bonus": 29.93,

"bonus_success": [

{

"rule": "cashback",

"action_id": 0,

"action_title": "",

"bonus": 29.93,

"priority": 999998

}

]

},

{

"position": 4,

"prod_cat": "20316",

"prod_code": "13997",

"prod_name": "КОНФ ВЕСОВЫЕ АССОРТИ",

"prod_price": "100",

"prod_amount": "2",

"prod_sum": 200,

"discount_limit": 200,

"discount": 0,

"parameters": {

"price": 100,

"mrp": 95,

"discount": 0,

"max_calculation_bonus": 200,

"max_payment_bonus": 200

},

"discount_success": [],

"discount_bonus": 0.5,

"bonus": 29.93,

"bonus_success": [

{

"rule": "cashback",

"action_id": 0,

"action_title": "",

"bonus": 29.93,

"priority": 999998

}

]

}

],

"sms_id": 6756, // данный параметр приходи только после настройке в системе АБМ - подтверждение списания по смс

"max_payment_bonus_check": 2264.5, // максимальное количество бонусов для списания(в бонусах)

"max_payment_money_check": 226.45, // максимальное количество бонусов для списания(в денежной единице с коэффициентом перевода 1 бонус=10 копеек, у вас он может отличаться)

"balance_available": 100 , //доступно бонусов на счету в участника ПЛ

"discount_fail": [],//информация по не примененным дисконтным акциям (акция активна, но в чеке не соблюдено условие для ее работы)

"bonus_fail": []//информация по не примененным бонусным акциям

}

}

}

Рекомендация:

- полученные в ответе на pre_check параметры "max_payment_bonus_check" и

- "balance_available" выводить на кассе минимальное из них, как «Максимально возможное количество бонусов для списания:»

- "sms_id": 6756, - идентификатор смс подтверждения списания бонусов по коду с смс

- pre_check_id - действителен 10 дней

Примеры ответов от АБМ при использовании купонов в чеке:

Пример ответа от лояльности

Значение

"coupon": [

{

"code": "1000896246",

"success": true,

"message": "",

"template_name": "Купон на бонус Titan",

"reward_type": 0

}

]

Данный купон действителен и его можно применить в данном чеке

"coupon": [

{

"code": "1000110027",

"success": false,

"message": "Coupon redeemed"

}

]

Данный купон уже погашен

"coupon": [

{

"code": "1000358936",

"success": false,

"message": "Coupon configuration is not active"

}

]

Срок действия указанного купона истек

"coupon": [

{

"code": "1000303888",

"success": false,

"message": "Wrong user",

"template_name": "Купон на скидку"

}

]

Данный купон не принадлежит указанному пользователю

"coupon": [

{

"code": "1000572007",

"success": false,

"message": "Coupon is out of date"

}

]

Срок действия указанного купона еще не наступил

"coupon":[

{

"code":"CUP20416079",

"success":false,

"message":"Condition Order sum is not met"

}

]

Условия купона по сумме чека не выполнены (сумма чека меньше, чем задано в условиях купона)
Запрос на подтверждение продажи

POST    /v2/partner/operation/check-confirm

  • подтверждает проведение чека, списания и начисления бонусов ( pre_check_id - действителен 10 дней)
  • применяет купон (ставит отметку об использовании)

Перечень параметров в запросе:

Название

Тип данных

Описание

Соответствует значению у Клиента

box

number

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

  

check_number

integer

Номер чека

Код операции продажи. При формировании должен быть уникальным в разрезе партнера

Формат:

Номер_чека_+_Дата_покупки

payment_type

string

Массив с типами оплат. Пример: [{"type":1,"sum":899},{"type":2,"sum":0.00}]

  

pre_check_id

string

Код (ID) операции полученній в ответе на запрос POST /v2/partner/operation/pre-check

  

sms_id

integer

Идентификатор смс при списании бонусов

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

code

integer

Код с смс отправленное покупателю

Пример ответа, при успешном запросе

{

"success": true,

"status": 201,

"data": {

"pre_check_id": "1548149007.104900.03", // идентификатор подтвержденного чека

"check_number": "100110", // номер чека, переданный кассой

"box_bonus": 0.07, // бонусы переданные в копилку

"bonus_accrued": 63.93, // начисленные бонусы

"bonus_redeemed": 1, // списанные бонусы, в счет оплаты

"bonus_balance": 288, // баланс бонусов у пользователя после оплаты чека

"c2b_result": { // информация по операции списания

"success": true, // статус операции

"errorDescription": "", // описание в случае ошибки

"processing_transaction_datetime": 1548150560, // время операции в unixtime

"c2b_check_number": "C2B-100110" // id операции

},

"b2c_result": { // информация по операции списания

"success": true, // статус операции

"errorDescription": "", // описание в случае ошибки

"processing_transaction_datetime": 1548150560, // время операции в unixtime

"b2c_check_number": "B2C-100110" // id операции

},

"coupon": [ // информация по купонам

{

"code": "6067PRECHECK",

"success": true,

"message": "",

"options": {

"received_discount": "16.85",

"redemption_count": 1

},

"reward_type": "1"

}

]

}

}

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

POST /partner/operation/check-return

Перечень параметров в запросе:

Название

Тип данных

Описание

Соответствует значению у Клиента

branch_id

string

Код (id) торговой точки

  

check_number

string

Номер чека возврата

  

operator_id

number

Код кассира

  

return_check_number

string

Номер продажи (чека), которая подлежит возврату

  

return_datetime

integer (тип: 1550478564)

Дата и время возврата

  

return_details

string

Перечень кодов товаров и их количества, которые подлежат возврату. Пример: [{"prod_code":"139974","prod_amount":1}]

  

terminal_id

number

Код кассы

  

Пример ответа, при успешном запросе

#Response for loyalty program particiiant

{

"success": true,

"status": 201,

"data": {

"return_check_number": "471", // номер чека продажи из которого сделан возврат

"check_number": "4587", // номер чека возврата

"branch_id": "001", // id торговой точки

"terminal_id": null, // id кассы

"operator_id": null, // id кассира

"b2c_returned": 15, // количество бонусов возвращенных на счет партнера

"b2c_transaction_id": 471, // id транзакции возврата бонусов на счет партнера

"c2b_returned": 0.5, // количество бонусов возвращенных на счет клиента

"c2b_transaction_id": 470, // id транзакции возврата бонусов на счет клиента

"message": "b2c - all bonuses cleared" // сообщение о возвращаемых бонусах на счет партнера (удалось ли вернуть бонусы, если да, то все бонусы или только часть)

}

}

#Response for anonymous client

{

"success": true,

"status": 201,

"data": {

"return_check_number": "CN-1570437820-db", // номер чека продажи из которого сделан возврат

"check_number": "CN-1570437820-ret", // номер чека возврата

"branch_id": "1", // id торговой точки

"terminal_id": null, // id кассы

"operator_id": null, // id кассира

"b2c_returned": 0, // количество бонусов возвращенных на счет партнера

"b2c_transaction_id": null, // id транзакции возврата бонусов на счет партнера

"c2b_returned": 0, // количество бонусов возвращенных на счет клиента

"c2b_transaction_id": null, // id транзакции возврата бонусов на счет клиента

"message": "Does not require transaction execution" // сообщение о возвращаемых бонусах на счет партнера (удалось ли вернуть бонусы, если да, то все бонусы или только часть)

}

}

Режим offline

Если нет возможности отправить данные в CRM Лояльности, то необходимо хранить эти данные в отдельном хранилище и выгрузить их по регламенту рекомендуется 1 - 2 раза в сутки

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

Выводить на кассу в каком состоянии находится касса – онлайн/оффлайн – списание бонусов невозможно.

Перечень операций в режиме offline

- операции продажи

Данные по продажам анонимных покупателей и участников ПЛ накапливаются на кассе, при доступе к лояльности отправляются данные о покупке и начисленным бонусам. Списать бонусы в режиме офлайн невозможно – выводить на кассу диалоговое окно: «Касса находиться в offline режиме. Списание бонусов невозможно.».В методе

POST /v2/partner/operation/pre-check передавать в параметр offline – 1(офлайн), далее применить метод POST    /v2/partner/operation/check-confirm

- операции возврата 

Данные по возвратам анонимных покупателей и участников ПЛ накапливаются на кассе, при доступе к лояльности отправляются данные о возврате со списанием начисленных бонусов и начислении списанных бонусов.

POST /partner/operation/check-return

Рекомендация

Для возможности идентифицировать транзакцию offline в отчетах системы, рекомендуем к номеру чека добавлять слово ”off”.

Пример для POST    /v2/partner/operation/check-confirm

check_number

integer

Номер чека

Код операции продажи. При формировании должен быть уникальным в разрезе партнера

off+Номер_чека_+_Дата_покупки

Пример для POST /partner/operation/check-return

check_number

string

Номер чека возврата

off+Номер_чека

Ошибки

Код ошибки

Текст ответа от сервера АБМ

Причина

pre-check (Продажа)

    

401

"name": "Unauthorized", "message": "Your request was made with invalid credentials.",

Ошибка авторизации. Неправильно указан токен.

404

"name": "Not Found","message": "Page not found.",

Допущена ошибка в адресе сервера

422

"field": "receipt_details", "message": "Receipt Details cannot be blank."

Допущена ошибка в деталях чека (разделитель, параметры и тд)

422

"field": "branch_id","message": "Partner branch not found"

Торговая точка с таким Id не найдена

422

"field": "variables", "message": "Invalid variables format"

Ошибка в синтаксисе переменной для акции

422

"field": "card","message": "Card not found"

Указанной карты нет в программе лояльности

422

"field": "errors","message": "User not found"

Указанного пользователя нет в лояльности

422

"field": "receipt_bonus_amount", "message": "Maximum 330 bonuses"

Превышен лимит по списанию бонусов

422

"field": "phone", "message": "User is blocked"

Если пользователь заблокирован

422

"field": "terminal_id","message": "Terminal not found"

Касса с таким Id не найдена

422

"field": "operator_id", "message": "Operator not found"

Кассир с таким Id не найден

500

"Internal Server Error"

Внешняя ошибка сервера

check-confirm(Продажа)

    

422

"field": "payment_type", "message": "The amount of the check does not match and the amount transferred in the payment_type."

Сумма оплаты не соответствует требуемой

422

"field": "payment_type", "message": "Wrong payment type."

Ошибка синтаксиса в "payment_type"

422

"field": "pre_check_id", "message": "Pre check not found."

pre_check_id не найден

422

"field": "pre_check_id","message": "Pre Check Id cannot be blank."

"pre_check_id" не передан

422

"field": "check_number", "message": "Such check number already exists"

Такой номер check_number уже занят

422

"field": "payment_type","message": "Payment Type cannot be blank."

"payment_type" не передан

422

"field": "pre_check_id", "message": "This check has already been confirmed."

pre_check_id не правильный или был ранее потвержден

500

"Internal Server Error"

Внешняя ошибка сервера

check-return (Возврат)

    

422

"field":"return_details","message":"Unable to return product 1930612

Невозможно вернуть продукт с этим кодом, его ней в указанном чеке или же возврат этого продукта уже осуществлен

422

"field":"return_check_number","message":"Check not found"

Указанный чек для возврата не найден в программе лояльности

500

"Internal Server Error"

Внешняя ошибка сервера
No Comments
Back to top