Руководство по загрузке справочника товаров и их остатков через ПО «HEADO»
В данной руководстве описываются требования к загрузке справочника товаров и их остатков в CSV формате через ПО «HEADO»

Версия от 2022-11-22
Общее описание работы
  1. В автоматическом или в ручном режиме, справочник товаров и остатки подготавливаются в CSV формате, который соответствует спецификациям HEADO и выгружаются в желаемый каталог обмена на ПК/Сервере.
  2. На ПК/Сервер устанавливается ПО «HEADO» (мидсервер), который обрабатывает CSV файлы в каталоге обмена данными (каталог указывается при установке ПО)
  3. После успешной обработки CSV файла, файл сразу удаляется, а данные отправляются в облако HEADO
ВАЖНО: Для установки ПО «HEADO» требуется получить специальный ключ доступа (Auth_Key/Access Key) предназначенного для загрузки данных. Не рекомендуется использовать более одной копии ПО с одним и темже ключом одновременно.
Технические требования к установке
Установка ПО «HEADO»
1. Скачать и запустить инсталлятор «suite_service_mi_setup.exe»
2. В появившемся окне, нажмите на кнопку «Next»
3. В появившемся окне, введите полученный ключ доступа (AccessKey) и нажмите на кнопку «Next». (см. Рис.1.)
Рисунок 1. Окно ввода ключа
4. В появившемся окне, нажмите на кнопку «Install». (см. Рис. 2)
Рисунок 2.
5. После завершения установки, нажмите кнопку «Next» и «Finish» (см. Рис. 3)
Рисунок 3.
Загрузка номенклатурного справочника
1. Скачайте файлы "csv.js" и "price.js" и сохраните их в директорию %programfiles(x86)%\GiftomanService\plugins\js\
(при необходимости, создайте директорию js)
2. Запустите командую строку (cmd)
3. В командной строке, последовательно введите команды:
3.1. cd %programfiles(x86)%\GiftomanService\
3.2. GM.Config.exe descriptor create 1db (запомните полученный ID descriptor)
3.3. GM.Config.exe descriptor update id "JsFileName" "price.js"
3.4. GM.Config.exe descriptor update id "Interactor.FileInteractor.WatchPath" "exchange_dir"
3.5. GM.Config.exe descriptor update id -t int "Interactor.FileInteractor.PollingInterval" ms
Где:
  • ID - номер обработчика полученного в пункте 3.2.
  • exchange_dir - директория обмена, в которую выгружаются CSV-файлы номенклатуры
  • ms - период, через который будет срабатывать скрипт в миллисекундах (по умолчанию 2000)
4. Для применения настроек, перезапустите службу KKMGMSuiteService
CSV формат номенклатурного справочника
Необходимо разработать модуль экспорта для автоматического формирования и выгрузки номенклатурного справочника товаров в CSV формате Heado. Модуль должен иметь возможность формировать CSV файл по расписанию в настраиваемый каталог обмена с ПО Heado.
CSV файл рекомендуется именовать по маске: yyyyMMdd_hhmm.csv
Где, yyyyMMdd – год, месяц, день. hhmm – час, минута.
Требования к CSV:
1. Кодировка файла - UTF-8 без BOM;
2. Формат файла должен соответствовать RFC 4180, что подразумевает:
  • В качестве разделителя используется запятая («,»). Если в названии товара или его категории содержится запятая, то данное поле требуется заключить в "кавычки";
  • CSV файл и номенклатура в нем, не должны быть разделены на несколько порций, т.к. новый файл сбрасывает привязку товаров к группам/меткам из предыдущей загрузки;
