Интеграция Учетная система - Лояльность
Задание на реализацию обмена данных между Учетной системой и АВМ Loyalty
Суть задачи - организовать регулярный автоматический (без участия человека) обмен данными между учетной системой Клиента и системой лояльности АВМ Loyalty.
Передача товарных групп
Необходимо реализовать выгрузку товарных групп. Выгружать нужно в такой последовательности: сначала группы первого уровня (родительская) затем группы нижнего уровня (дочерняя), следуя иерархии групп товаров вашей системы.
При изменении / обновлении товарных групп следует придерживаться ее иерархии.
Для передачи товаров с учетной системы в Лояльность используются методы 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 – создать ТТ (несколько магазинов одним запросом)
PUT v2/partner/branch – изменить ТТ (несколько магазинов одним запросом)
GET v2/partner/branch/{branch_id} – получить информация о конкретном ТТ
канал API: https://api.sandbox.abmloyalty.app
ключ (токен):(будет предоставлен менеджером внедрения дополнительно)
версия: v2
тип авторизации: Basic Authentication (можно использовать поле имени пользователя как токен(ключ) доступа и пропустить пароль)
ключ:
!! доступ к тестовой базе. Потом нужно будет переключиться на продуктовую систему
Все товары/группы товаров, которые есть в учетной системе должны присутствовать в Лояльности. Передавать новые товары/группы или обновлять существующие нужно с периодичностью 1 раз в несколько часов, а также возможность синхронизировать товары принудительно (на усмотрение стороны Заказчика)
При передаче классификатора сначала передавать группы, потом подгруппы, потом товары (если товар будет передан ранее чем группа, к которой он принадлежит, то товар не запишется. вернется ошибка).
Код группы и код товара должны быть уникальными для каждой группы и для каждого товара.
Ограничения на товар (максимальный бонус к списанию, максимальный бонус к начислению):
- каждый дочерний элемент, может иметь свое ограничение, отличимое от ограничения родительской группы.
- ограничение дочернего элемента, может быть равно или меньше, но не больше ограничения установленного для родительской группы.
- тип ограничения не может быть отличимый от типа ограничения родительской группы.
- если параметры не переданы - наследуются ограничения и тип родительской группы
- если группа корневая – ограничения записываются по умолчанию как 100%
POST v2/partner/products/groups
создать группу товаров
|
Название |
Тип данных |
Описание |
Соответствует значению у Клиента |
|---|---|---|---|
|
group_id |
integer |
Код группы |
|
|
name |
string |
Наименование группы |
|
|
parent_id |
integer |
Код родительской группы. Если родительской группы нет, то заполнять - 0 |
|
|
status |
integer |
1 - активная группа, 0 - неактивная (удаленная) группа |
|
|
max_calculation_bonus |
number |
Максимальный бонус к начислению для группы товаров |
|
|
max_calculation_bonus_unit |
integer |
Тип ограничения для начисления: 0 - %; 1-фиксированное значение |
|
|
max_payment_bonus |
number |
Минимальный бонус к начислению для группы товаров |
|
|
max_payment_bonus_unit |
integer |
Тип ограничения для списания: 0 - %; 1-фиксированное значение |
PUT v2/partner/products/groups/{group_id}
изменить группу товаров
Параметры аналогичны запросу на создание группы. Можно передавать только те параметры, которые необходимо изменить.
POST v2/partner/products
создать продукт (один запрос – один продукт)
|
Название |
Тип данных |
Описание |
Соответствует значению у Клиента |
|---|---|---|---|
|
art_id |
string |
Артикул (код, SKU) товара |
|
|
group_id |
integer |
Код родительской группы товаров |
|
|
max_calculation_bonus |
number |
Максимальный бонус для начисления (ограничение начисления бонуса для данного товара) |
|
|
max_calculation_bonus_unit |
integer |
Тип ограничения для начисления: 0 - %; 1-фиксированное значение |
|
|
max_payment_bonus |
number |
Максимальный бонус для списания (ограничение на списание бонуса для данного товара) |
|
|
max_payment_bonus_unit |
integer |
Тип ограничения для списания: 0 - %; 1-фиксированное значение |
|
|
name |
string |
Наименование товара |
|
|
price |
number |
Стоимость товара. Если стоимость товара часто меняется, или разниться в разных магазинах, то ее значение следует передать в запросах при предрасчете продажи и продажи (ссылка на описание запросов). По умолчанию значение: 0 |
|
|
mrp |
number |
Минимальная розничная цена. В зависимости от базовых настроек программы начисление и списание бонусов может быть применено только на сумму разницы между МРЦ и продажной ценой |
|
|
status |
integer |
1 - активный товар, 0 - неактивный (удаленный) товар |
|
|
properties |
string |
Дополнительные свойства товаров |
|
|
barcode |
string |
Штрих-код товара |
|
|
description |
string |
Описание товара |
|
|
discount |
number |
Размер скидки, число, по умолчанию 0 |
|
|
discount_unit |
integer |
Тип скидки, 0-процент, 1- деньги |
|
|
favorite_product_allowed |
integer |
Разрешение выбрать любимым продуктом,1 - разрешить, 0-запретить |
|
|
group_id_client |
integer |
Код группы для мобильного приложения |
|
|
img_url |
string |
Ссылка на изображение товара |
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 |
string |
id торговой точки, уникальная в пределах сети |
|
|
coord1 |
number |
координаты по широте |
|
|
coord2 |
number |
координаты по долготе |
|
|
address |
string |
адрес ТТ |
|
|
phones |
string |
номер телефона ТТ |
|
|
emails |
string |
Emails ТТ |
|
|
status |
string |
статус ТТ: 1 - активная, 0 - неактивная |
|
|
name |
string |
наименование ТТ |
|
|
time_from |
string |
время начала работы ТТ по графику |
|
|
time_to |
string |
время завершения работы ТТ по графику |
Пример:
{
"06":{ //id торговой точки, уникальная в пределах сети
"branch_id": "06",
"coord1": 55.72839976498599,
"coord2": 37.67679348090883,
"address": "Москва, Волгоградский проспект, 18, Россия, 109316",
"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": "Москва, Андреевская набережная, 1, Россия, 119334",
"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
Создает запись в таблице учета товара на складах.
Cоздает несколько записаей одним запросом (аналогично методу группового создания/изменения товаров /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 //наличие остатка: 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", //id товара
"price": 100.00, //цена продажная, может принимать значение null.
"price_discount": 80.99, //цена акционная, может принимать значение null.
"in_stock": true //наличие остатка: 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", //id товара
"price": 100.00, //цена продажная
"price_discount": 80.99, //цена акционная
"in_stock": true //наличие остатка: 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 - вэб-ссылка на изображение группы товаров. Не обязательно к заполнению.
Response:
parent_id
name
status
updated_at
created_at
group_id
img_url
GET - отдает список групп партнера
Response:
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 указываются только те параметры, которые подлежат изменению.
Response:
parent_id
name
status
updated_at
created_at
group_id
img_url
При переводе группы в неактивный статус - все ее подгруппы/товары должны быть в статусе неактивный.
GET - отдает информацию по конкретной записи
Response:
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 которые, вам понадоблятся :
· barcode - Штрих-код товара, string
· description - описание товара, string
· discount - Размер скидки, число, по умолчанию 0
· discount_unit - Тип скидки, 0-процент, 1- деньги
· favorite_product_allowed- Разрешение выбрать любимым продуктом,1 - разрешить, 0-запретить
· group_id_client - Код группы для мобильного приложения, integer
· img_url - Ссылка на изображение товара, string