Завдання на реалізацію обміну даних між Обліковою системою та АВМ Loyalty
Завдання на реалізацію обміну даних між Обліковою системою та АВМ Loyalty
Суть завдання – організувати регулярний автоматичний (без участі людини) обмін даними між обліковою системою Клієнта та системою лояльності АВМ Loyalty.
Передача товарних груп
Необхідно реалізувати вивантаження товарних груп. Вивантажувати потрібно в такій послідовності: спочатку групи першого рівня (батьківська), потім групи нижнього рівня (дочірня), слідуючи ієрархії груп товарів вашої системи.
При зміні/оновленні товарних груп слід дотримуватись її ієрархії.
Крок 1. Вивантажити батьківську групу товарів
Крок 2. Вивантажити дочірню групу товарів
Для передачі товарів з облікової системи Лояльність використовуються методи API:
POST v2/partner/products/groups - Створити групу товарів
PUT v2/partner/products/groups/{group_id} – змінити групу товарів
POST v2/partner/products - Створити продукт (один запит – один продукт)
PUT v2/partner/products/{art_id} - Змінити продукт (один запит – один продукт)
POST v2/partner/batch-products - створити продукти (кілька продуктів одним запитом, рекомендована кількість товарів в одному запиті – 1000)
PUT v2/partner/batch-products - Змінити продукти (кілька продуктів одним запитом, рекомендована кількість товарів в одному запиті - 1000)
GET v2/partner/products/groups- Отримати список всіх груп товарів
GET v2/partner/products/groups/{group_id}– отримати дані про конкретну групу
GET v2/partner/products– отримати список усіх товарів
GET v2 /partner/products/{art_id}– отримати дані про конкретний товар
Опис методів також доступний за посиланням:
https://documenter.getpostman.com/view/10073265/TzJuAdf6
Для передачі торгових точок з облікової системи Лояльність використовуються методи API:
GET v2/partner/branch- Отримати список всіх ТТ (в активному статусі)
POST v2/partner/branch– створити ТТ (кілька магазинів одним запитом)
PUTv2/partner/branch– змінити ТТ (кілька магазинів одним запитом)
GET v2/partner/branch/{branch_id}– отримати інформацію про конкретного ТТ
канал API: https://api.sandbox.abmloyalty.app
ключ (токен):
версія: v2
тип авторизації: Базова автентифікація(можна використовувати поле імені користувача як токен (ключ) доступу та пропустити пароль)
ключ:
!! доступ до тестової бази. Потім потрібно буде перейти на продуктову систему
Усі товари/групи товарів, які є в обліковій системі, повинні бути присутніми в Лояльності. Передавати нові товари/групи або оновлювати існуючі потрібно з періодичністю 1 раз на кілька годин, а також можливість синхронізувати товари примусово (на розсуд сторони Замовника)
При передачі класифікатора спочатку передавати групи, потім підгрупи, потім товари (якщо товар буде передано раніше, ніж група, до якої він належить, то товар не запишеться. повернеться помилка).
Код групи та код товару мають бути унікальними для кожної групи та для кожного товару.
Обмеження на товар (максимальний бонус до списання, максимальний бонус до нарахування):
- кожен дочірній елемент може мати своє обмеження, відмінне від обмеження батьківської групи.
- обмеження дочірнього елемента, може бути рівним або менше, але не більше обмеження встановленого для батьківської групи.
- Тип обмеження не може відрізнятися від типу обмеження батьківської групи.
- якщо параметри не передані - успадковуються обмеження та тип батьківської групи
- якщо група коренева – обмеження записуються за умовчанням як 100%
POST v2/partner/products/groups
створити групу товарів
Назва | Тип даних | Опис | Відповідає значенню у Клієнта |
|---|---|---|---|
group_id | ціле число | Код групи | |
name | рядок | Найменування групи | |
parent_id | ціле число | Код батьківської групи. Якщо батьківської групи немає, то заповнювати – 0 | |
status | ціле число | 1 - активна група, 0 - неактивна (віддалена) група | |
max_calculation_bonus | номер | Максимальний бонус до нарахування для групи товарів | |
max_calculation_bonus_unit | ціле число | Тип обмеження для нарахування: 0 – %; 1-фіксоване значення | |
max_payment_bonus | номер | Мінімальний бонус до нарахування для групи товарів | |
max_payment_bonus_unit | ціле число | Тип обмеження для списання: 0 – %; 1-фіксоване значення |
PUT v2/partner/products/groups/{group_id}
змінити групу товарів
Параметри аналогічні запиту створення групи. Можна передавати лише ті параметри, які потрібно змінити.
POST v2/partner/products
створити продукт (один запит – один продукт)
Назва | Тип даних | Опис | Відповідає значенню у Клієнта |
|---|---|---|---|
art_id | рядок | Артикул (код, SKU) товару | |
group_id | ціле число | Код батьківської групи товарів | |
max_calculation_bonus | номер | Максимальний бонус для нарахування (обмеження нарахування бонусу для цього товару) | |
max_calculation_bonus_unit | ціле число | Тип обмеження для нарахування: 0 – %; 1-фіксоване значення | |
max_payment_bonus | номер | Максимальний бонус для списання (обмеження на списання бонусу для цього товару) | |
max_payment_bonus_unit | ціле число | Тип обмеження для списання: 0 – %; 1-фіксоване значення | |
name | рядок | Найменування товару | |
price | номер | Вартість товару. Якщо вартість товару часто змінюється, або різнитися у різних магазинах, її значення слід передати у запитах при передрахуванні продажу та продажу (посилання опис запитів). За замовчуванням значення: 0 | |
mrp | номер | Мінімальна роздрібна ціна. Залежно від базових налаштувань програми нарахування та списання бонусів може бути застосовано лише на суму різниці між МРЦ та продажною ціною | |
status | ціле число | 1 - активний товар; 0 - неактивний (видалений) товар | |
properties | рядок | Додаткові властивості товарів | |
barcode | рядок | Штрих-код товару | |
description | рядок | Опис товару | |
discount | номер | Розмір знижки, число за замовчуванням 0 | |
discount_unit | ціле число | Тип знижки, 0-відсоток, 1-гроші | |
favorite_product_allowed | ціле число | Дозвіл вибрати улюбленим продуктом,1 - дозволити, 0-заборонити | |
group_id_client | ціле число | Код групи для мобільного додатка | |
img_url | рядок | Посилання на зображення товару |
PUT v2/partner/products/{art_id}
змінити продукт (один запит – один продукт)
Параметри аналогічні запиту створення продукту. Можна передавати лише ті параметри, які потрібно змінити.
POST v2/partner/batch-products
створити продукти (створити декілька продуктів, переданих в одному запиті)
Параметри та його обов'язковість аналогічні запиту створення продукту.Рекомендована кількість товарів в одному запиті – 1000.
приклад:
{
"100001":{
"group_id": 121981,
"art_id": "100001",
"name": "Макароны 400 гр.",
"status": 1,
"price": 80.29,
“mrp”: 50.00,
"max_calculation_bonus": null,
"max_calculation_bonus_unit": null,
"max_payment_bonus": null,
"max_payment_bonus_unit": null
},
"100002":{
"group_id": 121981,
"art_id": "100002",
"name": "Кетчуп острый",
"status": 1,
"price": null,
"max_calculation_bonus": null,
"max_calculation_bonus_unit": null,
"max_payment_bonus": null,
"max_payment_bonus_unit": null
}
}
PUT v2/partner/batch-products
змінити продукти (створити кілька продуктів, переданих в одному запиті)
Параметри аналогічні запиту створення продукту. Можна передавати лише ті параметри, які потрібно змінити.Рекомендована кількість товарів в одному запиті – 1000.
Для передачі торгових точок з облікової системи Лояльність використовуються методи API:
GET v2/partner/branch- Отримати список всіх ТТ (в активному статусі)
POST v2/partner/branch– створити ТТ (кілька магазинів одним запитом)
PUT v2/partner/branch– змінити ТТ (кілька магазинів одним запитом)
GET v2/partner/branch/{branch_id}- отримати інформацію про конкретного ТТ
Усі торгові точки, які є в мережі та працюють з лояльністю – повинні бути присутніми у Лояльності (система не зможе прийняти запит від магазину, який відсутній у базі лояльності).
POST v2/partner/branch
створити ТТ (кілька магазинів одним запитом)
Назва | Тип даних | Опис | Відповідає значенню у Клієнта |
|---|---|---|---|
branch_id | рядок | id торгової точки, унікальна в межах мережі | |
coord1 | номер | координати по широті | |
coord2 | номер | координати по довготі | |
address | рядок | адреса ТТ | |
phones | рядок | номер телефону ТТ | |
emails | рядок | Електронні листи TT | |
status | рядок | статус ТТ: 1 – активна, 0 – неактивна | |
name | рядок | найменування ТТ | |
time_from | рядок | час початку роботи ТТ за графіком | |
time_to | рядок | час завершення роботи ТТ за графіком |
приклад:
{
{
"06":{ //id торгової точки, унікальний в мережі
"branch_id": "06",
"coord1": 55.72839976498599,
"coord2": 37.67679348090883,
"address": "Київ, проспект Бандери, 18, Україна",
"phones": "044-006-06-06",
"emails": "mag06@gmail.com",
"status": 1,
"name": "ТТ6",
"time_from": "00:00",
"time_to": "23:59"
},
"07":{
"branch_id": "07",
"coord1": 55.71260711011073,
"coord2": 37.577362060546875,
"address": "Київ, проспект Бандери, 20, Україна",
"phones": "044-007-07-07",
"emails": "mag07@gmail.com",
"status": 1,
"name": "ТТ7",
"time_from": "00:00",
"time_to": "23:59"
}
}
PUT v2/partner/branch
змінити ТТ (кілька магазинів одним запитом)
Параметри аналогічні запиту створення ТТ. Можна передавати лише ті параметри, які потрібно змінити.
Методи для завантаження акційної ціни
Для завантаження акційних цін у лояльність необхідно використовувати такі методи:
Метод v2/partner/products/warehouse
POST
Створює запис у таблиці обліку товару на складах.
Створює кілька записів одним запитом (аналогічно методу групового створення/зміни товарів /partner/batch-products)
Приклад запиту:
{
"10.22":{ //id ТТ.id товару. Обов'язковий параметр
"branch_id": "10", // id ТТ. Обов'язковий параметр.
"art_id": "22", // ID товару. Обов'язковий параметр.
"price": 100.00, //Ціна продажна. Не обов'язковий параметр може приймати значення null.
"price_discount": 80,99, //Ціна акційна. Не обов'язковий параметр може приймати значення null.
"in_stock": правда //наявність залишку: true - у наявності/false немає. Чи не обов'язковий параметр. Якщо не передано, то false за замовчуванням.
},
"10.23":{.....
}
}
Приналежність партнеру визначати за токеном у запиті.
При успішному виконанні запиту повертається відповідь у статусі 201, кількість створених/не створених записів та статус кожного переданого запису.
Приклад відповіді:
{
"success": true,
"status": 201,
"data": {
"success": 3, //створено записів
"failed": 0, //не створено записів
"branch_product": {
"10.22": { //статус по конкретному запису
"status": 201,
"message": "Ok"
},
"10.23": {
"status": 201,
"message": "Ok"
},
"10.24": {
"status": 201,
"message": "Ok"
}
}
Якщо запит виконано частково - повертається відповідь у статусі 422, кількість створених/не створених записів та статус кожного переданого запису.
Приклад відповіді:
{
"success": false,
"status": 422,
"data": {
"success": 0,
"failed": 3,
"branch_product": {
"10.23": {
"status": 422,
"message": "Invalid product",
"data": {
"art_id": "Error. Acrticle of product has to be unique"
}
},
"10.24": {
"status": 422,
"message": "Invalid product",
"data": {
"art_id": "Error. Acrticle of product has to be unique"
}
},
"10.26": {
"status": 201,
"message": "Ok"
}
}
}
}
метод
PUT /partner/products/warehouse
Змінює запис у таблиці обліку товару на складах.
Змінює кілька записів одним запитом.
Приклад запиту:
{
"10.22":{ //id ТТ.id товару
"branch_id": "10", //id ТТ
"art_id": "22", //ідентифікатор вантажу
"price": 100.00, //Ціна продажна, може набувати значення null.
"price_discount": 80,99, //Ціна акційна, може набувати значення null.
"in_stock": правда //наявність залишку: true - у наявності/false немає
},
"10.23":{.....
}
}
Можна передавати лише ті параметри, які змінюються.
При успішному виконанні запиту повертається відповідь у статусі 201, кількість змінених/не змінених записів та статус кожного переданого запису.
Якщо запит виконано частково - повертається відповідь у статусі 422, кількість змінених/не змінених записів та статус кожного переданого запису.
метод
GET /partner/products/warehouse/{branch_id}
Повертає інформацію про товари на вказаному складі (магазині).
- {branch_id} - id магазина
Приклад відповіді:
{
"success": true,
"status": 200,
"data": {
"items": [
{
"branch_id": "10", //id ТТ
"art_id": "22", //ідентифікатор вантажу
"price": 100.00, //Ціна продажна
"price_discount": 80,99, //Ціна акційна
"in_stock": правда //наявність залишку: true - у наявності/false немає
}
]
метод
GET /partner/products/warehouse/{branch_id}/{art_id}
Повертає інформацію про конкретний товар на вказаному складі (магазині).
- {branch_id} - id магазина
- {art_id} - id товару
Приклад успішної відповіді та перевірки – аналогічні методу /partner/products/warehouse/{branch_id}
Для завантаження товарів у Мобільний додаток необхідно виконати кілька доопрацювань з вашого боку:
1. Реалізувати передачу каталогу груп та підгруп товарів, що використовується в Інтернет-магазині. Використовуючи метод POST/partner/products/groups-client
POST/partner/products/groups-client - Партнер визначається за токеном авторизації
POST - створює новий запис
BODY:
parent_id – id батьківської групи. Обов'язково до заповнення. Для групи першого рівня брати 0.
name – найменування групи. Обов'язково до заповнення.
status – статус групи: 1-активний; 0-неактивний. Не обов'язково заповнити. Якщо не передано, то за промовчанням надавати активний статус.
group_id - зовнішній ID групи (ID групи у партнера). Обов'язково до заповнення.
img_url – веб-посилання на зображення групи товарів. Не обов'язково заповнити.
Відповідь:
parent_id
name
status
updated_at
created_at
group_id
img_url
GET – віддає список груп партнера
Відповідь:
parent_id
name
status
updated_at
created_at
group_id
img_url
PUT /partner/products/groups-client/{group_id} - Новий метод.
Партнер визначається за токеном авторизації.
{group_id} - ID групи, за якою виконується запит.
PUT - змінює запис
BODY:
parent_id
name
status
group_id
img_url
У BODY вказуються лише параметри, які підлягають зміні.
Відповідь:
parent_id
name
status
updated_at
created_at
group_id
img_url
При переведенні групи в неактивний статус - всі її підгрупи/товари повинні бути неактивними.
GET - віддає інформацію щодо конкретного запису
Відповідь:
parent_id
name
status
updated_at
created_at
group_id
img_url
2. Реалізувати вивантаження опису, штрих-кодів та зображень товарів за допомогою методів:
POST v2/partner/products - Створити продукт (один запит – один продукт)
PUT v2/partner/products/{art_id} - Змінити продукт (один запит – один продукт)
POST v2/partner/batch-products - створити продукти (кілька продуктів одним запитом, рекомендована кількість товарів в одному запиті – 1000)
PUT v2/partner/batch-products - Змінити продукти (кілька продуктів одним запитом, рекомендована кількість товарів в одному запиті - 1000)
Опис параметрів у BODY які, вам знадобляться:
· штрих-код - Штрих-код вантажу, рядок
· description - опис товару, string
· discount - Розмір знижки, число за замовчуванням 0
· discount_unit - Тип знижки, 0-відсоток, 1-гроші
· favorite_product_allowed- Дозвіл вибрати улюбленим продуктом,1 - дозволити, 0-заборонити
· group_id_client - Код групи для мобільного додатку, integer
· img_url - Посилання на зображення товару, string