Вы просматриваете старую версию данной страницы. Смотрите текущую версию.

Сравнить с текущим просмотр истории страницы

« Предыдущий Версия 6 Следующий »

SMP-2097 ID 2464 3.0_Интеграция СуперМаг Плюс и DS_РитейлСофт


SMP: 2097
ID: 2464
SALE: 3226

Техническое задание v.2.
Расширено уточнением перечня полей в выгружаемых данных, которые для ПО DS являются обязательными.


Техническое задание v.3.
Уточнение по поводу нумерации групп классификатора, таблица classif.

  1. Номера групп выгружать в виде дерева (tree).
  2. Корневая группа OWNER должна иметь идентификатор 0. Исторически мы выгружали ранее #.


Техническое задание v.3.
Валидация данных. Справочная информация:
Поступающие проходят этап валидации структуры XML. Правила валидации следующие:

  • Обязательные поля: Проверяется их наличие и строгое соответствие формату данных.
  • Необязательные поля: Их наличие не проверяется.

    Ниже описаны особенности валидации для ключевых типов данных:
    1) Классификатор товаров (classif)
  • Валидация выявляет критические ошибки структуры: 
    • Отсутствие циклических зависимостей (когда узел является собственным родителем)
    • Отсутствие узлов, у которых указан несуществующий родительский id (owner)
    • Уникальность всех узлов 
    • Обязательно наличие узла с id = 0 (Корень дерева)
    • Отсутствие некорневых узлов с пустым owner или равного нулю

      2) Товары (updateItems)
      Битые элементы (товары с ошибками в обязательных полях) вырезаются из исходного файла.
  • Проверяются два новых поля: producer и description. При превышении максимальной длины (255 символов) значения обрезаются. 

    3) QR-коды и Номер на весах (itemInfo)
  • Поля qr и plu являются необязательными. Можно передавать либо только qr, либо только plu, либо оба, либо ни одного (пример: <item article=""></item>).
  • Если поля присутствуют и их длина превышает максимум, элемент (товар) считается невалидным и вырезается из исходного файла.

    4) Цены (storePrices и priceTagInfo)
  • Битые элементы (с ошибками в обязательных полях) вырезаются из исходного файла.
    **


Бизнес процесс:

Описание: клиенты, использующие СуперМаг Плюс заинтересованы в интеграции с СуперМаг DS для использования прайс-дисплеев и esl-ценников.
Для интеграции СуперМаг Плюс и DS - используется расширенный XML-протокол, с помощью которого сейчас интегрируются УКМ5 и ДС 


Интерфейс и реализация:

В настоящее время УКМ5 интегрируется с СуперМаг DS по следующей схеме (рис.1.):
Рис.1.

Схема интеграции через СуперМаг Плюс претерпит следующие изменения (Рис.2.):
Рис.2.

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

  • Рабочее название.
    Логика работы с ПО Kafka заключается в следующем:
  • Кассовый модуль СуперМаг Плюс подготавливает данные в специализированном формате XML (описан ниже).
  • Полученные данные, модуль «Кассовый модуль СуперМаг Плюс» должен преобразовать и отправить в топик Kafka.


Справка: Apache Kafka — распределённая система обмена сообщениями между серверными приложениями в режиме реального времени. 


Описание форматов обмена:

Формат данных для публикации.

СуперМаг Плюс должен публиковать в Kafka файлы в следующем виде:

{
"content_base64": "здесь содержимое в base64",
"event_type": "F",
"number": "1",
"original_filename": "storePrices_[262][1][F].xml",
"store_id": "262",
"part": "1",
"part_status": "process"
}



content_base64

содержимое Xml файла в кодировке base64 (SKU и цены)

event_type

тип выгрузки (F/I - полная/частичная выгрузка)

number

порядковый номер файла (целое число)

original_filename

Имена файлов имеют формат TAGNAME_[Store][Number][P]_[Error].xml, где:
]]></ac:plain-text-body></ac:structured-macro>
TAGNAME – название выгружаемой информации
Store – код (идентификатор) магазина в торговой системе; может быть переменной длины.
Параметр Store может содержать любые печатные английские символы, кроме символа пробела.
Number – порядковый номер файла с информацией данного типа. Формат номера – целое положительное число.
P – признак полноты информации в файле:

  • F – файл содержит полный перечень элементов ("полная" выгрузка)
  • I – файл содержит неполный перечень элементов ("инкрементальная" выгрузка)
    Error – признак ошибки; устанавливается конвертером в случае возникновения любых ошибок при работе с данным файлом.

