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

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

Загальна інформація:

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

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

Онлайн- взаємодія каси та системи АВМ Loyalty відбувається в режимі реального часу)
Офлайн-у разі неможливості взаємодії каси та системи АВМ Loyalty в онлайн режимі (наприклад відсутність інтернет з'єднання) каса повинна записувати транзакції в чергу з номерами карток (перевіряючи їх по масці) і при відновленні з'єднання з АВМ Loyalty передавати їх. Якщо при надсиланні транзакції з черги до системи лояльності система лояльності повертає помилку, що карту не знайдено, запит надсилається повторно, як неідентифікована покупка.

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

Для взаємодії каси та Лояльності використовуються методи API:

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

POST /partner/card/card-update -використовується зміни статусу карти на касі;

POST /partner/operation/pre-check -розрахунок за чеком;

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

POST /партнер/операція/чек-повернення –запит на повернення;

ПУБЛІКУВАТИ /партнер/реферал/посилання -для створення зв'язки реферал-реферер (по роботі реферальної програми)

Операції з продажу:

Перелік операцій продажу на касі:

Режим онлайн - коли є безперервний доступ до мережі Internet
1. Купівля товару
2. Повернення товару (повне, часткове, повторне)
Режим офлайн - немає доступу до мережі Internet - дані продажу не можуть відправитися в CRM Лояльності безпосередньо під час продажу.

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

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

Отримати відповідь передрахунку POST /v2/partner/operation/pre-check.
Вивести повідомлення скільки можна списати бонусів за цей чек, якщо можна списати бонуси - значення з параметра "receipt_bonus_amount": З питанням чи списати бонуси (Відповідь Так, і Відповідь Ні).
Якщо відповідь Так. Вивести поле для введення кількості до списання, при цьому відображати максимальну допустиму кількість до списання. Якщо користувач ввів суму бонусів більше, ніж допустима – видавати відповідне повідомлення та не надсилати дані. Додати кнопку після введення - Надіслати (виконати другий передрахунок POST /v2/partner/operation/pre-check) та Скасувати - не списувати бонуси (вивести суму до оплати на чек та кількість нарахованих бонусів попозиційно та загальну кількість на чек) При натисканні відправити вивести суму до оплати на чек та кількість нарахованих та списаних бонусів (попозиційно та загальна кількість на чек).
Якщо Відповідь Ні вивести суму до оплати на чек та кількість нарахованих бонусів попозиційно та загальну кількість.
Після введення суми до оплати - підтвердження операції продажу POST /v2/partner/operation/check-confirm

За будь-яких змін у продажу - надсилати запит POST /v2/partner/operation/pre-check

Опис методів також доступний за посиланням:

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

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

версія: v2

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

ключ:

!! доступ до тестової бази. Потім потрібно буде перейти на продуктову систему

Опис усіх методів доступний за посиланням:

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

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

Запит на реєстрацію нового учасника програми лояльності (без верифікації по смс)

POST /partner/operation/user/registration

Створює новий рахунок у системі, заповнює анкету нового учасника програми.
У параметрах потрібно передати анкетні дані клієнта.
Обов'язковими параметрами є поля анкети, які встановлені як обов'язкові до заповнення (у даному прикладі 5 параметрів).
Метод повертає телефон та guid нового, створеного у системі учасника програми лояльності.

Назва	Тип даних	Опис
phone	рядок	Номер мобільного телефону у форматі 380#########
first_name	ціле число	Ім'я учасника ПЛ
middle_name	рядок	По батькові учасника програми лояльності
last_name	рядок	Прізвище учасника програми лояльності
birth_day	рядок	Дата народження учасника програми лояльності у форматі 1989-03-17
id_region	ціле число	Глобальний довідник регіону проживання
id_city	ціле число	Глобальний довідник міста проживання пов'язаний з регіоном.
gender	ціле число	Стать:1 - чоловік2- жінка
sms_notify	ціле число	Підписатися на смс розсилку:1-Згідний0-Не згоден
email_notify	ціле число	Підписатися на email розсилку:1-Згідний0-Не згоден
email	рядок	Електронна пошта у форматі abm@abmcloud.com
address	рядок	Адреса учасника ПЛ
channel_reg	ціле число	Канал реєстрації.Для каси: 5.

Приклад відповіді при успішному запиті:

{

"успіх": правда,

"статус":201,

"даних": {

"телефон":"380931000013",

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

}

Реєстрація учасника програми лояльності (з верифікацією по смс)

- 1. Реєстрація з смс за наявності картки
    1. Перевірка номера картки

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

ОТРИМАТИ /client/card/{number}/availability

Назва	Тип даних	Опис	Відповідає значенню у Клієнта
number	рядок	Номер картки учасника ПЛ

- - 1. Запит списку обов'язкових полів

GET /client/profile-params– повертає список полів основної анкети та їх обов'язковість до заповнення.

- - 1. Запит списку додаткових полів

GET /system/profile-fields- повертає список додаткових полів анкети та їхню обов'язковість до заповнення.

- - 1. Запит списку регіонів

ОТРИМАЙТЕ /v2/client/geo/{country}/regions -повертає всі регіони та їх ID

{country} - ID країни

- - 1. Запит списку міст

ОТРИМАЙТЕ /v2/client/geo/{country}/{city}/search-city - пошук у частині назви міста, повертає міста (регіони, країни) заданої country, max = 10шт

{country} - ID країни

{city} - частина назви міста

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

Наприклад, ID країни Казахстан = 81

- - 1. Перевірка номера телефону користувача

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

Назва	Тип даних	Опис	Відповідає значенню у Клієнта
phone	рядок	Номер мобільного телефону у форматі 380#########

- - 1. Реєстрація по смс

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

Назва	Тип даних	Опис	Відповідає значенню у Клієнта
phone	рядок	Номер мобільного телефону у форматі 380#########
password	рядок	Постійний пароль можна вносити стандартний 111111

- - 1. Підтвердження реєстрації паролем із смс

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

Назва	Тип даних	Опис	Відповідає значенню у Клієнта
код	рядок	Код з смс
sms_id	ціле число	Id sms, отриманий у попередньому запиті

- - 1. Присвоєння картки користувачеві

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

Назва	Тип даних	Опис	Відповідає значенню у Клієнта
code	рядок	Номер картки учасника ПЛ

- - 1. Генерація віртуальної картки

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

- - 1. Надсилання анкетних даних

PUT /v2/клієнт /профіль–метод надає зазначені дані учаснику (по токену)

Назва	Тип даних	Опис
first_name	ціле число	Ім'я учасника ПЛ
middle_name	рядок	По батькові учасника програми лояльності
last_name	рядок	Прізвище учасника програми лояльності
birth_day	рядок	Дата народження учасника програми лояльності у форматі 1989-03-17
id_region	ціле число	Глобальний довідник регіону проживання
id_city	ціле число	Глобальний довідник міста проживання пов'язаний з регіоном.
gender	ціле число	Стать:1 - чоловік2- жінка
email	string	Електронна почта в форматі abm@abmcloud.com
sms_subscribe	ціле число	Підписатися на смс розсилку:1-Згідний0-Не згоден
email_subscribe	ціле число	Підписатися на email розсилку:1-Згідний0-Не згоден
children	ціле число	Кількість дітей:0-дітей немає;1-1;2-2;3-3;4- ще 3;
channel_reg	ціле число	Канал реєстрації.Для каси: 5.
family_stat	ціле число	Сімейний стан:0- не визначено;1- одружений;2 - одномісні,
has_auto	ціле число	Наявність автомобіля:0 - не визначено;1 - не сам;2 - легковий автомобіль;3 - мікроавтобус;4 - вантажний вагон;5 - інший автомобіль,
work_status	ціле число	Вид зайнятості:0 - не визначено;1 - бізнесмен;2 - урядовець;3 - службовець;4 - учень;5 - пенсіонер;6 - домогосподарка;7 - інше,

Присвоїти картку учаснику програми

POST /v2/partner/card/card-update (опис у розділі 5.3)

Інформація про учасника програми лояльності

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

Якщо у відповіді набули статусу карти"2":"Заблоковано",то проводити продаж як неідентифікованому покупцеві (у річці не передавати номер картки)

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

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

{type} - карта або телефон

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

Приклад відповіді при успішному запиті:

{

"успіх":правда,

"статус":200,

"дані": {

"токен":"63",//Номер картки

"дані_користувача": {

"гід":«533a7a29-6928-4aad-a1b3-051bb1717af4»,

"мобільний":"380631024903",// номер телефону

"електронна пошта":"Alyonahavrylenko@gmail.com",// email-адреса

"ім'я":"Хелен",//ім'я

"по батькові":"",//По батькові

"прізвище":"Вчитель",//Прізвище

"створений":1578488728,// дата реєстрації;

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

"Стать":2,//Пол

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

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

"id_region":86,//id регіону

"id_city":1116,//id міста

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

"заблоковано":0//Кількість блокувань учасника

"статус_користувача": [],

"профіль": {

"робочий_статус":3,

"діти":0,

"has_auto":1,

"сімейна_статистика":2

"accounts_data":[

{

"рахунок":2620020401,// номер гаманця;

"валюта":"ДОБРЕ",// Назва валюти лояльності;

"баланс":0,// кількість бонусів на рахунку;

"доступний":0// кількість доступних бонусів на рахунку;

}

"cards_data":[

{

"номер":"2020000000259",// Номер картки;

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

"створений":1579167842,// Дата створення карти (генерації);

"дата_активації":1580741547,// дата активації (дата першої операції з карті чи дата прив'язки карти до гаманця);

"дата випуску":нуль,// Дата видачі карти;

"issue_branch":нуль,//Торгівельна точка в якій видана карта;

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

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

{

"номер":"63",

"статус":3,

"створений":1579166828,

"дата_активації":1579178912,

"дата випуску":нуль,

"issue_branch":нуль,

"дата_заблоковано":0,

"тип":1

{

"номер":"67",

"статус":2,

"створений":1579166828,

"дата_активації":1579167114,

"дата випуску":нуль,

"issue_branch":нуль,

"дата_заблоковано":1579167187,

"тип":1

{

"номер":"2020-80477",

"статус":3,

"створений":1578498242,

"дата_активації":1578910691,

"дата випуску":нуль,

"issue_branch":нуль,

"дата_заблоковано":0,

"тип":1

}

"подарункові_бонуси":[//Інформація з подарункових бонусів

{

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

"ім'я":«Для книг»,// Назва нарахування

"бонус":1000,//Кількість нарахованих бонусів

"відкрито_у":1581948299//Дата активації бонусів

}

"статуси карток": {

"0":"новий",

"1":"Активний",

"3":"Оплата",

"2":"Заблоковано"

"типи_карт": {

"1":"Головний",

"2":"Раб"

"загальна_витрачена_сума":13398// загальна сума покупок учасника.}

}

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

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

Назва	Тип даних	Опис
phone	рядок	Номер мобільного телефону у форматі 380#########
first_name	рядок	Ім'я учасника ПЛ
middle_name	рядок	По батькові учасника програми лояльності
last_name	рядок	Прізвище учасника програми лояльності
birth_day	рядок	Дата народження учасника програми лояльності у форматі 1989-03-17
id_region	ціле число	Глобальний довідник регіону проживання
id_city	ціле число	Глобальний довідник міста проживання пов'язаний з регіоном.
gender	ціле число	Стать:1 - чоловік2- жінка
sms_notify	ціле число	Підписатися на смс розсилку:1-Згідний0-Не згоден
email_notify	ціле число	Підписатися на email розсилку:1-Згідний0-Не згоден
email	рядок	Електронна пошта у форматі abm@abmcloud.com

Приклад відповіді при успішному запиті:

{

"успіх": правда,

"статус":200,

"даних": {

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

"мобільний":"380931000013",

"електронною поштою":"titkin1@ua-2.com",

"ім'я":"Артур",

"по батькові":"Іванович",

"прізвище":«Я досліджував»,

"створений":1521451738,//Дата створення

"день_народження":"1979-04-28",

"Стать":"2",

"sms_notify":"0",

"email_notify":"0",

"id_region":"91",

"id_city":"1586",

"заблоковано":1//Кількість блокувань картки

}

Інформація про картку учасника програми лояльності

Зміна статусу картки на касі

Запит оновлює дані картки:

Встановлює/змінює статус картки;
Встановлює/змінює дату видачі;
Встановлює/змінює точку видачі;
Надає карту існуючому учаснику програми.

POST /v2/partner/card/card-update

Перелік параметрів у запиті:

Назва	Тип даних	Опис	Відповідає значенню у Клієнта
card_issue_branch	рядок	Код торгової точки, де видали карту
card_issue_date	ціле число	Дата та час видачі картки передається у форматі unix time
card_number	рядок	Номер картки учасника ПЛ, за якою оновлюються дані
card_status	ціле число	Картка статусу:1 - Активна/Нова2 - Заблоковано3 - Платіжна
user_card	рядок	Номер картки учасника ПЛВикористовується для прив'язки додаткової карти	Ідентифікатор учасника програми лояльності, використовувати при необхідності прив'язки нової карти до існуючого учасника. Потрібно передавати один із цих параметрів
user_phone	рядок	Номер телефону учасника програми лояльності до якого буде прив'язана карта, вказана в параметрі 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 відповідають значенням товару опис деталей клієнт.

перевіряє наявність купона у системі, приналежність до партнера
можливість його погашення цим користувачем на даний момент часу
пов'язує код купона з номером транзакції, до якої буде застосовано купон
робить передрахунок чека з урахуванням купону (для купону знижок)

У запиті необхідно заповнювати наявний параметр"купон"

Перелік параметрів у запиті:

Назва	Тип даних	Опис	Відповідає значенню у Клієнта
branch_id	рядок	Код (id) торгової точкиПопередньо має бути створений у CRM Лояльності
card	ціле число	Номер картки учасника ПЛ
coupon	рядок	Код купона, якщо купонів кілька, їх необхідно записати через кому
offline	логічний	Визначає режим проведення операції: 1 – офлайн, 0-онлайнСписати бонуси у режимі офлайн неможливо
operator_id	рядок	Код касираПопередньо має бути створений у CRM Лояльності
phone	рядок	Номер телефону учасника ПЛ
receipt_bonus_amount	номер	Кількість бонусів за чек, які покупець хоче списати.
receipt_currency	рядок	Валюта бонусів	Передавати значення BON
receipt_datetime	Ціле число (тип: 1470825537)	Дата та час покупки за UTC(GMT) вформаті UNIX час
receipt_description	рядок	Опис типу покупки	Звичайний продаж
receipt_details	рядок	Деталі покупки (повний список товарів та їх властивості у квитанції) у вигляді масиву JSON. "position" - позиція в чеку. "prod_cat" – код групи товарів. "prod_code" - код SKU. "prod_name" - повна назва продукту. "prod_price" - ціна товару. "prod_amount" – кількість товару. "prod_sum" - загальна вартість продукту (зазвичай дорівнює prod_amount * prod_price). bonus_restrict - виключити позицію з розрахунку бонусу, не потрібно,external_discount - рармер (у грошах) зовнішньої знижки"meta":"{\"параметр1\":\"значення\", \"параметр2\":\"значення\"}"
session_id	ціле число	Код сесії
terminal_id	рядок	Код каси
variables	рядок	Дод. св-тва товару у вигляді масиву JSON Приклад: {"key1":1, "key2":1}

Важливо!!!:

1.bonus_restrict - Якщо товар продається за акцією, налаштованою в обліковій або касовій системі, передавати 1 до параметра bonus_restrict, щоб механіки лояльності по даному товару не спрацьовували.В інших позиціях цей параметр не передавати.

2. Якщо на продукт спрацьовує знижка, бонуси на цей продукт не нараховуються та не списуються.

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

{

"успіх": правда,

"статус":201,

"даних": {

"pre_check": {

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

"оплата": {

"гроші":899,03, // "чиста" сума до оплати (скільки грошей необхідно заплатити користувачу, за вирахуванням дисконтних та бонусних знижок

"bonus_redeeded":1, // скільки бонусів використано на оплату покупки

"знижка":0// розмір знижки у грошах

"валюта":"ДОБРЕ",// Валюта нарахування бонусів

"купон": [

{

"код":"3863NUM6",

"успіх": помилковий,

"повідомлення":"Конфігурація купона неактивна"

{

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

"успіх": правда,

"повідомлення":"",

"reward_type":"1"

}

],// купон використовуєний з цим чеком

"ідентифікатор_гілки":"001",// id торгової точки

"terminal_id":"термінал_1",// id каси

"operator_id":"оператор_1",// id касира

"session_id": нуль, // id сесії

"сума_квитанції":900,03, // повна сума чека

"платіжний_бонус":63,86, // всього бонусів нараховано за чеком

"базовий_бонус":63,86, // Розмір базового бонусу (кешбек)

"квитанція_опис":«Перевірочна перевірка»,// опис чека

"день народження_бонус":0, // бонус у день народження

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

"реквізити_квитанції": [

{

"положення":1, // номер позиції у чеку

"prod_cat":"20316",// категорія продукту (якщо товару немає у CRM, то повертається як "0")

"prod_code":"13997",// номер продукту

"prod_name":"КОНФ ВАГОВІ АСОРТІ",// назва продукту (якщо товару немає у CRM, то повертається як "no name product")

"prod_price":"100,01",// ціна товару

"prod_amount":"3",/ / Кількість продукту (шт.)

"prod_sum":300,03, // загальна вартість за позицією продукту

"bonus_restrict":"в порядку",

"ліміт_знижки":300,03, // максимально можлива знижка на позицію

"знижка":0, // Розмір застосованої знижки на позицію

"параметри": [],// Додаткові параметри позиції, встановлені в налаштуваннях товарів (ціна, мрц, обмеження щодо нарахування та списання бонусів)

"discount_success": [],// інформація щодо успішно застосованих дисконтних акцій

"знижка_бонус":0, // розмір знижки наданий бонусами в грошах

"бонус":0, // кількість бонусів, нарахованих на позицію

"бонус_успіх": []// докладна інформація щодо бонусних нарахувань на позицію

{

"положення":2,

"prod_cat":"20316",

"prod_code":"86163",

"prod_name":«Текіла Патрон срібло 0,5»,

"prod_price":"100",

"prod_amount":"2",

"prod_sum":200,

"ліміт_знижки":0,

"знижка":0,

"параметри": {

"ціна":100,

"мрп": нуль,

"знижка":0,

"max_calculation_bonus":4,

"max_payment_bonus":0

"discount_success": [// докладна інформація ззнижкам на позицію

{

"правило":"купон",// Тип нарахування, вечірка

"action_id":0, // id акції (для нарахування з акції)

"назва дії":"",// Назва акції

"інформація":"6556PRE",

"знижка":7.11, // розмір знижки у грошах

"пріоритет":1// Пріоритет акції

}

"знижка_бонус":0,

"бонус":4,

"бонус_успіх": [

{

"правило":"кешбек",

"action_id":0,

"назва дії":"",

"бонус":4,

"пріоритет":999998

}

]

{

"положення":3,

"prod_cat":"20316",

"prod_code":"77765",

"prod_name":"ПАКЕТ МАЙКА ФІРМОВИЙ ЄЛІСЕЙ 12КГ",

"prod_price":"100",

"prod_amount":"2",

"prod_sum":200,

"ліміт_знижки":200,

"знижка":0,

"параметри": [],

"discount_success": [],

"знижка_бонус":0,5,

"бонус":29.93,

"бонус_успіх": [

{

"правило":"кешбек",

"action_id":0,

"назва дії":"",

"бонус":29.93,

"пріоритет":999998

}

]

{

"положення":4,

"prod_cat":"20316",

"prod_code":"13997",

"prod_name":"КОНФ ВАГОВІ АСОРТІ",

"prod_price":"100",

"prod_amount":"2",

"prod_sum":200,

"ліміт_знижки":200,

"знижка":0,

"параметри": {

"ціна":100,

"мрп":95,

"знижка":0,

"max_calculation_bonus":200,

"max_payment_bonus":200

"discount_success": [],

"знижка_бонус":0,5,

"бонус":29.93,

"бонус_успіх": [

{

"правило":"кешбек",

"action_id":0,

"назва дії":"",

"бонус":29.93,

"пріоритет":999998

}

]

}

"sms_id": 6756,

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

"max_payment_money_check":226,45, // максимальна кількість бонусів для списання (у грошовій одиниці з коефіцієнтом переказу 1 бонус = 10 копійок, у вас він може відрізнятися)

"баланс_доступний":100, //Доступно бонусів на рахунку в учасника програми лояльності

"discount_fail": [],//інформація щодо не застосованих дисконтних акцій (акція активна, але в чеку не дотримано умови для її роботи)

"bonus_fail": []//інформація щодо не застосованих бонусних акцій

}

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

- Отримані у відповіді на pre_check параметри "max_payment_bonus_check" і

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

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

- pre_check_id – дійсний 10 днів

Приклади відповідей від АБМ під час використання купонів у чеку:

Приклад відповіді від лояльності	Значення
"купон": [{"код": "1000896246","успіх": правда,"повідомлення": "","template_name": "Купон на бонус Titan","reward_type": 0}]	Цей купон дійсний і його можна застосувати в даному чеку
"купон": [{"код": "1000110027","успіх": false,"message": "Купон погашено"}]	Цей купон вже погашено
"купон": [{"код": "1000358936","успіх": false,"message": "Конфігурація купона неактивна"}]	Термін дії вказаного купона минув
"купон": [{"код": "1000303888","успіх": false,"message": "Не той користувач","template_name": "Купон на знижку"}]	Цей купон не належить зазначеному користувачеві
"купон": [{"код": "1000572007","успіх": false,"message": "Купон застарів"}]	Термін дії вказаного купона ще не настав
"купон":[{"код": "CUP20416079","успіх": false,"message": "Сума замовлення не виконана"}]	Умови купона за сумою чека не виконані (сума чека менша, ніж задано в умовах купона)

Запит на підтвердження продажу

POST /v2/partner/operation/check-confirm

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

Перелік параметрів у запиті:

Назва	Тип даних	Опис	Відповідає значенню у Клієнта
коробка	номер	Кількість грошей, які будуть перераховані у бонуси згідно з коефіцієнтом списання. Має бути реалізований функціонал скарбнички.
номер_чек	ціле число	Номер перевіркиКод операції з продажу. При формуванні має бути унікальним у розрізі партнера	Формат:Номер_чека_+_Дата_покупки
тип оплати	рядок	Массив с типами оплат. Пример: [{"type":1,"sum":899},{"type":2,"sum":0.00}]
pre_check_id	рядок	Код (ID) операції отриманий у відповіді на запит POST /v2/partner/operation/pre-check

Приклад відповіді при успішному запиті

{

"успіх": правда,

"статус":201,

"даних": {

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

"номер_чек":"100110",// Номер чека, переданий касою

"box_bonus":0,07, // бонуси передані у скарбничку

"бонус_нараховано":63,93, // нараховані бонуси

"bonus_redeeded":1,// списані бонуси, рахунок оплати

"bonus_balance":288, //баланс бонусів у користувача після оплати чека

"c2b_result": {// відомості про журнальні операції

"успіх": правда,// статус операції

"errorDescription":"",// опис у разі помилки

"process_transaction_datetime":1548150560,// час операції у unixtime

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

"b2c_результат": {// відомості про журнальні операції

"успіх": правда,// статус операції

"errorDescription":"",// опис у разі помилки

"process_transaction_datetime":1548150560,// час операції у unixtime

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

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

{

"код":"6067ПОПЕРЕДНЯ ПЕРЕВІРКА",

"успіх": правда,

"повідомлення":"",

"параметри": {

"отримана_знижка":"16,85",

"redemption_count":1

"reward_type":"1"

}

]

}

Повернення товару

POST /партнер/операція/чек-повернення

Перелік параметрів у запиті:

Назва	Тип даних	Опис
ідентифікатор_гілки	рядок	Код (id) торгової точки
номер_чек	рядок	Номер чека повернення
operator_id	номер	Код касира
повернення_номер_чеку	рядок	Номер продажу (чека), що підлягає поверненню
повернення_датачас	ціле число (тип: 1550478564)	Дата та час повернення
return_details	рядок	Перелік кодів товарів та їх кількості, що підлягають поверненню. Приклад: [{"prod_code":"139974","prod_amount":1}]
terminal_id	номер	Код каси

Приклад відповіді при успішному запиті

#Відгук для учасника програми лояльності

{

"успіх": правда,

"статус":201,

"дані": {

"return_check_number":"471",// Номер чека продажу з якого зроблено повернення

"чек_номер":"4587",// Номер чека повернення

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

"ідентифікатор_терміналу": нуль,// id каси

"ідентифікатор_оператора": нуль,// id касира

"b2c_returned":15,// кількість бонусів повернутих на рахунок партнера

"b2c_transaction_id":471,// id транзакції повернення бонусів на рахунок партнера

"c2b_returned":0,5,// кількість бонусів повернутих на рахунок клієнта

"c2b_transaction_id":470,// id транзакції повернення бонусів на рахунок клієнта

"повідомлення":"b2c - усі бонуси очищені"// повідомлення про бонуси, що повертаються на рахунок партнера (чи вдалося повернути бонуси, якщо так, то всі бонуси або тільки частина)

}

#Відповідь для анонімного клієнта

{

"успіх": правда,

"статус":201,

"дані": {

"return_check_number":"CN-1570437820-db",// Номер чека продажу з якого зроблено повернення

"чек_номер":"CN-1570437820-ret",// Номер чека повернення

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

"ідентифікатор_терміналу": нуль,// id каси

"ідентифікатор_оператора": нуль,// id касира

"b2c_returned":0,// кількість бонусів повернутих на рахунок партнера

"b2c_transaction_id": нуль,// id транзакції повернення бонусів на рахунок партнера

"c2b_returned":0,// кількість бонусів повернутих на рахунок клієнта

"c2b_transaction_id": нуль,// id транзакції повернення бонусів на рахунок клієнта

"повідомлення":«Не потребує виконання транзакції»// повідомлення про бонуси, що повертаються на рахунок партнера (чи вдалося повернути бонуси, якщо так, то всі бонуси або тільки частина)

}

Режим offline

Якщо немає можливості надіслати дані в CRM Лояльності, необхідно зберігати ці дані в окремому сховищі і вивантажити їх за регламентом рекомендується 1 - 2 рази на добу

Регламент налаштувати гнучкий, щоб клієнт міг за необхідності змінити час.

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

Перелік операцій у режимі offline

- операції продажу

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

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

- Операції повернення

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

POST /партнер/операція/чек-повернення

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

Щоб ідентифікувати транзакцію offline у звітах системи, рекомендуємо до номера чека додавати слово ”off”.

Приклад для POST /v2/partner/operation/check-confirm

номер_чек	ціле число	Номер перевіркиКод операції з продажу. При формуванні має бути унікальним у розрізі партнера	off+Номер_чека_+_Дата_покупки

Приклад для POST /partner/operation/check-return

номер_чек	рядок	Номер чека повернення	off+Номер_чека

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

ОПУБЛІКУЙТЕ /партнера/реферал/посилання

Участь у РП не є обов'язковою. Частина учасників програми лояльності може бути в РП, тоді як інша частина учасників може бути звичайними власниками карт лояльності.

Немає постійної прив'язки Реферала до Реферера. Співвідношення Реферал-Реферер може змінюватись від операції до операції.

До одного реферера може бути прив'язано кілька рефералів. Реферал може змінити свого реферера, у своїй старий зв'язок не видаляється, а перетворюється на неактивний статус.

арбітр (реферер) – учасник програми лояльності, за рекомендацією якого реферали здійснюють операції.

Реферал (рефері) –учасник програми лояльності, який здійснює операцію за рекомендацією іншого учасника.

RP –реферальна програма

Зв'язок реферал -> реферер може бути створена двома способами:

при реєстрації, якщо майбутній учасник програми лояльності вказав ідентифікатор реферера і при цьому виконується подіяРеєстрація.
після реєстрації, якщо учасник програми лояльності вказав ідентифікатор реферера, при цьому подіяРеєстрація не виконується.

Ідентифікатор реферера може бути змінений рефералом будь-якої миті. У такому разі в системі створюється новий зв'язок реферер -> реферал, а старий зв'язок деактивується (зберігаємо для історії та звітності).

ПодіяРеєстрація вважати виконаним, якщо учасник програми лояльності заповнив всі обов'язкові поля анкети і вказав ідентифікатор свого реферера (зазначено посилання реферера на даний момент, коли користувачеві проставляється дата реєстрації в rtl_users.start_day). Після цього в системі створюється зв'язок реферер -> реферал та фіксується подіяРеєстрація.

Алгоритм:

Створення користувача у системі
Створення зв'язку реферер -> реферал методом /partner/referral/link
Завершення реєстрації (заповнення всіх обов'язкових полів анкети)

ПодіяКупівля вважати виконаним, якщо на момент покупки учасник програми лояльності є рефералом (в системі існує активний зв'язок реферер -> реферал). Після цього у системі фіксується подіяКупівля.

Алгоритм:

Розрахунок за чеком методом pre-check
Створення зв'язку реферер -> реферал методом /partner/referral/link
Підтвердження чека методом check-confirm

Або

Створення зв'язку реферер -> реферал методом /partner/referral/link
Розрахунок за чеком методом pre-check
Підтвердження чека методом check-confirm

Алгоритм:

Створення користувача у системі
Створення зв'язку реферер -> реферал методом /partner/referral/link
Завершення реєстрації (заповнення всіх обов'язкових полів анкети)

Назва	Тип даних	Опис
refereeToken	рядок	Твікон (номер картки/телефону хто здійснює продаж)
refereeType	рядок	Тіп ідентифікації рефері(card/phone)
referToken	рядок	Токен (номер картки/телефонуза рекомендацією якого операція відбувається)
refererType	рядок	Тип ідентифікації реферера(card/phone)

Приклад успішної відповіді:

{

"успіх": правда,

"статус":201,

"даних": {

"refererType":"карта",

"referToken":"20000000001",

"refereeType":"карта",

"refereeToken":"20000000001"

}

Помилки

Код помилки	Текст відповіді від сервера АБМ	Причина
попередня перевірка (продаж)
401	"name": "Неавторизовано", "message": "Ваш запит було зроблено з недійсними обліковими даними.",	Помилка авторизації. Неправильно вказано токен.
404	"name": "Не знайдено", "message": "Сторінка не знайдена.",	Допущена помилка на адресі сервера
422	"field": "receipt_details", "message": "Деталі квитанції не можуть бути пустими."	Допущено помилку в деталях чека (розділювач, параметри тощо)
422	"field": "branch_id","message": "Партнерська філія не знайдена"	Торговельну точку з таким Id не знайдено
422	"field": "змінні", "message": "Недійсний формат змінних"	Помилка у синтаксисі змінної для акції
422	"field": "картка", "message": "картка не знайдена"	Вказаної карти немає в програмі лояльності
422	"field": "помилки", "message": "Користувача не знайдено"	Вказаного користувача немає в лояльності
422	"field": "receipt_bonus_amount", "message": "Максимум 330 бонусів"	Перевищено ліміт зі списання бонусів
422	"field": "телефон", "message": "Користувач заблоковано"	Якщо користувач заблоковано
422	"field": "terminal_id", "message": "Термінал не знайдено"	Каса з таким Id не знайдено
422	"field": "operator_id", "message": "Оператор не знайдено"	Касира з таким Id не знайдено
500	"Внутрішня помилка сервера"	Зовнішня помилка сервера
check-confirm(Продаж)
422	"field": "payment_type", "message": "Сума чека не збігається з сумою переказу в payment_type."	Сума оплати не відповідає потрібній
422	"field": "payment_type", "message": "Неправильний тип платежу."	Помилка синтаксису в "payment_type"
422	"field": "pre_check_id", "message": "Попередня перевірка не знайдена."	pre_check_id не знайдено
422	"field": "pre_check_id","message": "Ідентифікатор попередньої перевірки не може бути порожнім."	"pre_check_id" не передано
422	"field": "check_number", "message": "Такий номер чеку вже існує"	Такий номер check_number вже зайнятий
422	"field": "payment_type", "message": "Тип платежу не може бути пустим."	"payment_type" не передано
422	"field": "pre_check_id", "message": "Цю перевірку вже підтверджено."	pre_check_id не правильний або був раніше підтверджений
500	"Внутрішня помилка сервера"	Зовнішня помилка сервера
check-return (Повернення)
422	"field":"return_details","message":"Неможливо повернути товар 1930612	Неможливо повернути продукт із цим кодом, його нею у зазначеному чеку або повернення цього продукту вже здійснено
422	"field":"return_check_number","message":"Чек не знайдено"	Зазначений чек для повернення не знайдено у програмі лояльності
500	"Внутрішня помилка сервера"	Зовнішня помилка сервера

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

Загальна інформація:

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

Запит на реєстрацію нового учасника програми лояльності (без верифікації по смс)

Реєстрація учасника програми лояльності (з верифікацією по смс)

first_name

middle_name

last_name

birth_day

id_region

id_city

gender

email

sms_subscribe

email_subscribe

children

channel_reg

family_stat

has_auto

work_status

Присвоїти картку учаснику програми

Інформація про учасника програми лояльності

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

first_name

middle_name

last_name

birth_day

id_region

id_city

gender

sms_notify

email_notify

email

Інформація про картку учасника програми лояльності

Зміна статусу картки на касі

user_phone

Продаж

Запросити передрахунок за чеком

"terminal_id":"термінал_1",// id каси

"сума_квитанції":900,03, // повна сума чека

Запит на підтвердження продажу

Повернення товару

Режим offline

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

Помилки