1. Назначение API

Внешний API СуперМаг DS предназначен для интеграции платформы с внешними информационными системами, в том числе с товароучётными системами. С помощью API внешние системы могут передавать в СуперМаг DS данные о связанных справочниках, товарах, ценах и о локациях и торговых объектах. Данные используются, в частности, при работе с электронными ценниками и промо-дисплеями.

API позволяет работать с основными объектами:

• Товарные категории – создавать, изменять, выполнять пакетную загрузку без построения дерева, применять загруженные изменения и формировать дерево категорий, а также удалять категории.
• Товары – создавать, изменять, удалять и искать товары, устанавливать цены в торговом объекте и загружать изображения на товар.
• Торговые объекты – создавать, изменять, искать и удалять торговые объекты.
• Локации – создавать, изменять, искать и удалять локации.

В этой статье описаны основные операции с товарными категориями, товарами и ценами. Подробные параметры методов, структуры запросов и ответов приведены в Swagger-документации.

Примечание. API развивается, поэтому состав методов, параметры и структуры данных могут изменяться. Перед настройкой интеграции сверяйтесь с актуальной Swagger-документацией.

2. Доступ к API

2.1. Доступ к личному кабинету СуперМаг DS 

Для регистрации устройств и настройки контента необходим доступ к личному кабинету СуперМаг DS. Для работы с API создайте отдельного пользователя с ролью Внешняя система:

1. Авторизуйтесь в СуперМаг DS (учётные данные предоставляет Ритейл Софт).

2. Перейдите в Справочники, подраздел Пользователи.

3. Нажмите Создать.

4. Укажите имя, email и пароль.

5. Выберите роль Внешняя система.

6. Сохраните изменения. 

Например, 

Имя: klient_1

Email: klient_1@mail.ru

Пароль: e8bdd3fa-7a10-4817-a4cc-33ddde7e6021

Роль: Внешняя система

2.2. Подготовка данных для авторизации 

Для запросов по API необходимо использовать авторизацию Base64. 

1. Введите ваш пароль и закодируйте данные в SHA-256 (например, тут). 

2. Скопируйте полученный хэш.

3. Соедините email и хэш_пароль, используя разделитель ":" без пробелов.

В данном примере получаем следующие данные:

klient_1@mail.ru:9e6161665cd8eb6d3b9b1cb15547519b8ec1bb984fd7c68f8dc67bb78fcdb56b

4. Закодируйте полученные данные (email:хэш_пароль) в Base64 (например, тут). 

2.3. Настройка запроса

1. Для проверки запросов можно использовать Postman. 

• В качестве адреса сервера используйте: http://194.154.87.20:59005.
• В URL запросов также передаётся partnerId (уникальный идентификатор партнёра). Его значение можно определить по URL личного кабинета СуперМаг DS.

2. Authorization:

  2.1. Выберете тип авторизации Basic Auth.

  2.2. В поле логина введите email, который указан в созданном пользователе с ролью Внешняя система на платформе DS. 

  2.3. В поле пароля введите преобразованный пароль в SHA256. 

3. Headers:

   3.1. Добавьте Authorization: 

• Впишите Basic.
• Вставьте закодированную форму email:хэш_пароль в Base64.

   3.2. Добавьте Conent-Type и выберете значение application/json.

4. Нажмите Send для выполнения запроса.

5. Проверьте ответ.

3. Управление товарными категориями

API ExternalCategoryEndpoints позволяет создавать, изменять и удалять товарные категории. Также предусмотрена пакетная загрузка категорий без построения дерева и применение загруженных изменений и формирование дерева категорий.

Подробная структура запроса приведена в Swagger-документации.

3.1. Создание или изменение категории 

Для создания новой категории или изменения существующей выполните POST-запрос:

{Внешний адрес сервера}/partner/{partnerId}/api/2.0/category/{code}

• partnerId – идентификатор партнёра.
• code – код категории.

Метод позволяет:

1. Создать новую категорию товаров.
2. Обновить данные существующей категории товаров.

В запросе передаются основные сведения о категории, включая её наименование и при необходимости родительскую категорию. 

3.2. Удаление категории 

Для удаления категории выполните DELETE-запрос: 

{Внешний адрес сервера}/partner/{partnerId}/api/2.0/category/{categoryId}

