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}
Описание
Батчевый импорт предложений
Данный метод предназначен для оптового импорта предложений (batch) в систему с ограничением в 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-ответе описываются причины ошибок.
Для того чтобы осуществить батчевую загрузку персональных прайсов (для конкретной торговой точки) необходимо указать в get параметрах запроса 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 очереди в get параметрах offers/import?id=XXXX. C последним чанком большого прайс-листа нужно будет послать флаг окончания offers/import?id=XXXX&end=1. NB! Допустим нужно загрузить 5000 предложений. Мы отправляем первый запрос с 1000 предложений и получаем в ответ идентификатор очереди. Дальше посылаем еще 4 запроса с 1000 предложений в каждом запросе и идентификатором очереди. При этом в последнем запросе нужно отправить параметр end=1, который зыкрывает очередь и является тригером для обработчика на загрузку предложений в систему. Если очередь не будет закрыта, то она не будет обработана и загружена в систему.
Чтобы удалить старый прайс-лист, нужно послать флаг удаления с первым или последним чанком offers/import?id=XXXX&delete=1. Если это прайс загружаемый одним запросом, то в get параметрах указываем все три флага (start, end, delete) 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-тело запроса на изменение.
Обновление остатков
Для загрузки измененного количества товара (остатков) необходимо использовать API https://food.smartsatu.com/api/offers/import-only-quantity, в запросе к которому передается массив товаров (sku либо unique_code) с актуальными значениями остатков:
[ { "store_id": null, "sku": null, "unique_code": "48700034204351", "quantity": 30, } ]
Для обновления остатков в определенных персональных прайслистах необходимо в параметре store_id указать массив идентификаторов торговых точек.
Удаление предложения
Для того чтобы изменить предложение, необходимо отправить 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
Определения
Импорт предложений
POST /offers/import?start=1
Offers Import Request
Name | Description | Schema | Example |
---|---|---|---|
name | Название предложения | varchar(255) | product1 |
sku | Штрих-код предложения | varchar(255) | 9876786897623 |
unit | Единица измерения | varchar(50) | шт / кг |
manufacturer | Производитель | varchar(255) | null |
quantity | Количество Для учета остатков. Пока слать 1 (есть в наличии) или 0 (нет в наличии). | smallint(6) | 1 / 0 |
expires_at | Годен до | int(10) | null / unixtimestamp |
price_1 | Цена 1 (для торговых точек в типом Магазин) | decimal(19,2) | float / null |
price_2 | Цена 2 (для для торговых точек в типом HoReCa) | decimal(19,2) | float / null |
price_3 | Цена 3 (для для торговых точек в типом Рынок) | decimal(19,2) | float / null |
price_4 | Цена 4 (только в случае заведения Акции) | decimal(19,2) | float / null |
price_5 | Выгодная цена | decimal(19,2) | float / null |
price_without_vat | Цена без НДС (РФ) | decimal(19,2) | float / null |
promotion_price_without_vat | Промо цена без НДС (РФ) | decimal(19,2) | float / null |
delivery_days | Дни доставки* На данный момент данный параметр не используется! Вся функциональность по настройке дней доставки регулируется через WEB-интерфейс | varchar(127) | "1,2,3,4,5,6,0" |
unique_code | Уникальный код предложения Сервисное поле поставщика. Возвращается в заказе. Например, GUID для 1С. | varchar(255) | string / null |
quantum | Квант поставки | decimal(19,3) | 5.000 |
isImport | Импортировать предложение (да/нет) | boolean | 1 / 0 |
minQuantity | Минимальное количество товара для заказа | decimal(19,3) | 5.000 |
status | Активность предложения (да/нет) Если нужно скрыть товарную карточку из каталога, то выставляем 0 (нет). | tinyint(1) | 1 / 0 |
Пример запроса:
[ { "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, //тут может быть GUID "quantum": 5.000, "isImport": "1", "minQuantity": 5.000, "status": 1 } ]
Offers Import Response
Name | Description | Schema | Example |
---|---|---|---|
id | Идентификатор очереди | string | 5d720cfee9d7c84ad038ff41 |
count | Количество предложений | integer | 2 |
comment | Комментарий | string | null |
Пример ответа:
{ "id": "5d720cfee9d7c84ad038ff41", "count": 2, "comment": null }
Изменение предложений
PUT /offers/{sku}
Offers Request (изменение)
Name | Description | Schema | Example |
---|---|---|---|
name | Название предложения | varchar(255) | product1 |
manufacturer | Производитель | varchar(255) | null |
quantity | Количество Для учета остатков. Пока слать 1 (есть в наличии) или 0 (нет в наличии). | smallint(6) | 1 / 0 |
expires_at | Годен до | int(10) | null / unixtimestamp |
price_1 | Цена 1 (для торговых точек в типом Магазин) | decimal(19,2) | float / null |
price_2 | Цена 2 (для для торговых точек в типом HoReCa) | decimal(19,2) | float / null |
price_3 | Цена 3 (для для торговых точек в типом Рынок) | decimal(19,2) | float / null |
price_4 | Цена 4 (только в случае заведения Акции) | decimal(19,2) | float / null |
price_5 | Выгодная цена | decimal(19,2) | float / null |
status | Активность предложения (да/нет) | string | 1 |
quantum | Квант | decimal(19,3) | 8.0 |
minQuantity | Минимальное количество товара для заказа | decimal(19,3) | null |
status | Активность предложения (да/нет) Если нужно скрыть товарную карточку из каталога, то выставляем 0 (нет). | tinyint(1) | 1 / 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, "minQuantity": null, //нет требования по минимальному количеству в заказе "status": 1 } ]
Offers Response
NB! Ответ приходит в json и по факту это string. За парсинг и выбор типа значений отвечает сторона поставщика.
Name | Description | Schema | Example |
---|---|---|---|
id | Идентификатор наименования предложения в системе SmartSatu | integer | 4317231 |
name | Название предложения | string | 425МЛ ЗЕЛЕНЫЙ ГОРОШЕК GREEN GA |
sku | Артикул предложения | string | 4870007151458 |
unit | Единица измерения предложения | string | шт |
manufacturer | Производитель | string | null |
quantity | Количество | string | 1 |
expires_at | Годен до | string | null |
price_1 | Цена 1 (для магазинов) | string | 329 |
price_2 | Цена 2 (для HoReCa) | string | 329 |
price_3 | Цена 3 (для рынков) | string | null |
price_4 | Цена 4 | string | null |
price_5 | Цена 5 | string | null |
unique_code | Уникальный код предложения Идентификатор предложения у поставщика | string | 141209 |
product_id | Идентификатор продукта (идентификатор товарной карточки в системе SmartSatu) | string | 28952 |
step | Квант поставки (quantum) | string | null |
minQuantity | Минимальное количество товара для заказа | string | null |
Пример ответа:
[ { "id": 4317231, "name": "425МЛ ЗЕЛЕНЫЙ ГОРОШЕК GREEN GA", "sku": 870007151458, "unit": "шт", "manufacturer": "", "quantity": 1, "expires_at": null, "price_1": 329, "price_2": 329, "price_3": null, "price_4": null, "price_5": null, "unique_code": "141209", "product_id": null, "step": null, "minQuantity": null } ]
Удаление предложений
DELETE /offers/{sku}
Delete Offer
Name | Description | Schema | Example |
---|---|---|---|
status | Код | integer | 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 | 0 |
status | Статус | integer | 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 | 0 |
status | Статус | integer | 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 | 0 |
status | Статус | integer | 404 |
type | Тип | string | yii\\web\\HttpException |
Пример ответа:
{ "name": "Not Found", "message": "Предложение не существует, удалено либо недоступно", "code": 0, "status": 404, "type": "yii\\web\\HttpException" }