3. Идентификатор товара должен быть уникальным для торговой сети, так как при совпадении идентификаторов, товар будет перезаписан;
4. Для опциональных полей необходимо передавать пустые значения.
NAME TYPE DESCRIPTION
1 name string(200) Название товара
2 category string(2000) Опционально
Иерархия групп товаров и дополнительных меток (акции и т.д.). В качестве делителя используется двойной амперсанд (&&).
Формат групп/меток: string(120)
Пример: Категория1&&Категория2&&Метка
При наличии идентификаторов торговых точек, перед дополнительной меткой в квадратных скобках можно указать ИД (store_ext_id) торговых точек (через запятую) на которую применяется данная метка на товар
Пример: Категория&&Подкатегория&&..&&[1,3]Акция.
3 price decimal(10,4) Опционально
Цена позиции
4 extid string(40) Уникальный «Внешний идентификатор товара» из справочника торговой системы предприятия, состоящий из цифр или латинских букв. Обязательно должен соответствовать внешнему уникальному идентификатору получаемого из чека.
5 vat decimal(4,2) Опционально
Ставка НДС в процентах (например 20.00 для 20%)
6 unit_type Enum Опционально
Единица измерения товара:
  • 1 - шт
  • 10 - литры
  • 11 - мл
  • 12 - ДАЛ (декалитры)
  • 20 - кг
  • 21 - граммы
  • 30 - метры
  • 31 - квадратные метры
7 unit_ratio decimal(10,4) Опционально
Коэффициент, пакетное соотношение проданного количества к unit_type
Примеры корректных записей CSV:

Пирожное,"торт,пирож,чизы&&Акция",36.99,159081,20,1,1
"Сосиски (1,25 кг)",,,21185, 20,20,1.25
Молоко,Молочные продукты&&Молоко&&Молоко в пакетах,39.90,59875,18,1,1
"Огурцы","овощи&&[1,2]Товар дня&&[3,4]monitor/critical",50.50,1234,,,

Загрузка товарных запасов
1. Скачайте файлы "csv.js" и "inventory.js" и сохраните их в директорию %programfiles(x86)%\GiftomanService\plugins\js\
(при необходимости, создайте директорию js)
2. Запустите командую строку (cmd)
3. В командной строке, последовательно введите команды:
3.1. cd %programfiles(x86)%\GiftomanService\
3.2. GM.Config.exe descriptor create e69 (запомните полученный ID descriptor)
3.3. GM.Config.exe descriptor update id "JsFileName" "inventory.js"
3.4. GM.Config.exe descriptor update id -t json "JsConfig" "{'PathInventory': ''}"
3.4. GM.Config.exe descriptor update id "JsConfig.PathInventory" "exchange_dir"
3.5. GM.Config.exe descriptor update id -t int "JsRunInterval" ms
Где:
  • ID - номер обработчика полученного в пункте 3.2.
  • exchange_dir - директория обмена, в которую выгружаются CSV-файлы с товарными запасами
  • ms - период, через который будет срабатывать скрипт в миллисекундах (по умолчанию 5000)
4. Для применения настроек, перезапустите службу KKMGMSuiteService
CSV формат по товарным запасам
Необходимо разработать модуль экспорта для автоматического формирования и выгрузки товарного запаса в CSV формате HEADO. Модуль должен иметь возможность формировать CSV файл по расписанию в настраиваемый каталог обмена с ПО HEADO.
Требования к CSV:
1. Кодировка файла - UTF-8 без BOM;
2. Формат файла должен соответствовать RFC 4180, что подразумевает:
  • В качестве разделителя используется запятая («,»). Если в названии товара или его категории содержится запятая, то данное поле требуется заключить в "кавычки";
  • CSV файл и номенклатура в нем, не должны быть разделены на несколько порций, т.к. новый файл сбрасывает привязку товаров к группам/меткам из предыдущей загрузки;
3. Идентификаторы товаров должны соответствовать идентификаторам товаров в справочнике;
4. Для опциональных полей необходимо передавать пустые значения.
NAME TYPE DESCRIPTION
1 store_ext_id string(40) Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
2 price_ext_id string(40) Уникальный «Внешний идентификатор товара» из справочника торговой системы предприятия, состоящий из цифр или латинских букв. Обязательно должен соответствовать внешнему уникальному идентификатору получаемого из чека.
3 snapshot_datetime string(ISO 8601 datetime) дата и время выгрузки актуального состояния инвентаря
Допустимые форматы:
1. YYYY-MM-DDThh:mm[:ss][Z] - Время в часовом поясе UTC+0;
2. YYYY-MM-DD hh:mm[:ss] - Время в локальном часовом поясе устройства, на котором установлено ПО HEADO.
4 in_matrix boolean Опционально:
Признак наличия в товарной матрице торговой точки.
Допустимые значения:
«1» или «true» – входит (передаётся по-умолчанию)
«0» или «false» – не входит
5 qty decimal(13,4) количество товара на момент выгрузки состояния
6 sell_price decimal(12,4) Опционально:
цена продажи за единицу
7 prime_cost decimal(12,4) Опционально:
себестоимость товара "без НДС" за единицу (Стоимость всего остатка / количество = средневзвешенная цена)
8 min_stock_level unsigned decimal(13,4) Опционально:
минимальный товарный запас в единицах учета, если задано на группу товаров, то транслировать значение для группы на все товары группы.
9 stock_in_days unsigned smallint Опционально:
норма товарного запаса в днях, если задано на группу товаров, то транслировать значение для группы на все товары группы.
10 in_transit decimal(13,4) Опционально:
количество товара в пути (в транзите) на момент выгрузки состояния
Примеры корректных записей CSV:

