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

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

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

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

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

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

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

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

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

POST /v2/client/check-phone -метод перевіряє, чи є цей номер телефону вже в програмі лояльності;

POST /partner/operation/user/registration -створює новий рахунок у системі, заповнює анкету нового учасника програми;

GET v2.1/client/oauth2/authorize -запит на перевірку даних;

POST v2.1/client/oauth2/authorize-для отримання коду авторизації;

POST v2.1/client/oauth2/token -для отримання токена доступу;

POST v2.1/client/oauth2/revoke - для отримання оновленого "access_token" та "refresh_token" ;

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

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

POST /partner/referral/link- для створення зв'язку реферал – реферер;

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

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

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

Отримати відповідь передрахунку 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

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

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

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

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

версія: v2

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

ключ:

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

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

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

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

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

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

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

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

{country} - ID країни

2.3. Запит списку міст

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

{country} - ID країни

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

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

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

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

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	ціле число	Канал реєстрації.Для інтернет магазину: 9.

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

{

"success": true,

"status": 201,

"data": {

"phone": "380931000013",

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

}

Авторизація користувача

https://documenter.getpostman.com/view/2804494/SzfCUkyK?version=latest

OAuth 2.0 - протокол авторизації, що дозволяє видати одному сервісу (Наприклад, інтернет-магазину) права на доступ до ресурсів користувача на іншому сервісі (в Особистому кабінеті). Протокол позбавляє необхідності довіряти додатку логін і пароль, а також дозволяє видавати обмежений набір прав.

Схема процесу: Додаток (Інтернет-магазин), Сервіс (Особистий кабінет)

З веб-стариці клієнта (інтернет - магазину) походить редирект на сторінку авторизації нашого ЛК:https://{base_url}/authorize?client_id={client_id}&redirect_uri={redirect_uri}де {base_url} - базовий url ЛК, {client_id} - id клієнта, згенерований під час створення конфігурації в CRM, {redirect_uri} - uri сервісу, який буде виконуватися редирект з додаванням в GET-параметри тимчасового токена.(дані надає АБМ)
На сторінці авторизації користувача запитується підтвердження видачі прав.(Сторінка особистого кабінету з формою на угоду надати свої дані - у разі, якщо авторизація в ЛК здійснена, якщо не - форма для авторизації, потім угоду).
У разі згоди користувача, браузер редагується на URL, вказаний при відкритті сторінки авторизації, з додаванням до GET-параметрів спеціального ключа - authorization code.
Сервер програми виконує POST-запит з отриманим authorization code як параметр. Внаслідок цього запиту повертається access token.

Для роботи з OAuth використовуються методи:

POST v2.1/client/oauth2/token

Служить для отримання "access_token" - використовується як тимчасовий токен авторизації, і "refresh_token" - токен для повторного запиту "access_token", якщо термін дії останнього минув. Термін дії "access_token" - 3600 сек. Інформація про термін дії повертається в параметрі "expires_in".

Назва	Тип даних	Опис
client_id	рядок	id клієнта, згенерований під час створення конфігурації в CRM
client_secret	рядок	ключ клієнта (сервісу), згенерований під час створення конфігурації в CRM
code	рядок	тимчасовий код авторизації, відправлений у параметрі "code" GET-запиту на "redirect_uri"
redirect_uri	рядок	uri сервісу, на який виконуватиметься редирект з додаванням у GET-параметри тимчасового токена. Задається під час створення конфігурації в CRM

Відповідь: {

"success": true,

"status": 201,

"data": {

"token_type": "Bearer",

"expires_in": 3600,

"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6IjJhYzUwOTI1ZjE5YTBhYTQxNDZmYTRhYzhiMDQ5OGEwZjgyZDVlMzJmZjE3ODM3YmE3ZDkxM2RhM2JlNTRiYzhhZWVjZGZiMDQ0YjE4MzJiIn0.eyJhdWQiOiJFWS1RLVpMdUhRV0Fwakx6bDZMcE14NS1pYlBuZDMiLCJqdGkiOiIyYWM1MDkyNWYxOWEwYWE0MTQ2ZmE0YWM4YjA0OThhMGY4MmQ1ZTMyZmYxNzgzN2JhN2Q5MTNkYTNiZTU0YmM4YWVlY2RmYjA0NGIxODMyYiIsImlhdCI6MTU4ODAwODIwNywibmJmIjoxNTg4MDA4MjA3LCJleHAiOjE1ODgwMTE4MDcsInN1YiI6Ijc1NiIsInNjb3BlcyI6W119.dVG7iE3v8ZnxqS3TM88koQjCr7xTun1Nj4XAH1vSlOhgccYVjK8s7YRvEVlo_ti1JrNg1nMSUauX8tqRuCjnRDrCA0fCteJdPc0s3ZrEKjoy8XYNqbxtiurOJAz3bICUdF1s-hJbkV5yWYZleJZ2SfPDR3mSq1FPnWawCCeOpdzo0P3VFI3JiLBoRbSMLRS4k8AUhOIy5AGyITG8dY0mwS-EYmmmXkJG-2eO-KZcfvJWmCCC8NPhELVcyj1-gmmFOf_-_yWHW95ZHhQV8PVArNtvQPvL_JLeYLPK93DGXum73qB-zmCSbRIC4GpjAzkCW17QOkUTo_RDU1jB9QQFLQ",

"refresh_token": "def5020091793bb299b6c802a5ef5714aaeda1637d38ad33cbfbc6130cae09ef043fe7c7bbfa1315cb039f0abb4cc989d1112097be33bd1485512ded277e507867cdc1d8b360a9c4a933afaddf810fba2cf1e5bddace9e5e9fbf48e888527e1c8383f52e23d90031fc8b4cf80e6675e49000939df24562ce17541ff898eb1b4e7567b5d29a04d1b20c538f3b09a6fe340cd39589274bf2d5ba7a40af9c9dff0f11aa063fdc168aab0ab263a6812d99ec07a2d202ed7c9fd47f74db862c36de2da60f7d3077262a16817a292ba3fc60afdfd49ed001591411a5de8c49000fa308c75e28b2d19e0c65a4eb35774841998876dd1293163e5c380ad3b325bd67bcc461a6da3c88fdb8c0130ecb1ac94303a4254fa36704827bc89e39e7f801691301c6cfd3212458509a79b2d59c02aa575dac88c4fcce16f080caf33681cecf08c1c4ef26e86bc495e4da7bc89ae501385fe5f071d5b4395be4385f9d5ef5176ae81b045356402a1ef2c1d83f7885924855105ef0b99dffa553a666b22332572666"

}

POST v2.1/client/oauth2/revoke

Служить для отримання оновленого "access_token" та "refresh_token" за "refresh_token". Термін дії "refresh_token" - 1 міс.

Назва	Тип даних	Опис
client_id	рядок	id клієнта, згенерований під час створення конфігурації в CRM
client_secret	рядок	ключ клієнта (сервісу), згенерований під час створення конфігурації в CRM
refresh_token	рядок	тимчасовий код авторизації, відправлений у параметрі "code" GET-запиту на "redirect_uri"
redirect_uri	рядок	uri сервісу, на який виконуватиметься редирект з додаванням у GET-параметри тимчасового токена. Задається під час створення конфігурації в CRM

Відповідь: {

"success": true,

"status": 201,

"data": {

"token_type": "Bearer",

"expires_in": 3600,

"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImFiN2U1OWUzMzdlZWVhMjcxY2Q1MGU2ZGRlNTUwNjRjZGNkMzkwY2Y0MmQzYzJiN2Q5ODdiZDlhYWMzYjIxMzM1MGVlN2U2NzMwYzY2MzE5In0.eyJhdWQiOiJFWS1RLVpMdUhRV0Fwakx6bDZMcE14NS1pYlBuZDMiLCJqdGkiOiJhYjdlNTllMzM3ZWVlYTI3MWNkNTBlNmRkZTU1MDY0Y2RjZDM5MGNmNDJkM2MyYjdkOTg3YmQ5YWFjM2IyMTMzNTBlZTdlNjczMGM2NjMxOSIsImlhdCI6MTU4ODAwOTg1NywibmJmIjoxNTg4MDA5ODU3LCJleHAiOjE1ODgwMTM0NTcsInN1YiI6Ijc1NiIsInNjb3BlcyI6W119.DfA7la0WtVTj5QxVgIbPKMjc6LUQLb40T3pM4UtyDeYy0cTmcIv8qYMb_t1Yu8SRNgQwovOO8Y95eUnisM3l7h2sup1Abg78QYR2XaX3y9OiW388lJ2bTPgDTncgR7IliAx49jdDIgju5xRcRfukcJRkqd4ewrW3707tgteHMkuN6XWAafrSI0GZKkRgT9vFT4AvSIklo2tc8s8NGXBP-aIyvyYZNWSjaF6o52OE0ThYaKkUeMvPbbmITO2VsEOS3ko7BQye-5tQn2QhomU-CaSS96B7fBdFb--zgzGCgBgMB1ABi46MOAz_5sr9jGj2iZN7VnpvWZZQlzIXziSnnw",

"refresh_token": "def50200ef5c8a317304e039d3da86ed4aa375b90fe8314343218dbb4018cea97ebf9a3da7cb9b0467e201e25f6db9d3cb7c174e7f9b4a5b0b4d368787fa6998484a5fc0d8388c0aae18de6e21928ef5fc947f64c6be4bf0c6ab5890bf54eabb0eb4a9a820405f773ae2152b374b1131c84bacffbd63e5b04fef47c0e2f925281e9e600b872dcc15e50e2a51320a04ad3ed0a1ca9bdbd09d990bed18c89355751ef879e4fc851229c58e6c39557f0cba1124b59508d7d3ea911a6da6934335016300f2fee308c0cbf524a22060776e72ba7820316b323ae42b711643eb6a3382e9cf688e988cb9e95e796c84e151b3274f20a11727064041c6fd7541da441bc17a576fff0c48e996ae703939c097793da76a1e3e94e81f33c52cb7f69530e3ba7b43672f5046c088c5c88ccbf25f5f9b5b9b6b6d7eb97efaf7e0bb8246212ad93623c2e7288e7e12f7d7938005423dafaaac72099eed05aca120fe0aa962a9de05b3170e1ebcfb65696bd13dde40d7e66a42bcff24ff02462de8e35694dd9059"

}

Доступні методи авторизації за "access_token":

Важливо! При роботі із запитами по "access_token" Використовувати тип авторизації "Bearer"

GET v2/client/partners
GET v2/client/card/card-info
GET v2/client/accounts
GET v2/client/partner/news-all
GET v2/client/partner/news-all/{id}
GET v2/client/partner/{guid}/news
GET v2/client/partner/{guid}/news/{id}
GET v2/client/profile
GET v2/client/client-history
GET v2/client/card/card-info
GET v2/client/partner/actions
GET v2/client/partner/actions/{id}

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

POST /v2/partner/operation/pre-check

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

Дані отримані в pre-check потрібно кешувати для подальшого друку чека та відправлення даних про продаж в облікову систему клієнта.

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

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

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

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

Назва	Тип даних	Опис	Відповідає значенню у Клієнта
branch_id	рядок	Код (id) торгової точки Попередньо має бути створений у CRM Лояльності
card	ціле число	Номер картки учасника ПЛ
coupon	рядок	Код купона, якщо купонів кілька, їх необхідно записати через кому
guid	рядок	Guid учасника програми лояльності
offline	логічний	Визначає режим проведення операції: 1 – офлайн, 0-онлайн Списати бонуси у режимі офлайн неможливо
operator_id	рядок	Код касира Попередньо має бути створений у CRM Лояльності
phone	рядок	Номер телефону учасника ПЛ
receipt_bonus_amount	номер	Кількість бонусів за чек. Цей параметр використовується лише у тому випадку, якщо партнер сам розраховує бонус. Відповідне налаштування має бути застосоване у CRM.	Не передавати
receipt_currency	рядок	Валюта бонусів	Передавати значення BON
receipt_datetime	Ціле число (тип: 1470825537)	Дата та час покупки ( формат unix time)
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 - виключити позицію із розрахунку бонусу, не потрібно "meta":"{\"параметр1\":\"значення\", \"параметр2\":\"значення\"}"
session_id	ціле число	Код сесії
terminal_id	рядок	Код каси
variables	рядок	Дод. св-тва товару у вигляді масиву JSON Приклад: {"key1":1, "key2":1}

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

{

"success": true,

"status": 201,

"data": {

"pre_check": {

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

"payment": {

"money": 899.03, // "чиста"сума до оплати (скільки грошей повинен оплатити покупець з урахуванням знижок і списаних бонусів) "bonus_redeemed": 1, // скільки бонусів було використано на оплату покупки

"discount": 0// розмір знижки в грошах },

"currency": "BON",// валюта нарахування бонусів

"coupon": [

{

"code": "3863NUM6",

"success": false,

"message": "Coupon configuration is not active"

{

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

"success": true,

"message": "",

"reward_type": "1"

}

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

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

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

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

"session_id": null, // id сесії

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

"payment_bonus": 63.86, // всього бонусів нарахованих по чеку

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

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

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

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

"receipt_details": [

{

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

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

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

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

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

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

"prod_sum": 300.03, // загальна вартість по позиції продукту

"bonus_restrict": "ok",

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

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

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

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

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

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

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

{

"position": 2,

"prod_cat": "20316",

"prod_code": "86163",

"prod_name": "Tekila Patron silver 0.5",

"prod_price": "100",

"prod_amount": "2",

"prod_sum": 200,

"discount_limit": 0,

"discount": 0,

"parameters": {

"price": 100,

"mrp": null,

"discount": 0,

"max_calculation_bonus": 4,

"max_payment_bonus": 0

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

{

"rule": "coupon",// тип нарахування, купон

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

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

"info": "6556PRE",

"discount": 7.11, // розмір знижки в грошових одиницях

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

}

"discount_bonus": 0,

"bonus": 4,

"bonus_success": [

{

"rule": "cashback",

"action_id": 0,

"action_title": "",

"bonus": 4,

"priority": 999998

}

]

{

"position": 3,

"prod_cat": "20316",

"prod_code": "77765",

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

"prod_price": "100",

"prod_amount": "2",

"prod_sum": 200,

"discount_limit": 200,

"discount": 0,

"parameters": [],

"discount_success": [],

"discount_bonus": 0.5,

"bonus": 29.93,

"bonus_success": [

{

"rule": "cashback",

"action_id": 0,

"action_title": "",

"bonus": 29.93,

"priority": 999998

}

]

{

"position": 4,

"prod_cat": "20316",

"prod_code": "13997",

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

"prod_price": "100",

"prod_amount": "2",

"prod_sum": 200,

"discount_limit": 200,

"discount": 0,

"parameters": {

"price": 100,

"mrp": 95,

"discount": 0,

"max_calculation_bonus": 200,

"max_payment_bonus": 200

"discount_success": [],

"discount_bonus": 0.5,

"bonus": 29.93,

"bonus_success": [

{

"rule": "cashback",

"action_id": 0,

"action_title": "",

"bonus": 29.93,

"priority": 999998

}

]

}

"sms_id": 6756,

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

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

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

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

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

}

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

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

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

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

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

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

Приклад відповіді від лояльності	Значення
"coupon": [ { "code": "1000896246", "success": true, "message": "", "template_name": "Купон на бонус Titan", "reward_type": 0 } ]	Цей купон дійсний і його можна застосувати в даному чеку
"coupon": [ { "code": "1000110027", "success": false, "message": "Coupon redeemed" } ]	Цей купон вже погашено
"coupon": [ { "code": "1000358936", "success": false, "message": "Coupon configuration is not active" } ]	Термін дії вказаного купона минув
"coupon": [ { "code": "1000303888", "success": false, "message": "Wrong user", "template_name": "Купон на скидку" } ]	Цей купон не належить зазначеному користувачеві
"coupon": [ { "code": "1000572007", "success": false, "message": "Coupon is out of date" } ]	Термін дії вказаного купона ще не настав
"coupon":[ { "code":"CUP73591135", "success":false, "message":"No products to apply coupon" } ]	На продукти в даному чеку, дія вказаного купона не поширюється

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

POST /v2/partner/operation/check-confirm

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

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

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

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

{

"success": true,

"status": 201,

"data": {

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

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

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

"bonus_accrued": 63.93, // нараховані бонуси

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

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

"c2b_result": { // інформація по операції списання "success": true, // статус операції

"errorDescription": "", // опис у випадку помилки

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

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

"b2c_result": { // інформація по операції нарахування

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

"errorDescription": "", // опис у випадку помилки

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

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

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

{

"code": "6067PRECHECK",

"success": true,

"message": "",

"options": {

"received_discount": "16.85",

"redemption_count": 1

"reward_type": "1"

}

]

}

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

POST /partner/operation/check-return

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

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

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

#Response for loyalty program particiiant

{

"success": true,

"status": 201,

"data": {

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

"check_number": "4587", // номер чеку повернення

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

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

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

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

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

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

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

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

}

#Response for anonymous client

{

"success": true,

"status": 201,

"data": {

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

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

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

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

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

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

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

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

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

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

}

Режим offline

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

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

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

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

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

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

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

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

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

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

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

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

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

check_number

ціле число

Номер перевірки

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

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

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

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

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

POST /partner/referral/link

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

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

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

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

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

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

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

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

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

Подія Реєстрація вважати виконаним, якщо учасник ~~підводного човна~~ПЛ заповнив всі обов'язкові поля анкети і вказав ідентифікатор свого реферера (зазначено посилання реферера на даний момент, коли користувачеві проставляється дата реєстрації в 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)

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

{

"success": true,

"status": 201,

"data": {

"refererType": "card",

"refererToken": "20000000001",

"refereeType": "card",

"refereeToken": "20000000001"

}

Метод на отримання історії нарахування, списання бонусів

Метод отримання історичних транзакцій

GET /v2/partner/operation/user/{type}/{token}/client-history

Приклад запиту:

GET /v2/partner/operation/user/phone/380631024903/client-history?dateFrom=2021-01-01&dateTo=2021-12-31 HTTP/1.1

Хост: api-groupeseb.abmloyalty.app

Тип вмісту: application/x-www-form-urlencoded

Прийняти мову: en

Авторизація: базова NzMyODljZTgtYzYwYS00ZjRjLTk5MjAtOWQ5ZmQ3NGZjOTQ0Og==

Приклад відповіді:{

"success": true,

"status": 200,

"data": {

"items": [

{

"type": "burn",

"data": {

"date": 1637542837,

"bonus": -2,

"description": "Bonus write off Partner:1 User:26430 Sum:2.000000"

}

{

"type": "burn",

"data": {

"date": 1637542837,

"bonus": -3,

"description": "Bonus write off Partner:1 User:26430 Sum:3.000000"

}

{

"type": "burn",

"data": {

"date": 1637542837,

"bonus": -1,

"description": "Bonus write off Partner:1 User:26430 Sum:1.000000"

}

{

"type": "burn",

"data": {

"date": 1637456419,

"bonus": -2,

"description": "Bonus write off Partner:1 User:26430 Sum:2.000000"

}

{

"type": "burn",

"data": {

"date": 1637370021,

"bonus": -1,

"description": "Bonus write off Partner:1 User:26430 Sum:1.000000"

}

{

"type": "gift",

"data": {

"date": 1637052008,

"bonus": 2,

"close_at": 1637531999,

"description": "Gift bonus User:19 Generator:26430 From:2021-11-16 To:2021-11-21 Sum:2.000000"

}

{

"type": "gift",

"data": {

"date": 1637051986,

"bonus": 3,

"close_at": 1637531999,

"description": "Gift bonus User:18 Generator:26430 From:2021-11-16 To:2021-11-21 Sum:3.000000"

}

{

"type": "gift",

"data": {

"date": 1636974592,

"bonus": 1,

"close_at": 1637359199,

"description": "Gift bonus User:17 Generator:26430 From:2021-11-15 To:2021-11-19 Sum:1.000000"

}

{

"type": "pending",

"data": {

"date": 1636974506,

"bonus": 1,

"category": "manually",

"close_at": 1637531999,

"description": "Test"

}

{

"type": "gift",

"data": {

"date": 1636974327,

"bonus": 2,

"close_at": 1637445599,

"description": "Gift bonus User:16 Generator:26430 From:2021-11-15 To:2021-11-20 Sum:2.000000"

}

{

"type": "burn",

"data": {

"date": 1635465609,

"bonus": -10,

"description": "Bonus write off Partner:1 User:26430 Sum:10.000000"

}

{

"type": "burn",

"data": {

"date": 1635465609,

"bonus": -10,

"description": "Bonus write off Partner:1 User:26430 Sum:10.000000"

}

{

"type": "burn",

"data": {

"date": 1635206405,

"bonus": -1,

"description": "Bonus write off Partner:1 User:26430 Sum:1.000000"

}

{

"type": "burn",

"data": {

"date": 1635033605,

"bonus": -1,

"description": "Bonus write off Partner:1 User:26430 Sum:1.000000"

}

{

"type": "pending",

"data": {

"date": 1634816857,

"bonus": 1,

"category": "manually",

"close_at": 1635195599,

"description": "Test 1"

}

{

"type": "gift",

"data": {

"date": 1634628771,

"bonus": 1,

"close_at": 1635022799,

"description": "Gift bonus User:10 Generator:26430 From:2021-10-19 To:2021-10-23 Sum:1.000000"

}

{

"type": "burn",

"data": {

"date": 1634428804,

"bonus": -1,

"description": "Bonus write off Partner:1 User:26430 Sum:1.000000"

}

{

"type": "gift",

"data": {

"date": 1633960959,

"bonus": 1,

"close_at": 1634417999,

"description": "Gift bonus User:8 Generator:26430 From:2021-10-11 To:2021-10-16 Sum:1.000000"

}

{

"type": "burn",

"data": {

"date": 1632960003,

"bonus": -5,

"description": "Bonus write off Partner:1 User:26430 Sum:5.000000"

}

{

"type": "pending",

"data": {

"date": 1632822670,

"bonus": 10,

"category": "profile",

"close_at": 1635414670,

"description": "Profile fill Юлия Шейнина 10.00BON expiration date 28.10.2021"

}

"_links": {

"self": {

"href": "https://api-groupeseb.abmloyalty.app/v2/partner/operation/user/phone/380631024903/client-history?dateFrom=2021-01-01&dateTo=2021-12-31&page=1"

"first": {

"href": "https://api-groupeseb.abmloyalty.app/v2/partner/operation/user/phone/380631024903/client-history?dateFrom=2021-01-01&dateTo=2021-12-31&page=1"

"last": {

"href": "https://api-groupeseb.abmloyalty.app/v2/partner/operation/user/phone/380631024903/client-history?dateFrom=2021-01-01&dateTo=2021-12-31&page=2"

"next": {

"href": "https://api-groupeseb.abmloyalty.app/v2/partner/operation/user/phone/380631024903/client-history?dateFrom=2021-01-01&dateTo=2021-12-31&page=2"

}

"_meta": {

"totalCount": 23,

"pageCount": 2,

"currentPage": 1,

"perPage": 20

}

Приклади відповідей для різних типів операцій(З описом параметрів)

"type":"чек" - продаж