store_id

Id магазина во внешней системе
Или "all", если файл содержит список товаров для магазинов.

part

номер части для больших файлов

part_status

статус части. Варианты:

  • process - будут еще части 
  • last - последняя часть, проверить нумерацию и коммитить


Формат данных для обмена:

За основу формата обмена данными взят конвертер СуперМаг XML, с некоторыми изменениями, в частности:

  • Имена файлов должны быть строго такими, как они отражены в описании, иначе конвертер DS их проигнорирует.
  • Структура файлов расширена новыми данными.

Файлы обмена (общий список).

Ниже представлен общий список файлов, которые требуется формировать. Часть файлов (их структура) не претерпела изменений по отношению к конвертеру СуперМаг XML, и не описывается в данном ТЗ.

№

Имя файла

Описание назначения

Комментарий

1.

store

магазины

Новый файл. Ранее СуперМаг плюс такой не формировал.

2.

classif

Классификатор товаров

Без изменений.

3.

updateItems

товары

Файл расширен новыми тегами.

4.

storePrices

цены по месту хранения

Без изменений.

5.

priceTagInfo

акционные цены

Новый файл. Ранее СуперМаг плюс такой не формировал.

6.

itemInfo

QR-коды и PLU

Новый файл. Ранее СуперМаг плюс такой не формировал.


Общее описание

Ниже описывается расширение существующего протокола обмена данными (СуперМаг XML) для создания готового "коробочного" решения, которое позволит клиентам, использующим СуперМаг Плюс, избежать отдельной интеграции с «СуперМаг DS» для использования электронных ценников (ESL) и Прайс-дисплеев.
Ранее данные из Торговой системы выгружались данные исключительно для кассовых систем и систем контроля цен. Теперь этот процесс дополняется: фактически те же самые данные будут параллельно передаваться и в DS. Это позволит системе «СуперМаг DS» получать актуальную информацию о товаре и их ценах.

Описание расширения

  • Наименование файла строго как в описание. (операционная система LINUX регистрозависима)
  • Формат представления информации – XML. 
  • Кодировка – UTF-8.
  • Десятичный разделитель – точка
  • Каждый тип информации передаётся с помощью отдельного файла, который имеет название, соответствующее типу передаваемой информации. В одном файле может содержаться только один тип информации.
      1. Расширение существующих файлов в протоколе: 

        Тип информации

        Имя файла и головного тега

        Магазины

        store

        Товары 

        updateItems

      2. Добавление новых файлов в протокол:


Тип информации

Имя файла и головного тега

Акционные цены на товары

priceTagInfo

QR-коды и PLU

itemInfo

Файл store (магазины)

Наименование файла: store (например, store_[1234]_[I].xml).


Описание изменений: Файл расширяется двумя новыми полями:

  • director — ФИО директора магазина.
  • description — Произвольное текстовое описание или комментарий к магазину.

Описание файла "store":


Примечание

Формат 

Источник данных из СуперМаг Плюс

<stores
fullness="I">


Значение всегда указывается как I !



<version="">


String(20)


<store>




  <code>

Код магазина в торговой системе

String(100)

Код магазина в торговой системе

  <name>

Название магазина

String(100)

Название магазина

  <jurName>

Название юр. лица

String(100)

Собственный контрагент места хранения. Единственный из списка, или первый попавшийся.
Примечание: режим множественности ЮР. Лиц в СуперМаг DS не поддерживается.

  <address>

Адрес магазина

String(100)

Адрес магазина

  <director>

Новое поле: Директор магазина
ФИО директора магазина.

String(100)

Требуется добавить новый атрибут места хранения или создать новую системную характеристику.
Реализация – на усмотрение разработчика.

  <description>

Новое поле: Описание магазина

String(100)

Требуется добавить новый атрибут места хранения или создать новую системную характеристику.
Реализация – на усмотрение разработчика.

  <INN>

ИНН юр. лица

String(40)

ИНН Собственного контрагента.

  <KPP>

КПП