• partnerId – идентификатор партнёра.
• categoryId – идентификатор категории. 

Метод позволяет удалить указанную категорию на основании её идентификатора.

3.3. Пакетная загрузка категорий

Для загрузки большого количества категорий за один сценарий обмена выполните POST-запрос:

{Внешний адрес сервера}/partner/{partnerId}/api/2.0/category/batch-load

• partnerId – идентификатор партнёра.

Метод позволяет:

1. Создать категории без построения дерева.
2. Сохранить категории во временной области (staging).

Благодаря этому справочник можно передавать частями, а структуру категорий формировать только после завершения загрузки.

3.4. Применение изменений 

После завершения пакетной загрузки необходимо применить загруженные данные – выполните POST-запрос:

{Внешний адрес сервера}/partner/{partnerId}/api/2.0/category/commit

• partnerId – идентификатор партнёра.

Метод позволяет:

1. Применить изменения, ранее загруженные в staging.
2. Сформировать актуальное дерево товарных категорий.

4. Управление товарами

API ExternalGoodEndpoints позволяет создавать, изменять, удалять и искать товары, устанавливать цены в торговом объекте и загружать изображения на товар.

Подробная структура запроса приведена в Swagger-документации.

4.1. Создание или изменение 

Для создания нового товара или изменения существующего выполните POST-запрос:

{Внешний адрес сервера}/partner/{partnerId}/api/2.0/good/{sku}

• partnerId – идентификатор партнёра.
• sku – идентификатор товара.

Метод позволяет:

1. Добавить новый товар.
2. Обновить данные существующего товара по его SKU.

4.2. Удаление товара 

Для удаления товара выполните DELETE-запрос: 

{Внешний адрес сервера}/partner/{partnerId}/api/2.0/good/{sku}

• partnerId – идентификатор партнёра.
• sku – идентификатор товара.

Метод позволяет удалить выбранный товар на основании его идентификатора.

4.3. Изменение цены на товар в выбранном торговом объекте 

Для того чтобы установить цену на товар в выбранном торговом объекте выполните POST-запрос:

{Внешний адрес сервера}/partner/{partnerId}/api/2.0/good/{sku}/location/{locationCode}/price

• partnerId – идентификатор партнёра.
• sku – идентификатор товара.
• locationCode - идентификатор торгового объекта.

Метод позволяет обновить данные существующего товара по его SKU для конкретного торгового объекта, включая цену, PLU (номер на весах), QR-код и параметры кампании.

4.4. Изменение изображения товара 

Для того чтобы загрузить изображение для товара выполните POST-запрос:

{Внешний адрес сервера}/partner/{partnerId}/api/2.0/good/{sku}/image/{name}

• partnerId – идентификатор партнёра.
• sku – идентификатор товара.
• name – имя изображения.

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

4.5. Поиск товара 

Для того чтобы найти товар по названию или sku выполните POST-запрос:

{Внешний адрес сервера}/partner/{partnerId}/api/2.0/good/query

• partnerId – идентификатор партнёра.

5. Ответы API

При успешном выполнении запроса сервер возвращает HTTP-код 200.

В зависимости от метода также могут возвращаться:

• 400 – неверный формат запроса.
• 401 – ошибка авторизации.
• 500 – ошибка выполнения запроса.

При получении ошибки проверьте параметры запроса и текст ответа сервера.

6. Гарантия доставки 

API поддерживает механизм подтверждения успешной обработки запросов:

• При успешном выполнении запроса возвращается HTTP-код 200.
• Система гарантирует обработку запросов в порядке поступления.

7. Рекомендации 

1. В случае получения ошибки, не указанной в явном виде в схеме Swagger, за исключением ошибки 500, клиент может повторять запрос до тех пор, пока не получит ответ 200 OK.

2. Общее количество запросов от клиента не должно превышать 10 запросов в секунду.

3. На стороне СуперМаг DS могут быть добавлены дополнительные обработчики, отслеживающие превышение указанного количества запросов, приводящее к отправке системного кода ошибки в соответствии с общей спецификации HTTP;.

4. Для диагностики ошибок используются идентификаторы транзакций.

5. Необходимо сохранять параметры оригинального запроса для повторной отправки.

Ритейл Софт, как поставщик решения, обязуется выполнять требования, предлагаемые к клиентам, при увеличении их числа.