API Offers: различия между версиями

Материал из SmartSatu Knowledge Base
Перейти к навигации Перейти к поиску
 
(не показана 31 промежуточная версия этого же участника)
Строка 16: Строка 16:
 
'''URI схема'''
 
'''URI схема'''
  
−
''Host : //smartsatu.com/api/ Schemes : HTTPS''
+
''Host : //food.smartsatu.com/api/ Schemes : HTTPS''
 +
 
 
==Методы==
 
==Методы==
 
===Импорт предложений===
 
===Импорт предложений===
Строка 23: Строка 24:
 
GET /offers  
 
GET /offers  
 
===Изменение предложений===
 
===Изменение предложений===
−
PUT /offers{sku}
+
PUT /offers/{sku}
 +
 
 
===Удаление предложений===
 
===Удаление предложений===
−
DELETE /offers{sku}
+
DELETE /offers/{sku}
 +
 
 
==Описание==
 
==Описание==
 
===Батчевый импорт предложений===
 
===Батчевый импорт предложений===
−
Данный метод предназначен для оптового импорта предложений в систему с ограничением в 1000 предложений.
+
Данный метод предназначен для оптового импорта предложений (batch) в систему с ограничением в 1000 предложений в одном запросе.  
−
Первый запрос должен отправляться с параметром start=1 (https://food.smartsatu.com/api/offers/import?start=1)
+
Первый запрос должен отправляться с параметром <code>start=1</code>
−
После первого запроса вы получите транзакционный идентификатор вида:
+
<code>https://food.smartsatu.com/api/offers/import?start=1</code>
 +
В ответ первого запроса вы получите транзакционный идентификатор очереди вида:
 
  {
 
  {
 
   'id': '98db89147d6cd0018417b71'
 
   'id': '98db89147d6cd0018417b71'
 
  }
 
  }
−
Для всех последующих запросов на импорт предложений, вам необходимо добавлять транзакционный идентификатор в параметры запроса.
+
Для всех последующих запросов на импорт предложений, вам необходимо добавлять транзакционный идентификатор в параметры запроса:
−
(https://food.smartsatu.com/api/offers/import?id=98db89147d6cd0018417b71)
+
<code>https://food.smartsatu.com/api/offers/import?id=98db89147d6cd0018417b71</code>
−
Для того чтобы закончить оптовый импорт предложений в систему, необходимо отправить запрос с параметром end=1 (https://food.smartsatu.com/api/offers/import?id=98db89147d6cd0018417b71?end=1)
+
Для того чтобы закончить оптовый импорт предложений в систему, необходимо отправить запрос с параметром end=1:
−
Если вам необходимо удалить все старые предложения, то в последнем запросе необходимо передать параметр delete=1 (https://food.smartsatu.com/api/offers/import?delete=1)
+
<code>https://food.smartsatu.com/api/offers/import?id=98db89147d6cd0018417b71&end=1</code>
 +
Если вам необходимо удалить все старые предложения, то в последнем запросе необходимо передать параметр delete=1:
 +
<code>https://food.smartsatu.com/api/offers/import?id=98db89147d6cd0018417b71&end=1&delete=1</code>
  
−
В атрибуте'comment' в JSON-ответе описываются причины ошибок.  
+
В атрибуте 'comment' в JSON-ответе описываются причины ошибок.  
  
−
Для того чтобы осуществить батчевую загрузку персональных прайсов (для конкретной торговой точки) необходимо указать в параметрах запроса ?store_id
+
Для того чтобы осуществить батчевую '''загрузку персональных прайсов (для конкретной торговой точки)''' необходимо указать в get параметрах запроса <code>store_id</code> (id торговой точки):
−
https://food.smartsatu.com/api/offers/import?start=1&store_id=80).
+
<code>https://food.smartsatu.com/api/offers/import?start=1&end=1&delete=1&store_id=80</code>
  
 
  Рекомендации по батчевой загрузке предложений:
 
  Рекомендации по батчевой загрузке предложений:
−
  Рекомендуем прогружать по 500-1000 предложений в одном чанке. Т.к. если прайс-лист до 1000 предложений, то его можно прогрузить одним чанком. Для этого в запросе на батчевую загрузку вы устанавливает флаги старта и окончания очереди: offers/import? start=1&end=1.
+
  Рекомендуем прогружать по 500-1000 предложений в одном запросе. Т.к. если прайс-лист до 1000 предложений, то его можно прогрузить одним запросом. Для этого в запросе на батчевую загрузку устанавливаются флаги старта и окончания очереди: offers/import?start=1&end=1.
−
  Однако прайс-лист может быть больше чем 1000 штук. Так, если прайс-лист содержит больше 1000 предложений, то вы открываете очередь с первым чанком (в котором первые 1000 предложений) offers/import?start=1. Ответом на такой запрос мы вернем id очереди.
+
  Прайс-лист может быть больше чем 1000 штук. Так, если прайс-лист содержит больше 1000 предложений, то открывается очередь с первым запросом с первой 1000 предложений: offers/import?start=1. В ответе вернется id очереди.
−
  С последующими чанками нужно будет слать id очереди offers/import?id=XXXX.
+
  С последующими запросами нужно будет слать id очереди в get параметрах offers/import?id=XXXX.
−
  C последним чанком большого прайс-листа нужно будет послать флаг окончания offers/import?id=XXXX&end=1.   
+
  C последним чанком большого прайс-листа нужно будет послать флаг окончания offers/import?id=XXXX&end=1.
 +
'''NB!''' Допустим нужно загрузить 5000 предложений. Мы отправляем первый запрос с 1000 предложений и получаем в ответ идентификатор очереди. Дальше посылаем еще 4 запроса с 1000 предложений в каждом запросе и идентификатором очереди. При этом в последнем запросе нужно отправить параметр end=1, который зыкрывает очередь и является тригером для обработчика на загрузку предложений в систему. Если очередь не будет закрыта, то она не будет обработана и загружена в систему.   
 
   
 
   
−
Чтобы удалить старый прайс-лист, нужно послать флаг удаления с первым или последним чанком offers/import?id=XXXX&delete=1. Если это маленький прайс, то offers/import?start=1&end=1&delete=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.
 
  Таким образом для Торговой точки в каталоге товаров предложения с Выгодной ценой отображаются с перечеркнутой старой ценой (Price 1 или Price 2) и итоговая промо-цена (Price 5). Кроме того, предложение дополнительно помечается иконкой акции "%".
 
  Таким образом для Торговой точки в каталоге товаров предложения с Выгодной ценой отображаются с перечеркнутой старой ценой (Price 1 или Price 2) и итоговая промо-цена (Price 5). Кроме того, предложение дополнительно помечается иконкой акции "%".
  
−
Обратите внимание, что значение Quantum (количество товара в фасовке/упаковке) обязательно должно быть кратно значению minQuantity (минимальное количество данного товара, которое ТТ обязано купить для оформления заказа). Если значения не пройдут валидацию, то добавится только значение Quantum.
+
Для временно отсутствующего у поставщика товара в поле <code>quantity</code> предложения указывается значение <code>0</code> (ноль). Торговым точкам товар будет отображен с пометкой "нет в наличии". Добавить в корзину и заказать такой товар торговые точки не смогут. 
 +
 
 +
ВАЖНО: значение Quantum (количество товара в фасовке/упаковке) обязательно должно быть кратно значению minQuantity (минимальное количество данного товара, которое ТТ обязано купить для оформления заказа). Если значения не пройдут валидацию, то добавится только значение Quantum.  
 
  Например:
 
  Например:
−
  Поставщик выставил предложение на товар по цене 1100 руб. Фасовка (quantum) осуществляется по 10 шт. Минимальное количество в заказе (minQuantity) - 30 шт. Для успешного заказа торговая точка первоначально добавляет в корзину 30 шт товара (сумма заказа составит 1100 * 30), далее добавление в корзину будет происходить с шагом в 10 шт.
+
  Поставщик выставил предложение на товар по цене 1100 руб за единицу. Фасовка (quantum) осуществляется по 10 шт. Минимальное количество в заказе (minQuantity) - 30 шт. Для успешного заказа торговая точка первоначально добавляет в корзину 30 шт товара (сумма заказа составит 1100 * 30), далее добавление в корзину будет происходить с шагом в 10 шт.
  
 
===Получение списка предложений===
 
===Получение списка предложений===
Строка 66: Строка 75:
  
 
Вместе с данным параметром мы отправляем JSON-тело запроса на изменение.
 
Вместе с данным параметром мы отправляем JSON-тело запроса на изменение.
 +
 +
===Обновление остатков===
 +
Для загрузки измененного количества товара (остатков) необходимо использовать API https://food.smartsatu.com/api/offers/import-only-quantity?start=1&end=1, в запросе к которому передается массив товаров ('''sku''' либо '''unique_code''') с актуальными значениями остатков:
 +
[
 +
    {
 +
      "sku": null,
 +
      "unique_code": "48700034204351",
 +
      "quantity": 30,
 +
    }
 +
]
 +
Для обновления остатков в определенном персональном прайслисте необходимо в параметре '''store_id''' указать идентификатор торговой точки:
 +
https://food.smartsatu.com/api/offers/import-only-quantity?start=1&end=1&store_id=9576
 +
 
===Удаление предложения===
 
===Удаление предложения===
 
Для того чтобы изменить предложение, необходимо отправить PUT-запрос c JSON-телом по URL: https://food.smartsatu.com/api/offers/{sku}, где sku - это штрих-код предложения, которое необходимо изменить.  
 
Для того чтобы изменить предложение, необходимо отправить PUT-запрос c JSON-телом по URL: https://food.smartsatu.com/api/offers/{sku}, где sku - это штрих-код предложения, которое необходимо изменить.  
Строка 177: Строка 199:
  
 
==Определения==
 
==Определения==
−
===Offers Import Request===
+
===Импорт предложений===
 +
POST /offers/import?start=1
 +
 
 +
====Offers Import Request====
 
{| class="wikitable"
 
{| class="wikitable"
 
! style="font-weight:bold;" | Name
 
! style="font-weight:bold;" | Name
Строка 186: Строка 211:
 
| style="font-weight:bold;" | name
 
| style="font-weight:bold;" | name
 
| Название предложения
 
| Название предложения
−
| string
+
| varchar(255)
 
| product1
 
| product1
 
|-
 
|-
 
| style="font-weight:bold;" | sku
 
| style="font-weight:bold;" | sku
 
| Штрих-код предложения
 
| Штрих-код предложения
−
| string
+
| varchar(255)
 
| 9876786897623
 
| 9876786897623
−
|-
 
−
| style="font-weight:bold;" | store_id
 
−
| Идентификационный номер магазина (индивидуальное предложение)
 
−
| string
 
−
| null
 
 
|-
 
|-
 
| style="font-weight:bold;" | unit
 
| style="font-weight:bold;" | unit
 
| Единица измерения
 
| Единица измерения
−
| string
+
| varchar(50)
−
| null
+
| шт / кг
 
|-
 
|-
 
| style="font-weight:bold;" | manufacturer
 
| style="font-weight:bold;" | manufacturer
 
| Производитель
 
| Производитель
−
| string
+
| varchar(255)
 
| null
 
| null
 
|-
 
|-
 
| style="font-weight:bold;" | quantity
 
| style="font-weight:bold;" | quantity
−
| Количество
+
| Количество '''Для учета остатков. Пока слать 1 (есть в наличии) или 0 (нет в наличии).'''
−
| string
+
| smallint(6)
−
| 1
+
| 1 / 0
 
|-
 
|-
 
| style="font-weight:bold;" | expires_at
 
| style="font-weight:bold;" | expires_at
 
| Годен до
 
| Годен до
−
| string
+
| int(10)
−
| null
+
| null / unixtimestamp
 
|-
 
|-
 
| style="font-weight:bold;" | price_1
 
| style="font-weight:bold;" | price_1
−
| Цена 1 (для магазинов)
+
| Цена 1 (для торговых точек в типом Магазин)
−
| string
+
| decimal(19,2)
−
| 555
+
| float / null
 
|-
 
|-
 
| style="font-weight:bold;" | price_2
 
| style="font-weight:bold;" | price_2
−
| Цена 2 (для HoReCa)
+
| Цена 2 (для для торговых точек в типом HoReCa)
−
| string
+
| decimal(19,2)
−
| null
+
| float / null
 
|-
 
|-
 
| style="font-weight:bold;" | price_3
 
| style="font-weight:bold;" | price_3
−
| Цена 3 (для рынков)
+
| Цена 3 (для для торговых точек в типом Рынок)
−
| string
+
| decimal(19,2)
−
| null
+
| float / null
 
|-
 
|-
 
| style="font-weight:bold;" | price_4
 
| style="font-weight:bold;" | price_4
−
| Цена 4
+
| Цена 4 (только в случае заведения Акции)
−
| string
+
| decimal(19,2)
−
| null
+
| float / null
 
|-
 
|-
 
| style="font-weight:bold;" | price_5
 
| style="font-weight:bold;" | price_5
−
| Цена 5
+
| Выгодная цена
−
| string
+
| decimal(19,2)
−
| null
+
| float / null
 
|-
 
|-
 
| style="font-weight:bold;" | price_without_vat
 
| style="font-weight:bold;" | price_without_vat
−
| Цена без НДС
+
| Цена без НДС (РФ)
−
| string
+
| decimal(19,2)
−
| null
+
| float / null
 
|-
 
|-
 
| style="font-weight:bold;" | promotion_price_without_vat
 
| style="font-weight:bold;" | promotion_price_without_vat
−
| Промо цена без НДС
+
| Промо цена без НДС (РФ)
−
| string
+
| decimal(19,2)
−
| null
+
| float / null
 
|-
 
|-
 
| style="font-weight:bold;" | delivery_days
 
| style="font-weight:bold;" | delivery_days
 
| Дни доставки* '''На данный момент данный параметр не используется! Вся функциональность по настройке дней доставки регулируется через WEB-интерфейс'''
 
| Дни доставки* '''На данный момент данный параметр не используется! Вся функциональность по настройке дней доставки регулируется через WEB-интерфейс'''
−
| string
+
| varchar(127)
−
| 1,2,3,4,5,6,0
+
| "1,2,3,4,5,6,0"
 
|-
 
|-
 
| style="font-weight:bold;" | unique_code
 
| style="font-weight:bold;" | unique_code
−
| Уникальный код предложения
+
| Уникальный код предложения '''Сервисное поле поставщика. Возвращается в заказе. Например, GUID для 1С.'''
−
| string
+
| varchar(255)
−
| null
+
| string / null
 
|-
 
|-
 
| style="font-weight:bold;" | quantum
 
| style="font-weight:bold;" | quantum
−
| Квант
+
| Квант поставки
−
| string
+
| decimal(19,3)
−
| 0,5
+
| 5.000
 
|-
 
|-
 
| style="font-weight:bold;" | isImport
 
| style="font-weight:bold;" | isImport
 
| Импортировать предложение (да/нет)
 
| Импортировать предложение (да/нет)
 
| boolean
 
| boolean
−
| 1
+
| 1 / 0
 
|-
 
|-
 
| style="font-weight:bold;" | minQuantity
 
| style="font-weight:bold;" | minQuantity
 
| Минимальное количество товара для заказа
 
| Минимальное количество товара для заказа
−
| string
+
| decimal(19,3)
−
| 5.500
+
| 5.000
 
|-
 
|-
 
| style="font-weight:bold;" | status
 
| style="font-weight:bold;" | status
−
| Активность предложения (да/нет)
+
| Активность предложения (да/нет) '''Если нужно скрыть товарную карточку из каталога, то выставляем 0 (нет).'''
−
| string
+
| tinyint(1)
−
| 1
+
| 1 / 0
 
|}
 
|}
 
Пример запроса:
 
Пример запроса:
Строка 298: Строка 318:
 
       "price_3": null,
 
       "price_3": null,
 
       "price_4": null,
 
       "price_4": null,
−
       "price_5": null,
+
       "price_5": null *Указание выгодной цены,
−
      "price": 888,
 
 
       "price_without_vat": null,
 
       "price_without_vat": null,
 
       "promotion_price_without_vat": null,
 
       "promotion_price_without_vat": null,
 
       "delivery_days": "1,2,3,4,5,6,0",
 
       "delivery_days": "1,2,3,4,5,6,0",
−
       "unique_code": null,
+
       "unique_code": null, //тут может быть GUID
−
       "quantum": 0.5,
+
       "quantum": 5.000,
 
       "isImport": "1",
 
       "isImport": "1",
−
       "minQuantity": 5.500,
+
       "minQuantity": 5.000,
 
       "status": 1
 
       "status": 1
 
     }
 
     }
 
  ]
 
  ]
  
