Интеграция с сайтом

Система ShopManager позволяет произвести интеграцию с вашим сайтом.
Поддерживается автоматическое обновление на вашем сайте цен и наличия товаров.

Иными словами, как только у вас обновляется любой из прайс-листов, и пересчитываются розничные цены, цены будут автоматически меняться и на вашем сайте!

Для настройки автоматического обновления цен на вашем сайте, необходимо установить на ваш сайт два скрипта, вы можете сделать это с помощью ваших программистов или мы это сделаем для вас.

Скрипт №1 - выгрузка списка товаров

В большинстве случаев создание скрипта №1 не требуется, и в качестве источника списка товаров может выступать ваш YML фид, если он присутствует у вас на сайте. Также для некоторых движков сайтов у нас есть готовые модули интеграции, уточните в службе тех. поддержки, есть ли готовый модуль для вашего движка сайта.

Для реализации выгрузки списка товаров с вашего сайта по API, требуется реализовать на стороне вашего сайта скрипт, который будет обрабатывать POST запросы, и отдавать в JSON формате информацию о списке категорий и товаров на вашем сайте. Адрес данного скрипта необходимо будет сообщить в службу тех. поддержки. В заголовке всех запросов будет передаваться параметр SMKey - секретный ключ, который вам необходимо проверять, чтобы избежать несанкцианированного обращения к вашему скрипту.

Для передачи списка категорий, в POST запросе будет отправлено следующее содержимое: {"action": "export_categories"}

В ответ необходимо отправить JSON объект следующего вида:

1
2
3
4
5
6
7
8
{
"status": 0,
"categories": [
{"id": "20", "name": "Техника для кухни"},
{"id": "21", "name": "Кофемашины", "parent_id": "20"},
{"id": "22", "name": "Яйцеварки", "parent_id": "20"}
]
}

Проверьте корректность работы вашего срипта с помощью Postman или утилиты curl:

1
curl -k -H "SMKey: 3J5B0PGG1YnKAnWoNahJL4Zk" -d '{"action": "export_categories"}' 'http://megashop.by/api/sm-sync.php'

Для передачи списка товаров, в POST запросе будет отправлено следующее содержимое: {"action": "export_products", "limit": 100, "offset": 0} где атрибуты limit и offset указывают на количество товаров которое нужно вернуть в ответ и сдвиг.

В ответ необходимо отправить JSON объект следующего вида:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
"status": 0
"products": [
{
"id": "42",
"categoriesIds": [21],
"manufacturer": "Saeco",
"name": "Saeco Lirika OTC [RI9851/01]",
"sku": "RI9851/01",
"url": "http://megashop.by/coffee/saeco/ri985101"
"price": "10.00",
"quantity": "100",
}
]
}

Проверьте корректность работы вашего срипта с помощью Postman или утилиты curl:

1
curl -k -H "SMKey: 3J5B0PGG1YnKAnWoNahJL4Zk" -d '{"action": "export_products", "limit": 100, "offset": 0}' 'http://megashop.by/api/sm-sync.php'

Скрипт №2 - обновление цены и наличия товара (push модель)

При изменении цены товара или наличия в сводном прайсе в ShopManager, эти изменения должны тут же отразиться на вашем сайте. Для этого, со стороны ShopManager в сторону вашего сайта будет отправляться POST запрос к скрипту (push модель). В запросе будет передаваться список измененных товаров.

Для каждого товара будут передаваться его идентификатор, новая цена и наличие.
Формат передаваемых по ссылке данных, приведен в разделе “Формат данных”.

Отправка обновления происходит в двух случаях:

  1. когда вы вручную меняете цену на какойто один или несколько товаров - тогда вам на сайт отправляются только эти измененные товары
  2. когда вы пересчитываете сводный прайс или добавляете прайс поставщика в сводный - тогда происходит полная перевыгрузка, отправляются все ваши товары

В запросе отправляется заголовок (header) с именем SMSyncType который может принимать значения partial (для сценария 1) и full (для сценария 2)

Скрипт должен найти каждый измененный товар в базе и обновить цену и наличие (если цена или наличие изменилось, если не изменились, то обновлять не нужно, чтобы снизить нагрузку на вашу БД).
В ответ должен вернуться результат в формате JSON в котором будет следующая информация:

