Skip to main content

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

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

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

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

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

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

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

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

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

GET /partner/operation/user/{type}/{token}/user-info - повертає інформацію про учасника програми лояльності

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

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

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

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

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

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

  1. Режим онлайн - коли є безперервний доступ до мережі Internet
    1. Купівля товару
    2. Повернення товару (повне, часткове, повторне)
  2. Режим офлайн - немає доступу до мережі 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

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

ключ:

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

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

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",

}

}

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

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

Метод перевіряє, чи є така карта в програмі лояльності, якщо карта є в параметрі 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-Не згоден  

children

 integer Кількість дітей:0-дітей немає;1-1;2-2;3-3;4- ще 3;  

channel_reg

 integer Канал реєстрації.Для каси: 5.  

family_stat

 integer Сімейний стан:0- не визначено;1- одружений;2 - одномісні,  

has_auto

 integer Наявність автомобіля:0 - не визначено;1 - немає авто;2 - легковий автомобіль;3 - мікроавтобус;4 - вантажний ;5 - інший автомобіль,  

work_status

 integer Вид зайнятості:0 - не визначено;1 - бізнесмен;2 - урядовець;3 - службовець;4 - учень;5 - пенсіонер;6 - домогосподарка;7 - інше,  


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

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

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

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

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

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

{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, // згода на мейл-розсилку (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% скидка"

]

 }

}

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

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

Назва Тип даних Опис Відповідає значенню у Клієнта
phone рядок Номер мобільного телефону у форматі 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 //Кількість блокувань карти

}

}

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

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

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

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

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 відповідають значенням товару опис деталей клієнт.

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

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

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

Назва Тип даних Опис Відповідає значенню у Клієнта
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 час (без часового поясу)  
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"// вид купону 1- бонус, 0 - знижка

}

], // купон використані в цьому чеку

"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": "1",

"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_redeeded":1,// списані бонуси, в рахунок оплати

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

"c2b_result": {// відомості про операції списання

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

"errorDescription":"",// опис  помилки

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

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

},

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

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

"errorDescription":"",// опис помилки

"process_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 Код каси  

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

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

{

"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" // повідомлення про бонуси, що повертаються на рахунок партнера (чи вдалося повернути бонуси, якщо так, то всі бонуси або тільки частина)

}

}

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

{

"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" Зовнішня помилка сервера
Back to top