−
===Offers Request (изменение)===
+
====Offers Import Response====
 +
{| class="wikitable"
 +
|-
 +
! Name !! Description !! Schema !! Example
 +
|-
 +
| '''id''' || Идентификатор очереди || string || 5d720cfee9d7c84ad038ff41
 +
|-
 +
| '''count''' || Количество предложений || integer || 2
 +
|-
 +
| '''comment''' || Комментарий || string || null
 +
|}
 +
Пример ответа:
 +
  {
 +
      "id": "5d720cfee9d7c84ad038ff41",
 +
      "count": 2,
 +
      "comment": null
 +
  }
 +
 
 +
===Изменение предложений===
 +
PUT /offers/{sku}
 +
 
 +
====Offers Request (изменение)====
 
{| class="wikitable"
 
{| class="wikitable"
 
! style="font-weight:bold;" | Name
 
! style="font-weight:bold;" | Name
Строка 320: Строка 360:
 
| style="font-weight:bold;" | name
 
| style="font-weight:bold;" | name
 
| Название предложения
 
| Название предложения
−
| string
+
| varchar(255)
 
| product1
 
| product1
 
|-
 
|-
 
| style="font-weight:bold;" | manufacturer
 
| style="font-weight:bold;" | manufacturer
 
| Производитель
 
| Производитель
−
| string
+
| varchar(255)
 
| null
 
| null
 
|-
 
|-
 
| style="font-weight:bold;" | quantity
 
| style="font-weight:bold;" | quantity
−
| Количество
+
| Количество '''Для учета остатков. 0 (нет в наличии), 1 или более (есть в наличии).'''
−
| string
+
| smallint(6)
−
| 1
+
| 1 / 0
 
|-
 
|-
 
| style="font-weight:bold;" | expires_at
 
| style="font-weight:bold;" | expires_at
 
| Годен до
 
| Годен до
−
| string
+
| int(10)
−
| null
+
| null / unixtimestamp
 
|-
 
|-
 
| style="font-weight:bold;" | price_1
 
| style="font-weight:bold;" | price_1
−
| Цена 1 (для магазинов)
+
| Цена 1 (для торговых точек в типом Магазин)
−
| string
+
| decimal(19,2)
−
| 555
+
| float / null
 
|-
 
|-
 
| style="font-weight:bold;" | price_2
 
| style="font-weight:bold;" | price_2
−
| Цена 2 (для HoReCa)
+
| Цена 2 (для для торговых точек в типом HoReCa)
−
| string
+
| decimal(19,2)
−
| null
+
| float / null
 
|-
 
|-
 
| style="font-weight:bold;" | price_3
 
| style="font-weight:bold;" | price_3
−
| Цена 3 (для рынков)
+
| Цена 3 (для для торговых точек в типом Рынок)
−
| string
+
| decimal(19,2)
−
| null
+
| float / null
 
|-
 
|-
 
| style="font-weight:bold;" | price_4
 
| style="font-weight:bold;" | price_4
−
| Цена 4
+
| Цена 4 (только в случае заведения Акции)
−
| string
+
| decimal(19,2)
−
| null
+
| float / null
 
|-
 
|-
 
| style="font-weight:bold;" | price_5
 
| style="font-weight:bold;" | price_5
−
| Цена 5
+
| Выгодная цена
−
| string
+
| decimal(19,2)
−
| null
+
| float / null
 
|-
 
|-
 
| style="font-weight:bold;" | status
 
| style="font-weight:bold;" | status
Строка 370: Строка 410:
 
| style="font-weight:bold;" | quantum
 
| style="font-weight:bold;" | quantum
 
| Квант
 
| Квант
−
| string
+
| decimal(19,3)
 
| 8.0
 
| 8.0
 +
|-
 +
| style="font-weight:bold;" | minQuantity
 +
| Минимальное количество товара для заказа
 +
| decimal(19,3)
 +
| null
 +
|-
 +
| style="font-weight:bold;" | status
 +
| Активность предложения (да/нет) '''Если нужно скрыть товарную карточку из каталога, то выставляем 0 (нет).'''
 +
| tinyint(1)
 +
| 1 / 0
 
|}
 
|}
 
