Завдання на реалізацію обміну даних між Касовою системою та АВМ Loyalty
Завдання на реалізацію обміну даних між Касовою системою та АВМ Loyalty
Зміст
2. Реєстрація нового учасника програми лояльності на касі 6
2.1. Запит на реєстрацію нового учасника підводного човна (без верифікації по смс) 6
2.2. Реєстрація учасника підводного човна (з верифікацією по смс) 7
2.3. Запити для визначення значень параметрів id_city та id_region 15
2.4. Присвоїти картку учаснику програми 16
3. Авторизація за номером телефону (з смс) 16
3.1. Запит на авторизацію за номером телефону 16
3.2. Запит на підтвердження номера телефону по смс 16
4. Інформація про учасника програми лояльності 17
4.1. Запит інформації про учасника програми лояльності та картку за номером картки 17
4.2. Запит інформації про учасника програми лояльності за номером телефону 19
5. Інформація про картку учасника програми лояльності 23
5.1. Запит інформації про картку учасника програми лояльності за номером картки 23
5.2. Запит інформації про картку учасника програми лояльності за номером картки 23
5.3. Зміна статусу картки на касі 24
6.1. Запросити передрахунок за чеком 25
6.2. Запит на підтвердження продажу 30
9. Реферальна програма 34
10. Помилки 38
Суть завдання - організувати регулярний автоматичний (без участі людини) обмін даними між касовою системою Клієнта та системою лояльності АВМ Loyalty.
Загальна інформація:
В систему АВМ Loyalty передаютьсявсі транзакції, як ідентифіковані, і неідентифіковані.
Обмін даними між касовою системою та системою АВМ Loyalty повинен бути реалізований в двох режимах:
- Онлайн- взаємодія каси та системи АВМ Loyalty відбувається в режимі реального часу)
- Офлайн-у разі неможливості взаємодії каси та системи АВМ Loyalty в онлайн режимі (наприклад відсутність інтернет з'єднання) каса повинна записувати транзакції в чергу з номерами карток (перевіряючи їх по масці) і при відновленні з'єднання з АВМ Loyalty передавати їх. Якщо при надсиланні транзакції з черги до системи лояльності система лояльності повертає помилку, що карту не знайдено, запит надсилається повторно, як неідентифікована покупка.
Дані передаються методами RESTful API по протоколу https.
Для взаємодії каси та Лояльності використовуються методи API:
POST /partner/operation/user/registration –реєструє нового учасника програми лояльності;
ПОСТ/v2.1/client/phone-auth
–запит на авторизацію за номером телефону;
ПОСТ/v2.1/client/phone-auth-confirm- підтвердження номера телефону за допомогою смс;
GET /partner/operation/user/{token}/card-user-info -віддає інформацію про статус картки та власника цієї картки, якщо картку присвоєно до рахунку;
POST /partner/card/card-update -використовується зміни статусу карти на касі;
POST /partner/operation/pre-check -розрахунок за чеком;
POST /partner/operation/check-confirm -запит на підтвердження продажу;
POST /партнер/операція/чек-повернення –запит на повернення;
ПУБЛІКУВАТИ /партнер/реферал/посилання -для створення зв'язки реферал-реферер (по роботі реферальної програми)
Операції з продажу:
Перелік операцій продажу на касі:
- Режим онлайн - коли є безперервний доступ до мережі Internet
- Купівля товару
- Повернення товару (повне, часткове, повторне)
- Режим офлайн - немає доступу до мережі 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-api.sandbox.abmloyalty.app
ключ (токен):
версія: v2
тип авторизації: Базова автентифікація(можна використовувати поле імені користувача як токен (ключ) доступу та пропустити пароль)
ключ:
!! доступ до тестової бази. Потім потрібно буде перейти на продуктову систему
Опис усіх методів доступний за посиланням:
https://documenter.getpostman.com/view/10073265/TzJuAdf5
Реєстрація нового учасника програми лояльності (ПЛ) на касі
Запит на реєстрацію нового учасника підводногопрограми човналояльності (без верифікації по смс)
POST /partner/operation/user/registration
- Створює новий рахунок у системі, заповнює анкету нового учасника програми.
- У параметрах потрібно передати анкетні дані клієнта.
Обов'язковими параметрами є поля анкети, які встановлені як обов'язкові до заповнення (у даному прикладі 5 параметрів). - Метод повертає телефон та guid нового, створеного у системі учасника програми лояльності.
Назва |
Тип даних |
Опис |
Відповідає значенню у Клієнта |
|---|---|---|---|
phone |
рядок |
Номер мобільного телефону у |
|
ціле число |
Ім'я учасника ПЛ |
||
рядок |
По батькові учасника |
||
рядок |
Прізвище учасника |
||
рядок |
Дата народження учасника |
||
|
id_region |
|||
| ціле число |
Глобальний довідник регіону проживання |
|
|
id_city |
|||
| ціле число |
Глобальний довідник міста проживання пов'язаний з регіоном. |
|
ціле число |
Стать: 1 -
|
||
|
sms_notify |
|||
| ціле число |
Підписатися на смс розсилку: 1-
|
|
|
email_notify |
|||
| ціле число |
Підписатися на email розсилку: 1-
|
|
рядок |
Електронна пошта у форматі abm@abmcloud.com |
||
рядок |
Адреса учасника ПЛ |
||
|
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
-
-
-
- Запит списку міст
-
-
ОТРИМАЙТЕ /v2/client/geo/{country}/{city}/search-city - пошук у частині назви міста, повертає міста (регіони, країни) заданої country, max = 10шт
{country} - ID країни прописати в запиті за промовчанням і не виводити в інтерфейс користувача для вибору.
Наприклад, ID країни Казахстан = 81
-
-
-
- Перевірка номера телефону користувача
-
-
POST /v2/client/check-phone–метод перевіряє чи є цей номер телефону вже в програмі лояльності, якщо є, то параметр is_exist у відповідь приходить true, якщо ні-false.
Назва
Тип даних
Опис
Відповідає значенню у Клієнта
phone
рядок
Номер мобільного телефону у
форматі 380#########форматі380#########-
-
-
- Реєстрація по смс
-
-
POST /v2.1/client/registration – метод реєструє номер телефону та відправляє на номер смс із кодом підтвердження
Назва
Тип даних
Опис
Відповідає значенню у Клієнта
phone
рядок
Номер мобільного телефону у
форматі 380#########форматі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/клієнт /профіль–метод надає зазначені дані учаснику (по токену)
Реєстраціяз смс без карти (генерується віртуальна картка)Запит списку обов'язкових полів
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-метод відправляє код із смс і підтверджує реєстраціюНазваТип данихОписВідповідає значенню у КлієнтаcodeрядокКод з смсsms_idціле числоId sms, отриманий у попередньому запитіГенерація віртуальної картки
GET /v2/client/card/generate-card– метод генерує віртуальну карту учаснику підводного човна (за токеном)Надсилання анкетних даних
PUT /v2/клієнт /профіль–метод надає зазначені дані учаснику (по токену)Запити для визначення значень параметрів id_city та id_regionGET /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Інші методи геопозиції:GET /v2/client/geo/{id}/get-country- повертає ВД країни та назву країниGET /v2/client/geo/{id}/get-region- повертає ВД країни, назву країни, ВД регіону, назву регіонуGET /v2/client/geo/{id}/get-city- повертає ВД країни, назву країни, ВД регіону, назву регіону, ВД міста, назву містаGET /v2/client/geo/countries- повертає всі країни та їх ВДПрисвоїти картку учаснику програми
POST /v2/partner/card/card-update (опис у розділі 5.3)
Авторизаціяза номером телефону (з смс)Запит на авторизацію за номером телефонуPOST /v2.1/client/phone-authНазваТип данихОписВідповідає значенню у КлієнтаphoneрядокНомер мобільного телефону у форматі380#########Приклад відповіді при успішному запиті:{"success":true,"status": 201,"data": {"phone": "380504222530","sms_id": 249,"timeout": 60}}Запит на підтвердження номера телефону по смсPOST /v2.1/клієнт/phone-auth-confirmНазваТип данихОписВідповідає значенню у КлієнтаcodeрядокПароль із sms, яка прийде учаснику програмиsms_idціле числоЦей параметр повертається у методіPOST /client/action/auth-phoneПриклад відповіді при успішному запиті:{"success": true,"status": 201,"data": {"phone": "380504222530","token": "d4538090-60d0-42bc-87e9-a6141f4d6f37","token_expired": 1518426222}}Інформація про учасника програми лояльності
Запитінформації про учасника програми лояльності та картку за номером карткиGET /partner/operation/user/{token}/card-user-info{токен}- номер картки за якою запитується інфоМетод повертає інфо по карті + інфо за учасником підводного човна, якщо карта прив'язана до рахунку.Приклад відповіді при успішному запиті:{"успіх":правда,"статус":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// загальна сума покупок учасника."групи": [//список груп, до якого бере участь УПЛ"Кабилдаєва","0555409355","фільтр","Чуй обл група розсилки","testoce2",«Всі клієнти»,"тест омурбекова 2","Тест 2","Горобец М, два магазина, квартал","Чоловіки всі","Крім 996701037770","Гавриленко тест","Іван Іванов","чоловіки від 20 до 30","тест титан","Для розсилки Пуш","\t0000001433663","0684607869","Для_Завдання_2","Титан чоловіка 2 магазини","Лікар тест","Жінки за кермом","Чуй конструктор","Титан всі клієнти","Лаки Лук 1","1010109147909","Ж 20-30, МП_Горобец","чоловіки за завданням","Печіка вагова","чоловіки до 30","Валерія","5% знижка"]}}Рекомендація:
Якщо у відповіді набули статусу карти"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
Приклад відповіді при успішному запиті:
{
}}
}
Інформація про картку учасника програми лояльності
Запитінформації про картку учасника програми лояльності за номером карткиGET /partner/operation/user/{token}/card-user-info{токен}-номер карти за якою запитується інфоМетод повертає інфо по карті + інфо за учасником підводного човна, якщо карта прив'язана до рахунку.Приклад відповіді при успішному запиті представлений у розділі Інформація про учасника програми лояльності.Запит інформації про картку учасника програми лояльності за номером карткиGET /partner/operation/card/{token}/card-info{токен}-номер карти за якою запитується інфоМетод повертає інфо за картоюПриклад відповіді при успішному запиті представлений у розділі Інформація про учасника програми лояльності.{"успіх":правда,"статус":200,"дані": {"токен": "2208801711684",// Номер картки"card_data": {"номер": "2208801711684",// Номер картки"статус": 0, //Статус карти"створено": 1563365120,// Дата створення (генерації карти у системі)"дата_активації": 0,// Дата активації картки (переходу картки в статус "Не заповнена")"date_blocked": 0,// Дата блокування картки (переда картки в статус "Заблокована")"user_guid": "Не знайдено",// Guid учасника програми, якому належить карта"тип": 1,// Тип картки (1-основна, 2-брелок)"main_card_number": "", // Номер основної карти якщо є карти брилоки"номер_підпорядкованої_картки": "", // Номер карти брилок якщо є."card_guid": null,// GUID самої катрти"Issue_date": null,// Дата видачі картки учаснику програми"issue_branch": null// Магазин видачі картки учаснику програми},"статуси": { // Статус старий"0": "Новий",// Нова (карта не має бонусного рахунку, при першому продажу на таку карту вона автоматично перейде в статус)"1": "Активний",//Мапа має бонусний рахунок, але ще не зареєстрована повністю. Може тільки накопичувати бонуси, але не списувати"2": "Заблоковано", // Заблокована. Не може ні накопичувати ні списувати бонуси."3": "Оплата" // Платіжна. Може накопичувати та списувати бонуси.},"типи": { //Типи карток:"1": "Головна",// Основна"2": "Раб"// Карта брилок прив'язана до основної карти.}}}Зміна статусу картки на касі
Запит оновлює дані картки:
- Встановлює/змінює статус картки;
- Встановлює/змінює дату видачі;
- Встановлює/змінює точку видачі;
- Надає карту існуючому учаснику програми.
POST /v2/partner/card/card-update
Перелік параметрів у запиті:
Назва
Тип даних
Опис
Відповідає значенню у Клієнта
card_issue_branch
рядок
Код торгової точки, де видали карту
card_issue_date
ціле число
Дата та час видачі картки передається у форматі unix time
card_number
рядок
Номер картки учасника ПЛ, за якою оновлюються дані
card_status
ціле число
Картка статусу:
1 - Активна/
Нова2Нова2 -Заблоковано3Заблоковано3 - Платіжнаuser_card
рядок
Номер картки учасника
ПЛВикористовуєтьсяПЛВикористовується для прив'язки додаткової картиІдентифікатор учасника
підводногопрограмичовна,лояльності, використовувати при необхідності прив'язки нової карти до існуючого учасника. Потрібно передавати один із цих параметрівuser_phone
рядок
Номер телефону учасника
підводногопрограмичовналояльності до якого буде прив'язана карта, вказана в параметрі card_numberПриклад відповіді при успішному запиті:
{
Продаж
Запросити передрахунок за чеком
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" необхідно зберегти для передачі в операції підтвердження продажу )
{
"terminal_id":"термінал_1",// id каси
"сума_квитанції":900,03, // повна сума чека
підводногопрограмичовналояльності}}}
}
}
Рекомендація:
- Отримані у відповіді на pre_check параметри "max_payment_bonus_check" і
-balance_available виводити на касі мінімальне з них, як «Максимально можлива кількість бонусів для списання:»
-"sms_id": 6756,- ідентифікатор смс підтвердження списання бонусів за кодом з смс
- pre_check_id – дійсний 10 днів
Приклади відповідей від АБМ під час використання купонів у чеку:
Приклад відповіді від лояльності
Значення
"купон": [
00}]
}]Цей купон дійсний і його можна застосувати в даному чеку
}]
}]Цей купон вже погашено
}]
}]Термін дії вказаного купона минув
}]
}]Цей купон не належить зазначеному користувачеві
}]
}]Термін дії вказаного купона ще не настав
"купон":[
}]
}]Умови купона за сумою чека не виконані (сума чека менша, ніж задано в умовах купона)
Запит на підтвердження продажу
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
Приклад відповіді при успішному запиті
{
}]}}
]
}
}
Повернення товару
POST /партнер/операція/чек-повернення
Перелік параметрів у запиті:
Назва
Тип даних
Опис
Відповідає значенню у Клієнта
ідентифікатор_гілки
рядок
Код (id) торгової точки
номер_чек
рядок
Номер чека повернення
operator_id
номер
Код касира
повернення_номер_чеку
рядок
Номер продажу (чека), що підлягає поверненню
повернення_датачас
ціле число (тип: 1550478564)
Дата та час повернення
return_details
рядок
Перелік кодів товарів та їх кількості, що підлягають поверненню. Приклад: [{"prod_code":"139974","prod_amount":1}]
terminal_id
номер
Код каси
Приклад відповіді при успішному запиті
#Відгук для учасника програми лояльності
{
}}
}
#Відповідь для анонімного клієнта
{
}}
}
Режим offline
Якщо немає можливості надіслати дані в CRM Лояльності, необхідно зберігати ці дані в окремому сховищі і вивантажити їх за регламентом рекомендується 1 - 2 рази на добу
Регламент налаштувати гнучкий, щоб клієнт міг за необхідності змінити час.
Виводити на касу в якому стані знаходиться каса – онлайн/оффлайн – списання бонусів неможливо.
Перелік операцій у режимі offline
- операції продажу
Дані з продажу анонімних покупців та учасників
підводногопрограмичовналояльності накопичуються на касі, при доступі до лояльності відправляються дані про купівлюслінним бонусам. Списати бонуси в режимі онлайннеможливо - Виводити на касу діалогове вікно: «Каса перебувати в offline режимі. Списання бонусів неможливе.».POST /v2/partner/operation/pre-checkпередавати до параметра offline – 1(офлайн),далі застосувати метод POST /v2/partner/operation/check-confirm
- Операції повернення
Дані щодо повернення анонімних покупців та учасників
підводногопрограмичовналояльності накопичуються на касі, при доступі до лояльності надсилаються дані про повернення зі списанням нарахованих бонусів та нарахування списаних бонусів.POST /партнер/операція/чек-повернення
Рекомендація
Приклад для 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)
Приклад успішної відповіді:
{
}}
}
Помилки
Код помилки
Текст відповіді від сервера АБМ
Причина
попередня перевірка (продаж)
401
Помилка авторизації. Неправильно вказано токен.
404
"name": "Не знайдено", "message": "Сторінка не знайдена.",
Допущена помилка на адресі сервера
422
"field": "receipt_details", "message": "Деталі квитанції не можуть бути пустими."
Допущено помилку в деталях чека (розділювач, параметри тощо)
422
"field": "branch_id","message": "Партнерська філія не знайдена"
Торговельну точку з таким Id не знайдено
422
"field": "змінні", "message": "Недійсний формат змінних"
Помилка у синтаксисі змінної для акції
422
Вказаної карти немає в програмі лояльності
422
"field": "помилки", "message": "Користувача не знайдено"
Вказаного користувача немає в лояльності
422
Перевищено ліміт зі списання бонусів
422
Якщо користувач заблоковано
422
Каса з таким Id не знайдено
422
Касира з таким 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
"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
"Внутрішня помилка сервера"
Зовнішня помилка сервера