String(40)

КПП Места хранения.

  <phone>

Телефон

String(40)

Телефон Места хранения.

  <active>

Активный/неактивный

Boolean

Фиксированное значение «true»

  <egaisIP>

IP-адрес и порт УТМ

String(255)

Требуется добавить новый атрибут места хранения или создать новую системную характеристику.
Реализация – на усмотрение разработчика.

  <CFA>

Код ЦФО – открытый идентификационный код, определяющий центр финансовой ответственности (идентификатор магазина для казначеев)

String(255)

Требуется добавить новый атрибут места хранения или создать новую системную характеристику.
Реализация – на усмотрение разработчика.

  <validatorIP>

IP-адрес и порт валидатора

String(255)

Требуется добавить новый атрибут места хранения или создать новую системную характеристику.
Реализация – на усмотрение разработчика.

  <localModuleIP>

IP-адрес локального модуля (для обращения в случае отсутствия связи с системой "Честный знак")

String (255)

Требуется добавить новый атрибут места хранения или создать новую системную характеристику.
Реализация – на усмотрение разработчика.

  <fsrarID>

Идентификатор организации в ФС РАР

String(255)

ФС РАР Собственного контрагента.

  <prismaIP>

IP-адрес и порт системы "Трассир"

String(255)

Требуется добавить новый атрибут места хранения или создать новую системную характеристику.
Реализация – на усмотрение разработчика.

  <storeIP>

IP модуля интеграции магазина

String(100)

Требуется добавить новый атрибут места хранения или создать новую системную характеристику.
Реализация – на усмотрение разработчика.

  <inputURL>

Полный URL входного каталога модуля интеграции магазина

String(255)

Требуется добавить новый атрибут места хранения или создать новую системную характеристику.
Реализация – на усмотрение разработчика.

  <outputURL>

Полный URL выходного каталога модуля интеграции магазина

String(255)

Требуется добавить новый атрибут места хранения или создать новую системную характеристику.
Реализация – на усмотрение разработчика.

  <region>

Код региона, к которому относится магазин

Int(11)

Требуется добавить новый атрибут места хранения или использовать новую системную характеристику.
Реализация – на усмотрение разработчика.

Можно выгружать код региона места хранения.

  <storeType>

Код формата магазина из справочника форматов магазинов

Int(11)

Требуется добавить новый атрибут места хранения или создать новую системную характеристику.
Реализация – на усмотрение разработчика.

</store>




</stores>





Файл updateItems (товары)

Наименование файла: updateItems (например: updateItems_[1234]_[F].xml).

Описание изменений: Файл расширяется тремя новыми полями, которые являются необязательными для передачи:

  • producer - Страна производства 
  • description - Описание товара 
  • customType - Атрибут товара


Описание файла "updateItems":


Примечание

Формат 

Источник данных из СуперМаг Плюс

<updateItems
fullness="F/I">


Значение может быть F или I, но всегда будет обрабатывается на стороне СуперМаг DS как I



<version="">


String(20)


<item>




   <article>


String(40)


   <name>


String(255)


   <measure>

Сокращение (шт, кг, л)

String(40)


   <measprec>

Количество знаков в дробной части; точность – 1, 0.001, 0.01, 0.1

String(one of 1; 0.1; 0.01; 0.001)


   <groupId>

Ссылка на узел классификатора

String(40)


   <producer>

Новое поле: Страна производства
Будет использоваться для алкогольной продукции, где необходимо на шаблоне ценника подсветить страну производства. 

String(255)

Страна

   <description>

Новое поле: Описание товара 
Используется для вывода на шаблон информации за какую единицу измерения написана стоимость. Например:

  • Цена за 1 ед. товара
  • Цена за 100 грамм
  • Цена за 1 кг

String(255)

Требуется создать новую системную характеристику.
Рабочее название descriptionDS:
Реализация – на усмотрение разработчика.

   <customType>

Новое поле: Атрибут товара
Значения данного поля будут использоваться для того чтобы применить к товару специальный шаблон. Например, для того чтобы система понимала, что данный товар алкоголь и для него нужно отобразить шаблон с акцентом на стране производителя.

Int(11)
1 – алкоголь 

Требуется создать новую системную характеристику.
Рабочее название customTypeDS:
Реализация – на усмотрение разработчика.

   <egaisType>