1
2
3
4
5
6
{
"status": 0,
"updateCount": 5,
"skipCount": 1,
"errorCount": 2
}

Для того чтобы данный скрипт не могли вызвать злоумышленники, в каждом запросе передается секретный ключ (значение ключа вы можете уточнить у службы поддержки), который нужно проверять, если ключ не совпал, нужно вернуть $STATUS_UNAUTORIZED:

1
2
3
4
5
6
7
$STATUS_OK = 0;
$STATUS_UNAUTORIZED = 100;
$STATUS_ERROR = 101;
if ($_SERVER['HTTP_SMKEY'] != 'secret01') {
header('SMRESULT: ' . json_encode(array('status' => $STATUS_UNAUTORIZED)));
exit;
}

Весь скрипт нужно завернуть в конструкцию try-catch, и в случае, если свалилась ошибка, вернуть статус $STATUS_ERROR

Для отладки интеграции, мы рекомендуем использовать утилиту curl или Postman. Пример отправки запроса утилитой curl:

1
curl -d '{"products":[{"id":"653","price":"12.63","inStock":1,"delivery":{}}]}' -H "SMKey: 3J5B0PGG1YnKAnWoNahJL4Zk" -X POST http://megashop.by/api/sm-sync.php

Скрипт №2 - обновление цены и наличия товара (pull модель)

Для некоторых CMS, рациональнее обновлять цены и наличие на сайте, с применением pull модели, т.е. с определенной периодичностью (например дважды в сутки) скачивать с ShopManager актуальный список товаров и цен, и производить их обновление на вашем сайте.

Для получения списка всех товаров с актуальными ценами и наличием (в формате JSON) используется ссылка:

https://my.shopmanager.by/d/api/site-export.json?shopId=XXX&key=YYY

XXX - ID вашего магазина
YYY - API ключ

Скопировать данную ссылку (а также, сгенерировать новый API ключ) вы можете в личном кабинете ShopManager в разделе “Профиль”.

Формат передаваемых по ссылке данных, приведен в разделе “Формат данных”.

Формат данных

Данные передаются в формате JSON, пример:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
"products": [
{
"id": "28",
"inStock": 1,
"price": 830.01,
"delivery": {"tt": 1, "tp": 5, "ct": 5, "cp": 15}
},
{
"id": "29",
"inStock": 1,
"price": 840.01,
"delivery": {"tt": 1, "tp": 5, "ct": 5, "cp": 15}
}
],
"staledProductsIds":["30", "31"]
}

Значения, которые принимает параметр inStock: 0 - под заказ, 1 - В наличии, 2 - нет в наличии, 3 - не определен;

В поле delivery содержится информация о доставке:

В массиве staledProductsIds передается список идентификаторов товаров, которые пропали из продажи (отсутствуют в прайсах поставщиков и в сводном прайсе).

В случае необходимости (включается по запросу), товары в выгрузке могут разбиваться на пакеты, чтобы снизить нагрузку на хостинг. Вместо отправки всех изменений цен и наличия одним запросом, товары разбиваются на группы по N товаров в группе, и отправляются отдельными запросами. При этом дополнительно передается атрибут batchIndex - индекс группы, начиная с 0.

В случае необходимости (включается по запросу), в выгрузку мы так-же можем передавать дополнительную информацию: оптовую цену товара, МРЦ, имя поставщика, курс и др.

В случае расширенной выгрузки, данные передаются в следующем виде:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
"products": [
{
"id": 28,
"inStock": 1,
"price": 830.01,
"delivery": {"tt": 1, "tp": 5, "ct": 5, "cp": 15},
"fixedPrice": 830.01,
"floorPrice": 999,
"origPrice": 750,
"priceId": 123,
"origStock": "4+",
"stock": 5
}
],
"staledProductsIds":["30", "31"],
"prices": [
"id": 123,
"fileName": "оптрон-наличие.xls",
"exchangeRate": 1,
"priceConfigName": "Оптрон"
]
}

Таким образом, в выгрузку по каждому товару попадают следующие дополнительные поля:

Для каждого поставщика товаров, передаются поля: