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

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

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

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

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

Операции с торговыми объектами и локациями здесь не рассматриваются. Подробное описание соответствующих методов приведено в Swagger-документации.

Примечание. Перед настройкой интеграции используйте документацию, соответствующую версии СуперМаг DS.

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 (если вам предоставлен доступ к тестовому контуру).
  • https://ds.retail-soft.pro:51086 (если вам предоставлен доступ к продуктивной среде).
• В URL запросов также передаётся partnerId (уникальный идентификатор партнёра). Его значение можно определить по URL личного кабинета СуперМаг DS.

2. Настройка авторизации (Authorization):

  2.1. Перейдите во вкладку Authorization. 

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

  2.2. Заполните поля:

• Username – email пользователя с ролью "Внешняя система", созданного на платформе DS.
• Password – пароль пользователя, предварительно преобразованный в хэш SHA256.

3. Настройка заголовков (Headers):

   3.1. Перейдите во кладку Headers.

   3.2. Добавьте заголовки: 

• Authorization – впишите Basic и вставьте закодированную форму email:хэш_пароль в Base64.
• Conent-Type – выберете значение application/json.

4. Заполните тело запроса (если выбранный метод API предусматривает передачу тела запроса):

  4.1. Перейдите во вкладку Body.

  4.2. Выберите тип raw.

  4.3. В выпадающем списке формата выберите JSON.

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

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

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

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.3.1. Передача данных кампании 

При изменении цены для товара в торговом объекте можно передать параметры кампании. 

Кампания определяет ценовые данные товара и используется при выборе подходящей формы отображения. Поддерживаются следующие варианты кампаний:

1. Шаблон 1, Шаблон 2, Шаблон 3: позволяют использовать разные варианты оформления регулярной или акционной цены.

• Для кампаний доступны поля: Цена, Старая цена и Скидка.

2. Скидка на N-й товар: позволяет задать специальные условия для определённой по счёту единицы товара.

• Передаются количество товара, скидка, основная цена и цена для N-й единицы.

3. N по цене M: позволяет задать условие, при котором количество N продаётся по стоимости количества M.

• Передаются количество и цена для соответствующих значений N и M.

4. Скидка от количества: позволяет задавать разные цены в зависимости от количества товара.

• Для одной кампании можно передать несколько пар Количество – Цена.

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

После обработки запроса кампания сохраняется для указанного товара и торгового объекта. Тип кампании и заполненные ценовые поля используются при выборе подходящей формы из активного набора.

Точные системные значения типов кампаний, структура объекта extension, названия и типы полей, обязательность параметров и примеры запросов приведены в Swagger-документации. 

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

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

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

• partnerId – идентификатор партнёра.
• sku – идентификатор товара.
• name – имя загружаемого файла вместе с его расширением в формате: "{имя}.{расширение}". При сохранении изображения на стороне DS к указанному имени автоматически добавляется префикс "api. Итоговое имя будет: "api_{имя}.{расширение}".

Метод позволяет загрузить изображение для существующего товара с указанным 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. Необходимо сохранять параметры оригинального запроса для повторной отправки.

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