Пример запроса:
 
Пример запроса:
Строка 387: Строка 437:
 
       "status": 1
 
       "status": 1
 
       "quantum": 8.0,
 
       "quantum": 8.0,
 +
      "minQuantity": null, //нет требования по минимальному количеству в заказе
 +
      "status": 1
 
   }
 
   }
 
  ]
 
  ]
  
−
===Offers Import Response===
+
====Offers Response====
−
{| class="wikitable"
+
'''NB!''' Ответ приходит в json и по факту это string. За парсинг и выбор типа значений отвечает сторона поставщика.
−
|-
 
−
! Name !! Description !! Schema !! Example
 
−
|-
 
−
| '''id''' || Идентификатор наименования || integer($int32) || 5d720cfee9d7c84ad038ff41
 
−
|-
 
−
| '''count''' || Количество предложений || integer($int32) || 2
 
−
|-
 
−
| '''comment''' || Комментарий || string || null
 
−
|}
 
−
Пример ответа:
 
−
  {
 
−
      "id": "5d720cfee9d7c84ad038ff41",
 
−
      "count": 2,
 
−
      "comment": null
 
−
  }
 
−
 
 
−
===Offers Response===
 
 
{| class="wikitable"
 
{| class="wikitable"
 
! style="font-weight:bold;" | Name
 
! style="font-weight:bold;" | Name
Строка 416: Строка 451:
 
|-
 
|-
 
| style="font-weight:bold;" | id
 
| style="font-weight:bold;" | id
−
| Идентификатор наименования предложения
+
| Идентификатор наименования предложения в системе SmartSatu
−
| integer($int32)
+
| integer
 
| 4317231
 
| 4317231
 
|-
 
|-
Строка 426: Строка 461:
 
|-
 
|-
 
| style="font-weight:bold;" | sku
 
| style="font-weight:bold;" | sku
−
| Штрих-код предложения
+
| Артикул предложения
 
| string
 
| string
 
| 4870007151458
 
| 4870007151458
Строка 433: Строка 468:
 
| Единица измерения предложения
 
| Единица измерения предложения
 
| string
 
| string
−
| null
+
| шт
 
|-
 
|-
 
| style="font-weight:bold;" | manufacturer
 
| style="font-weight:bold;" | manufacturer
Строка 443: Строка 478:
 
| Количество
 
| Количество
 
| string
 
| string
−
| 0
+
| 1
 
|-
 
|-
 
| style="font-weight:bold;" | expires_at
 
| style="font-weight:bold;" | expires_at
Строка 463: Строка 498:
 
| Цена 3 (для рынков)
 
| Цена 3 (для рынков)
 
| string
 
| string
−
| 329
+
| null
 
|-
 
|-
 
| style="font-weight:bold;" | price_4
 
| style="font-weight:bold;" | price_4
Строка 476: Строка 511:
 
|-
 
|-
 
| style="font-weight:bold;" | unique_code
 
| style="font-weight:bold;" | unique_code
−
| Уникальный код предложения
+
| Уникальный код предложения '''Идентификатор предложения у поставщика'''
 
| string
 
| string
 
| 141209
 
| 141209
 
|-
 
|-
 
| style="font-weight:bold;" | product_id
 
| style="font-weight:bold;" | product_id
−
| Идентификатор продукта
+
| Идентификатор продукта (идентификатор товарной карточки в системе SmartSatu)
 
| string
 
| string
 
| 28952
 
| 28952
 
|-
 
|-
 
| style="font-weight:bold;" | step
 
| style="font-weight:bold;" | step
−
| Шаг
+
| Квант поставки (quantum)
 
| string
 
| string
 
| null
 
| null
Строка 494: Строка 529:
 
| string
 
| string
 
| null
 
| null
−
|-
 
−
| style="font-weight:bold;" | price
 
−
| Цена для текущей ТТ
 
−
| string
 
−
| 329
 
 
|}
 
|}
 
