Skip to main content

Завдання на реалізацію обміну даних між Касовою системою та АВМ 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 /партнер/операція/чек-повернення –запит на повернення;

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

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

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

  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 рядок Номер мобільного телефону у форматі 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»,

}

}

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

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

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

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

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

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

        • Запит списку додаткових полів

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

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

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

{country} - ID країни

        • Запит списку міст

ОТРИМАЙТЕ /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 рядок Номер мобільного телефону у форматі 380#########  
        • Реєстрація по смс

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

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

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

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

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

Назва Тип даних Опис Відповідає значенню у Клієнта
code рядок Номер картки учасника ПЛ  
        • Генерація віртуальної картки(якщо немає пластикової картки)

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

        • Надсилання анкетних даних

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

Назва Тип даних Опис Відповідає значенню у Клієнта

first_name

 цsле число Ім'я учасника ПЛ  

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 - інше,  


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

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

Якщо у відповіді набули статусу карти"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// загальна сума покупок учасника.}

}

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

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). Після цього в системі створюється зв'язок реферер -> реферал та фіксується подіяРеєстрація.

Алгоритм:

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

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

Алгоритм:

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

Або

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

Алгоритм:

  1. Створення користувача у системі
  2. Створення зв'язку реферер -> реферал методом /partner/referral/link
  3. Завершення реєстрації (заповнення всіх обов'язкових полів анкети)
Назва Тип даних Опис Відповідає значенню у Клієнта
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 "Внутрішня помилка сервера" Зовнішня помилка сервера
Back to top