Тип маркировки товара

Int(11)


   <SubExcise>

Признак подакцизности товара

Int(11) 


   <crptNotUnique>

Признак неуникальности контрольной марки

0 – уникальная марка
1 – неуникальная марка


   <taxgroupId>

Код налоговой группы



   <propertyId>

Доп. свойство «Размер»

String(40)


   <addProperty>

Доп. свойства



        <id>


String(40)


        <name>


String(80)


        <value>


String(100)


   </addProperty>




   <barcode>

Перечень штрихкодов Один штриховой код товара.



       <id>

Непосредственно штрихкод

String(40)

Первый попавшийся, или тот, что отмечен как «Использовать при EDI обмене \ GTIN»

       <propertyValue>


String(100)


       <quantity>

«Количество» для штрихкода

Decimal(16.3)


   </barcode>




   <TNVDcode>

Идентификатор записи из справочника ТН ВЭД

String(50)


   <productAlcCodes>




      <alcCode>

Специальный идентификатор кода алкогольной продукции

String(40)


</productAlcCodes>




  <supplierLink>




      <supplierINN>

ИНН поставщика

String(12)


      <supplierTax>

НДС поставщика из контракта с поставщиком

Возможные значения: «20%», «10%», «Не облагается»


  </supplierLink>




</item>




</updateItems>





Файл priceTagInfo (акционные цены)

Источником данных для акционных ценников будут выступать документы «Маркетинговая акция».

С помощью данного файла в DS возможно отразить следующие акционные кампании:

№ п.п.

Название компании в DS

Комментарий

1.

Процентная скидка

Реализовано в СМ+ с помощью Маркетинговых акций.

2.

«N по цене M»

Не реализована в СМ+, выгружаться не будет.

3.

«Скидка от количества»

Не реализована в СМ+, выгружаться не будет.


Примечание

Формат 

Источник данных из СуперМаг Плюс


<priceTagInfofullness=  "F/I"storeId =  ""  >

  Значение может быть F или I (обязательное)Код магазина во внешней системе (обязательное)




<item article="">

Код товара (артикул) (секция должна быть указана хотя бы один раз)

String(40)

Артикул из спецификации документа Маркетинговая акция.


description

Название акции (обязательное)

String(100)

Название акции.


dateFrom

Дата и время начала акции

DateTime()

Планируемая Дата и время начала акции


dateTo

Дата и время окончания акции

DateTime()

Панируемая \ или \ Фактическая (при наличии) Дата и время окончания акции


campaigntype

Тип компании. Один из предопределенных: (обязательное) 

  • discountbypercent (процентная скидка)
  • discountnbym (тип скидки «N по цене M»)
  • discountbycount (тип скидки «Скидка от количества»)

String(40)

Фиксированное значение «discountbypercent»

Других типов компаний в торговой системе СуперМаг плюс - нет.


<campaign>






Внутри секции <campaign> настройки кампании, которые зависят от типа кампании (см. таблицы далее)


<campaign>

</campaign>  





</item>





</priceTagInfo>






Секция campaign:

<campaign>

Источник данных из СуперМаг Плюс

    price

цена (обязательное)

Decimal(16.2)Цена артикула из документа Маркетинговая акция.

    oldPrice

старая цена

Decimal(16.2)Старая цена из документа Маркетинговая акция.

    discount

процент скидки

Decimal(16.2)Процент скидки. Требуется рассчитать и округлить до целого числа в меньшую сторону.

</campaign>






Пример:
<priceTagInfo fullness="I" storeId="2">
<version>1.0</version>
<item article="000177">
<description>Покупайте наших слонов</description>
<dateFrom>01.01.2025</dateFrom>
<dateTo>31.12.2025</dateTo>
<campaigntype>discountbypercent</campaigntype><campaign>
<price>45</price>
<oldPrice>50</oldPrice>
<discount>10</discount></campaign>
</item>
</priceTagInfo>

Файл itemInfo (QR-коды и PLU)

Наименование файла: itemInfo (например: itemInfo_[Store]_[Number]_[P].xml)


Примечание

Формат 

Источник данных из СуперМаг Плюс

< itemInfofullness=  "F/I"storeId =     >

  Значение может быть F или IКод магазина во внешней системе (обязательное)