Пример ответа:
 
Пример ответа:
Строка 507: Строка 537:
 
     "name": "425МЛ ЗЕЛЕНЫЙ ГОРОШЕК GREEN GA",
 
     "name": "425МЛ ЗЕЛЕНЫЙ ГОРОШЕК GREEN GA",
 
     "sku": 870007151458,
 
     "sku": 870007151458,
−
     "unit": "",
+
     "unit": "шт",
 
     "manufacturer": "",
 
     "manufacturer": "",
−
     "quantity": 0,
+
     "quantity": 1,
 
     "expires_at": null,
 
     "expires_at": null,
 
     "price_1": 329,
 
     "price_1": 329,
 
     "price_2": 329,
 
     "price_2": 329,
−
     "price_3": 329,
+
     "price_3": null,
 
     "price_4": null,
 
     "price_4": null,
 
     "price_5": null,
 
     "price_5": null,
−
     "unique_code": "151885",
+
     "unique_code": "141209",
 
     "product_id": null,
 
     "product_id": null,
 
     "step": null,
 
     "step": null,
−
     "minQuantity": null,
+
     "minQuantity": null
−
    "price": 329,
 
 
   }
 
   }
 
  ]
 
  ]
  
−
===Delete Offer===
+
===Удаление предложений===
 +
