API Offers

Обзор

Данный документ описывает методы для работы поставщика/дистрибьютора по получению списка предложений, а также изменению, удалению и импорту предложений в системе Smart Satu.

Предложение - это цена, которую предлагает поставщик за определенный товар. Также система Smart Satu позволяет загружать как общие предложения, которые доступны всем торговым точкам, так индивидуальные для конкретных магазинов.

Больше информации по предложениям находится по ссылке: Работа с предложениями

Версия

Version: 1.0.0

Контактная информация

Contact: info@smartsatu.com

URI схема

Host : //food.smartsatu.com/api/ Schemes : HTTPS

Методы

Импорт предложений

POST /offers/import?start=1

Получение списка предложений

GET /offers

Изменение предложений

PUT /offers{sku}

Удаление предложений

DELETE /offers{sku}

Описание

Батчевый импорт предложений

Данный метод предназначен для оптового импорта предложений в систему с ограничением в 1000 предложений. Первый запрос должен отправляться с параметром start=1 (https://food.smartsatu.com/api/offers/import?start=1) После первого запроса вы получите транзакционный идентификатор вида:

{
 'id': '98db89147d6cd0018417b71'
}

Для всех последующих запросов на импорт предложений, вам необходимо добавлять транзакционный идентификатор в параметры запроса: https://food.smartsatu.com/api/offers/import?id=98db89147d6cd0018417b71 Для того чтобы закончить оптовый импорт предложений в систему, необходимо отправить запрос с параметром end=1: https://food.smartsatu.com/api/offers/import?id=98db89147d6cd0018417b71?end=1 Если вам необходимо удалить все старые предложения, то в последнем запросе необходимо передать параметр delete=1: https://food.smartsatu.com/api/offers/import?id=98db89147d6cd0018417b71?end=1&delete=1

В атрибуте 'comment' в JSON-ответе описываются причины ошибок.

Для того чтобы осуществить батчевую загрузку персональных прайсов (для конкретной торговой точки) необходимо указать в параметрах запроса ?store_id (id торговой точки): https://food.smartsatu.com/api/offers/import?start=1&end=1&delete=1&store_id=80

Рекомендации по батчевой загрузке предложений:
Рекомендуем прогружать по 500-1000 предложений в одном чанке. Т.к. если прайс-лист до 1000 предложений, то его можно прогрузить одним чанком. Для этого в запросе на батчевую загрузку устанавливаются флаги старта и окончания очереди: offers/import? start=1&end=1.
Прайс-лист может быть больше чем 1000 штук. Так, если прайс-лист содержит больше 1000 предложений, то открывается очередь с первым чанком с первой 1000 предложений: offers/import?start=1. В ответе вернется id очереди.
С последующими чанками нужно будет слать id очереди offers/import?id=XXXX.
C последним чанком большого прайс-листа нужно будет послать флаг окончания offers/import?id=XXXX&end=1.  

Чтобы удалить старый прайс-лист, нужно послать флаг удаления с первым или последним чанком offers/import?id=XXXX&delete=1. Если это маленький прайс, то offers/import?start=1&end=1&delete=1

В предложениях доступна загрузка Акций с типом "Выгодная цена" - фактическая скидка на товар. Для этого в предложении необходимо указать первоначальную цену Price 1 (для магазина), Price 2 (для ХоРеКа) и конечную промо-цену Price 5.

Таким образом для Торговой точки в каталоге товаров предложения с Выгодной ценой отображаются с перечеркнутой старой ценой (Price 1 или Price 2) и итоговая промо-цена (Price 5). Кроме того, предложение дополнительно помечается иконкой акции "%".

Для временно отсутствующего у поставщика товара в поле “quantity” предложения указывается значение “0” (ноль). Торговым точкам товар будет отображен с пометкой "нет в наличии". Добавить в корзину и заказать такой товар торговые точки не смогут.

ВАЖНО: значение Quantum (количество товара в фасовке/упаковке) обязательно должно быть кратно значению minQuantity (минимальное количество данного товара, которое ТТ обязано купить для оформления заказа). Если значения не пройдут валидацию, то добавится только значение Quantum.

Например:
Поставщик выставил предложение на товар по цене 1100 руб. Фасовка (quantum) осуществляется по 10 шт. Минимальное количество в заказе (minQuantity) - 30 шт. Для успешного заказа торговая точка первоначально добавляет в корзину 30 шт товара (сумма заказа составит 1100 * 30), далее добавление в корзину будет происходить с шагом в 10 шт.

Получение списка предложений

Для того чтобы получить список всех предложений, необходимо отправить GET-запрос c пустым телом по URL: https://food.smartsatu.com/api/offers. Ответом от сервера будет являться массив данных со списком всех ваших предложений в системе Smart Satu с их данными.

Редактирование предложения

Для того чтобы отредактировать предложения требуется добавить в запрос SKU данного предложения. Пример: https://food.smartsatu.site/api/offers/9876786897623

Вместе с данным параметром мы отправляем JSON-тело запроса на изменение.

Удаление предложения

Для того чтобы изменить предложение, необходимо отправить PUT-запрос c JSON-телом по URL: https://food.smartsatu.com/api/offers/{sku}, где sku - это штрих-код предложения, которое необходимо изменить. Ответом от сервера будет являться массив данных с измененными данными предложения.

Для удаления конкретного предложения из всех прайс-листов (как общих, так и индивидульных) необходимо отправить PUT-запрос c JSON-телом по URL: https://food.smartsatu.com/api/offers/{sku}/all, где sku - это штрих-код предложения, которое необходимо изменить. Пример: https://food.smartsatu.com/api/offers/5053990106868/all

Безопасность

В headers запроса обязательно должна передаваться страна пользователя, а также уникальный токен авторизации, который был получен при входе в систему. Ответом от сервера будет являться массив данных с измененными данными заказа.

Type	In	Name	Description
Authorization	header	required	Для создания HTTP Basic Auth заголовка нужно преобразовать access_token следующим образом: $auth= "Basic " . base64encode(access_token . ":"); Данный токен должен использоваться в каждом запросе в системе.
country	header	required	Параметр страны должен использоваться в каждом запросе в системе.

Параметры

Type	Name	Description	Schema
Body	body required	Запрос на изменение предложения

Ответы

Offers Import Response:

HTTP Code	Description	Schema
200	Ok	Offers Import Response
401	Unauthorized	401

Offers Response:

HTTP Code	Description	Schema
200	Ok	Offers Response
401	Unauthorized	401

Offers Response (изменение):

HTTP Code	Description	Schema
200	Ok	Response Order Items
401	Unauthorized	[401
403	Forbidden	403

Delete Offer:

HTTP Code	Description	Schema
204	Ok	Response Order Items
401	Unauthorized	[401
403	Forbidden	403
404	Not Found	404

Принимаемые ресурсом типы MIME

• application/json

Возвращаемые ресурсом типы MIME

• application/json

Определения

Offers Import Request

Name	Description	Schema	Example
name	Название предложения	string	product1
sku	Штрих-код предложения	string	9876786897623
store_id	Идентификационный номер магазина (оставлять значение null - в url указан store_id. Иначе произойдет дублирование предложений)	string	null
unit	Единица измерения	string	null
manufacturer	Производитель	string	null
quantity	Количество	string	1
expires_at	Годен до	string	null
price_1	Цена 1 (для магазинов)	string	555
price_2	Цена 2 (для HoReCa)	string	null
price_3	Цена 3 (для рынков)	string	null
price_4	Цена 4	string	null
price_5	Выгодная цена	string	null
price_without_vat	Цена без НДС	string	null
promotion_price_without_vat	Промо цена без НДС	string	null
delivery_days	Дни доставки* На данный момент данный параметр не используется! Вся функциональность по настройке дней доставки регулируется через WEB-интерфейс	string	1,2,3,4,5,6,0
unique_code	Уникальный код предложения	string	null
quantum	Квант	string	0,5
isImport	Импортировать предложение (да/нет)	boolean	1
minQuantity	Минимальное количество товара для заказа	string	5.500
status	Активность предложения (да/нет)	string	1

Пример запроса:

[
  {
     "name": "product1",
     "sku": "9876786897623",
     "store_id": null
     "unit": "",
     "manufacturer": "",
     "quantity": 1,
     "expires_at": null,
     "price_1": 555,
     "price_2": null,
     "price_3": null,
     "price_4": null,
     "price_5": null *Указание выгодной цены,
     "price_without_vat": null,
     "promotion_price_without_vat": null,
     "delivery_days": "1,2,3,4,5,6,0",
     "unique_code": null,
     "quantum": 0.5,
     "isImport": "1",
     "minQuantity": 5.500,
     "status": 1
   }
]

Offers Request (изменение)

Name	Description	Schema	Example
name	Название предложения	string	product1
manufacturer	Производитель	string	null
quantity	Количество	string	1
expires_at	Годен до	string	null
price_1	Цена 1 (для магазинов)	string	555
price_2	Цена 2 (для HoReCa)	string	null
price_3	Цена 3 (для рынков)	string	null
price_4	Цена 4	string	null
price_5	Цена 5	string	null
status	Активность предложения (да/нет)	string	1
quantum	Квант	string	8.0

Пример запроса:

[
  {
     "name": "Обновленное название предложения",
     "manufacturer": "",
     "quantity": 100,
     "expires_at": null,
     "price_1": 333,
     "price_2": 500,
     "price_3": null,
     "price_4": null,
     "price_5": null,
     "status": 1
     "quantum": 8.0,
  }
]

Offers Import Response

Name	Description	Schema	Example
id	Идентификатор наименования	integer($int32)	5d720cfee9d7c84ad038ff41
count	Количество предложений	integer($int32)	2
comment	Комментарий	string	null

Пример ответа:

  {
     "id": "5d720cfee9d7c84ad038ff41",
     "count": 2,
     "comment": null
  }

Offers Response

Name	Description	Schema	Example
id	Идентификатор наименования предложения	integer($int32)	4317231
name	Название предложения	string	425МЛ ЗЕЛЕНЫЙ ГОРОШЕК GREEN GA
sku	Штрих-код предложения	string	4870007151458
unit	Единица измерения предложения	string	null
manufacturer	Производитель	string	null
quantity	Количество	string	0
expires_at	Годен до	string	null
price_1	Цена 1 (для магазинов)	string	329
price_2	Цена 2 (для HoReCa)	string	329
price_3	Цена 3 (для рынков)	string	329
price_4	Цена 4	string	null
price_5	Цена 5	string	null
unique_code	Уникальный код предложения	string	141209
product_id	Идентификатор продукта	string	28952
step	Шаг	string	null
minQuantity	Минимальное количество товара для заказа	string	null
price	Цена для текущей ТТ	string	329

Пример ответа:

[
 {
   "id": 4317231,
   "name": "425МЛ ЗЕЛЕНЫЙ ГОРОШЕК GREEN GA",
   "sku": 870007151458,
   "unit": "",
   "manufacturer": "",
   "quantity": 0,
   "expires_at": null,
   "price_1": 329,
   "price_2": 329,
   "price_3": 329,
   "price_4": null,
   "price_5": null,
   "unique_code": "151885",
   "product_id": null,
   "step": null,
   "minQuantity": null,
   "price": 329,
 }
]

Delete Offer

Name	Description	Schema	Example
status	Код	string	204
message	Сообщение	string	Предложение удалено

Пример ответа:

{
 "status": 204,
 "message": "Предложение удалено."
}

401

Name	Description	Schema	Example
name	Название	string	Unauthorized
message	Сообщение	string	Your request was made with invalid credentials
code	Код	integer($int32)	0
status	Статус	integer($int32)	401
type	Тип	string	"yii\\web\\UnauthorizedHttpException"

Пример ответа:

{
 "name": "Unauthorized",
 "message": "Your request was made with invalid credentials.",
 "code": 0,
 "status": 401,
 "type": "yii\\web\\UnauthorizedHttpException"
}

403

Name	Description	Schema	Example
name	Название	string	Forbidden
message	Сообщение	string	You're not allowed to delete this item
code	Код	integer($int32)	0
status	Статус	integer($int32)	403
type	Тип	string	yii\\web\\HttpException

Пример ответа:

{
 "name": "Forbidden",
 "message": "You're not allowed to delete this item.",
 "code": 0,
 "status": 403,
 "type": "yii\\\\web\\\\HttpException"
}

404

Name	Description	Schema	Example
name	Название	string	Not Found
message	Сообщение	string	Предложение не существует, удалено либо недоступно
code	Код	integer($int32)	0
status	Статус	integer($int32)	404
type	Тип	string	yii\\web\\HttpException

Пример ответа:

{
 "name": "Not Found",
 "message": "Предложение не существует, удалено либо недоступно",
 "code": 0,
 "status": 404,
 "type": "yii\\web\\HttpException"
}