123,7890,2022-09-29 03:00,1,5,66.99,38.3,11.8,
456,0987,2022-09-30T03:00,0,3.99,504,314.42,100.0,7

Загрузка прямых показателей
1. Скачайте файлы "csv.js" и "kpi.js" и сохраните их в директорию %programfiles(x86)%\GiftomanService\plugins\js\
(при необходимости, создайте директорию js)
2. Запустите командую строку (cmd)
3. В командной строке, последовательно введите команды:
3.1. cd %programfiles(x86)%\GiftomanService\
3.2. GM.Config.exe descriptor create e69 (запомните полученный ID descriptor)
3.3. GM.Config.exe descriptor update id "JsFileName" "kpi.js"
3.4. GM.Config.exe descriptor update id -t json "JsConfig" "{'PathInventory': ''}"
3.4. GM.Config.exe descriptor update id "JsConfig.PathInventory" "exchange_dir"
3.5. GM.Config.exe descriptor update id -t int "JsRunInterval" ms
Где:
  • ID - номер обработчика полученного в пункте 3.2.
  • exchange_dir - директория обмена, в которую выгружаются CSV-файлы с товарными запасами
  • ms - период, через который будет срабатывать скрипт в миллисекундах (по умолчанию 5000)
4. Для применения настроек, перезапустите службу KKMGMSuiteService
CSV формат по прямым показателям
Необходимо разработать модуль экспорта для автоматического формирования значений показателей в CSV формате HEADO. Модуль должен иметь возможность формировать CSV файл по расписанию в настраиваемый каталог обмена с ПО HEADO.
Требования к CSV:
1. Кодировка файла - UTF-8 без BOM;
2. Формат файла должен соответствовать RFC 4180, что подразумевает:
  • В качестве разделителя используется запятая («,»)
3. Перевод строки стандартный 13,10 (\r\n);
4. Название полей в CSV не выгружается.
NAME TYPE DESCRIPTION
1 kpi_id bigint Прямой идентификатор показателя в HEADO
2 store_ext_id string(40) Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
3 ts string(ISO 8601 datetime) Дата/время регистрируемого значения
4 value decimal(10,4) Значение показателя за указанный час (система агрегирует значения кратные одному часу)
5 weight decimal(10,4) Вес показателя (для корректной работы AVG-показателей, по умолчанию = 1)
Примеры корректных записей CSV:

p/1437627895975752408,1128,2022-12-01 23:59,155.8,1
p/1437627895975752410,220,2022-12-01 23:59,89432.2,1
p/1437627895975752412,221,2022-12-01 23:59,35298.7,1
Проверка работы обработчиков
Для проверки работы обработчиков скопируйте тестовые CSV-файлы в соответствующие папки обмена. В случае успешной обработки файлы должны удалиться. Если файл не удалился, значит файл содержит ошибки и не может быть обработан. Для поиска ошибок, вы можете воспользоваться логом Javascript-модулей из директории: %programfiles(x86)%\GiftomanService\data\logs\:
  • Для обработчика справочника товаров – ext-id-JsPriceUpdaterInteractor.log
  • Для обработчика остатков – ext-id-JsInteractor.log
, где id – идентификатор соответствующего дескриптора.
Появился вопрос ?
При возникновении ошибки, предоставьте логи ПО «HEADO»
    Made on
    Tilda