DELETE /offers/{sku}
 +
====Delete Offer====
 
{| class="wikitable"
 
{| class="wikitable"
 
! style="font-weight:bold;" | Name
 
! style="font-weight:bold;" | Name
Строка 533: Строка 564:
 
| style="font-weight:bold;" | status
 
| style="font-weight:bold;" | status
 
| Код
 
| Код
−
| string
+
| integer
 
| 204
 
| 204
 
|-
 
|-
Строка 566: Строка 597:
 
| style="font-weight:bold;" | code
 
| style="font-weight:bold;" | code
 
| Код
 
| Код
−
| integer($int32)
+
| integer
 
| 0
 
| 0
 
|-
 
|-
 
| style="font-weight:bold;" | status
 
| style="font-weight:bold;" | status
 
| Статус
 
| Статус
−
| integer($int32)
+
| integer
 
| 401
 
| 401
 
|-
 
|-
Строка 587: Строка 618:
 
   "type": "yii\\web\\UnauthorizedHttpException"
 
   "type": "yii\\web\\UnauthorizedHttpException"
 
  }
 
  }
 +
 
===403===
 
===403===
 
{| class="wikitable"
 
{| class="wikitable"
Строка 606: Строка 638:
 
| style="font-weight:bold;" | code
 
| style="font-weight:bold;" | code
 
| Код
 
| Код
−
| integer($int32)
+
| integer
 
| 0
 
| 0
 
|-
 
|-
 
| style="font-weight:bold;" | status
 
| style="font-weight:bold;" | status
 
| Статус
 
| Статус
−
| integer($int32)
+
| integer
 
| 403
 
| 403
 
|-
 
|-
Строка 627: Строка 659:
 
   "type": "yii\\\\web\\\\HttpException"
 
   "type": "yii\\\\web\\\\HttpException"
 
  }
 
  }
 +
 
===404===
 
===404===
 
{| class="wikitable"
 
{| class="wikitable"
Строка 646: Строка 679:
 
| style="font-weight:bold;" | code
 
| style="font-weight:bold;" | code
 
| Код
 
| Код
−
| integer($int32)
+
| integer
 
| 0
 
| 0
 
|-
 
|-
 
| style="font-weight:bold;" | status
 
| style="font-weight:bold;" | status
 
| Статус
 
| Статус
−
| integer($int32)
+
| integer
 
| 404
 
| 404
 
|-
 
|-

Текущая версия на 05:40, 2 июня 2022

Обзор

Данный документ описывает методы для работы поставщика/дистрибьютора по получению списка предложений, а также изменению, удалению и импорту предложений в системе 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?start=1&end=1, в запросе к которому передается массив товаров (sku либо unique_code) с актуальными значениями остатков: 

[
   {
      "sku": null,
      "unique_code": "48700034204351",
      "quantity": 30,
   }
]

Для обновления остатков в определенном персональном прайслисте необходимо в параметре store_id указать идентификатор торговой точки: https://food.smartsatu.com/api/offers/import-only-quantity?start=1&end=1&store_id=9576

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

Для того чтобы изменить предложение, необходимо отправить 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 Количество Для учета остатков. 0 (нет в наличии), 1 или более (есть в наличии). 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"
}
Источник — https://docs.smartsatu.com/wiki/index.php?title=API_Offers&oldid=1653