Внешний API СуперМаг DS предназначен для интеграции платформы с внешними информационными системами, в том числе с товароучётными системами. С помощью API внешние системы могут передавать в СуперМаг DS данные о связанных справочниках, товарах, ценах и о локациях и торговых объектах. Данные используются, в частности, при работе с электронными ценниками и промо-дисплеями.
API позволяет работать с основными объектами:
В этой статье описаны основные операции с товарными категориями, товарами и ценами. Подробные параметры методов, структуры запросов и ответов приведены в Swagger-документации.
Примечание. API развивается, поэтому состав методов, параметры и структуры данных могут изменяться. Перед настройкой интеграции сверяйтесь с актуальной Swagger-документацией.
Для регистрации устройств и настройки контента необходим доступ к личному кабинету СуперМаг DS. Для работы с API создайте отдельного пользователя с ролью Внешняя система:
1. Авторизуйтесь в СуперМаг DS (учётные данные предоставляет Ритейл Софт).
2. Перейдите в Справочники, подраздел Пользователи.
3. Нажмите Создать.
4. Укажите имя, email и пароль.
5. Выберите роль Внешняя система.
6. Сохраните изменения.
Например,
Имя: klient_1
Email: klient_1@mail.ru
Пароль: e8bdd3fa-7a10-4817-a4cc-33ddde7e6021
Роль: Внешняя система
Для запросов по API необходимо использовать авторизацию Base64.
1. Введите ваш пароль и закодируйте данные в SHA-256 (например, тут).
2. Скопируйте полученный хэш.
3. Соедините email и хэш_пароль, используя разделитель ":" без пробелов.
В данном примере получаем следующие данные:
klient_1@mail.ru:9e6161665cd8eb6d3b9b1cb15547519b8ec1bb984fd7c68f8dc67bb78fcdb56b
4. Закодируйте полученные данные (email:хэш_пароль) в Base64 (например, тут).
1. Для проверки запросов можно использовать Postman.
2. Authorization:
2.1. Выберете тип авторизации Basic Auth.
2.2. В поле логина введите email, который указан в созданном пользователе с ролью Внешняя система на платформе DS.
2.3. В поле пароля введите преобразованный пароль в SHA256. 
3. Headers:
3.1. Добавьте Authorization:
3.2. Добавьте Conent-Type и выберете значение application/json.
4. Нажмите Send для выполнения запроса.
5. Проверьте ответ.
API ExternalCategoryEndpoints позволяет создавать, изменять и удалять товарные категории. Также предусмотрена пакетная загрузка категорий без построения дерева и применение загруженных изменений и формирование дерева категорий.
Подробная структура запроса приведена в Swagger-документации.
Для создания новой категории или изменения существующей выполните POST-запрос:
{Внешний адрес сервера}/partner/{partnerId}/api/2.0/category/{code}
Метод позволяет:
В запросе передаются основные сведения о категории, включая её наименование и при необходимости родительскую категорию.
Для удаления категории выполните DELETE-запрос:
{Внешний адрес сервера}/partner/{partnerId}/api/2.0/category/{categoryId}
Метод позволяет удалить указанную категорию на основании её идентификатора.
При удалении категории вместе с ней будут удалены все связанные подкатегории и товары. |
Для загрузки большого количества категорий за один сценарий обмена выполните POST-запрос:
{Внешний адрес сервера}/partner/{partnerId}/api/2.0/category/batch-load
Метод позволяет:
Благодаря этому справочник можно передавать частями, а структуру категорий формировать только после завершения загрузки.
После завершения пакетной загрузки необходимо применить загруженные данные – выполните POST-запрос:
{Внешний адрес сервера}/partner/{partnerId}/api/2.0/category/commit
Метод позволяет:
API ExternalGoodEndpoints позволяет создавать, изменять, удалять и искать товары, устанавливать цены в торговом объекте и загружать изображения на товар.
Подробная структура запроса приведена в Swagger-документации.
Для создания нового товара или изменения существующего выполните POST-запрос:
{Внешний адрес сервера}/partner/{partnerId}/api/2.0/good/{sku}
Метод позволяет:
Для удаления товара выполните DELETE-запрос:
{Внешний адрес сервера}/partner/{partnerId}/api/2.0/good/{sku}
Метод позволяет удалить выбранный товар на основании его идентификатора.
Для того чтобы установить цену на товар в выбранном торговом объекте выполните POST-запрос:
{Внешний адрес сервера}/partner/{partnerId}/api/2.0/good/{sku}/location/{locationCode}/price
Метод позволяет обновить данные существующего товара по его SKU для конкретного торгового объекта, включая цену, PLU (номер на весах), QR-код и параметры кампании.
Для того чтобы загрузить изображение для товара выполните POST-запрос:
{Внешний адрес сервера}/partner/{partnerId}/api/2.0/good/{sku}/image/{name}
Метод позволяет загрузить изображение для существующего товара с указанным SKU.
Для того чтобы найти товар по названию или sku выполните POST-запрос:
{Внешний адрес сервера}/partner/{partnerId}/api/2.0/good/query
При успешном выполнении запроса сервер возвращает HTTP-код 200.
В зависимости от метода также могут возвращаться:
При получении ошибки проверьте параметры запроса и текст ответа сервера.
API поддерживает механизм подтверждения успешной обработки запросов:
1. В случае получения ошибки, не указанной в явном виде в схеме Swagger, за исключением ошибки 500, клиент может повторять запрос до тех пор, пока не получит ответ 200 OK.
2. Общее количество запросов от клиента не должно превышать 10 запросов в секунду.
3. На стороне СуперМаг DS могут быть добавлены дополнительные обработчики, отслеживающие превышение указанного количества запросов, приводящее к отправке системного кода ошибки в соответствии с общей спецификации HTTP;.
4. Для диагностики ошибок используются идентификаторы транзакций.
5. Необходимо сохранять параметры оригинального запроса для повторной отправки.
Ритейл Софт, как поставщик решения, обязуется выполнять требования, предлагаемые к клиентам, при увеличении их числа.