<item article="">

Код товара (артикул) (секция должна быть указана хотя бы один раз)

String(40)


<qr>

содержимое QR-кода для ценника (необязательное) 

String(100)

Не заполняем

<plu>

Код на весах (необязательное) 

String(40)

PLU код из списка товаров для весов по месту хранения.

</item>




</itemInfo>




 

Правила наполнения данными для файла priceTagInfo:

Источником данных для акционных ценников будут выступать документы «Маркетинговая акция».
Следует учитывать, что у данного документа имеются следующие атрибуты, значение которых напрямую может оказывать влияние на цену товара, и как следствие цену на ценнике СуперМаг DS. К атрибутам относится:

  • Планируемая дата начала акции.
  • Планируемая дата окончания акции.
  • Статус «Исполняется». (Статус указывает, что акция стартовала).
  • Фактическая дата окончания акции.

Так же не исключены ситуации, при которых возможно пересечение артикулов в созданных маркетинговых акциях, а также досрочное завершение акции (вручную сотрудником).
Так как стоит задача, получить в DS акционные цены в строгом в соответствии в ценами в кассовой системе, то логика выгрузки определена следующая:
Маркетинговая акция запустилась (однократная выгрузка).
Задача: проинформировать DS о значении и начале действия аукционной цены.

    1. При формировании выгрузки storePrices (цены) - для товара участвующего в Маркетинговой акции, в качестве регулярной цены будет выгружаться текущая цена из карточки, она же на этот момент будет являться аукционной.
    2. При формировании выгрузки priceTagInfo (акционные цены) - для товара участвующего в действующей Маркетинговой акции, в качестве:
  • «Цены» - должна выгружаться текущая цена из карточки, она же на этот момент будет являться акционной.
  • «Старой цены» - должна быть выгружена цена, которая была зафиксирована как «цена до акции».
  • «Название акции» - название акции, которая породила акционную цену.
  • «Дата и время начала акции» - Планируемая Дата и время старта акции
  • «Дата и время окончания акции» - Планируемая Дата и время окончания акции


Маркетинговая акция завершена (однократная выгрузка).
Задача: проинформировать DS о завершения действия аукционной цены.

    1. При формировании выгрузки storePrices (цены) - для товара участвующего в Маркетинговой акции, в качестве регулярной цены будет выгружаться текущая цена из карточки, она же на этот момент будет являться аукционной.
    2. При формировании выгрузки priceTagInfo (акционные цены) - для товара участвующего в действующей Маркетинговой акции, в качестве:
  • «Цены» - должна выгружаться текущая цена из карточки, она же на этот момент будет являться регулярной ценой.
  • «Старой цены» - должна быть выгружена цена из карточки, она же на этот момент будет являться регулярной ценой.
  • «Название акции» - название акции, которая породила акционную цену.
  • «Дата и время начала акции» - Планируемая Дата и время старта акции
  • «Дата и время окончания акции» - Фактическая Дата и время окончания акции


Маркетинговая акция завершена, но артикул продолжает участвовать в другой акции (однократная выгрузка).
Задача: проинформировать DS о новом значении и начале действия новой аукционной цены.

    1. При формировании выгрузки storePrices (цены) - для товара участвующего в Маркетинговой акции, в качестве регулярной цены будет выгружаться текущая цена из карточки, она же на этот момент будет являться акционной.
    2. При формировании выгрузки priceTagInfo (акционные цены) - для товара участвующего в действующей Маркетинговой акции, в качестве:
  • «Цены» - должна выгружаться текущая цена из карточки, она же на этот момент будет являться акционной.
  • «Старой цены» - должна быть выгружена цена, которая была зафиксирована как «цена до акции».
  • «Название акции» - название акции, которая породила акционную цену.
  • «Дата и время начала акции» - Планируемая Дата и время старта акции
  • «Дата и время окончания акции» - Планируемая Дата и время окончания акции


Публикация файлов в kafka (топики)

Каждый клиент идентифицируется уникальным ID (partner_id). Для каждого клиента создается отдельная группа топиков в формате: partner_id.doc_type
partner_id - id партнера на сервере DS 
doc_type - тип передаваемой информации

СуперМаг Плюс - 1.060.

  • Нет меток