Руководство по загрузке справочника товаров и их остатков через ПО «HEADO»
В данной руководстве описываются требования к загрузке справочника товаров и их остатков в CSV формате через ПО «HEADO»
Версия от 2022-11-22
Версия от 2022-11-22
Общее описание работы
- В автоматическом или в ручном режиме, справочник товаров и остатки подготавливаются в CSV формате, который соответствует спецификациям HEADO и выгружаются в желаемый каталог обмена на ПК/Сервере.
- На ПК/Сервер устанавливается ПО «HEADO» (мидсервер), который обрабатывает CSV файлы в каталоге обмена данными (каталог указывается при установке ПО)
- После успешной обработки CSV файла, файл сразу удаляется, а данные отправляются в облако HEADO
ВАЖНО: Для установки ПО «HEADO» требуется получить специальный ключ доступа (Auth_Key/Access Key) предназначенного для загрузки данных. Не рекомендуется использовать более одной копии ПО с одним и темже ключом одновременно.
Технические требования к установке
| ПАРАМЕТР | ЗНАЧЕНИЕ, ОГРАНИЧЕНИЕ |
|---|---|
| Операционная система | WinXP (POSReady 2009), Win7 и старше (x86 или x64) |
| Дополнительное ПО | Microsoft .NET Framework 4+ |
| Процессор (CPU) | Celeron 1Ghz |
| Оперативная память (RAM) | 1GB |
| Свободно место на диске (HDD) | 50Mb для установки ПО |
| Разрешение монитора | 640х480 при использовании графического интерфейса |
| Internet-канал (прямой или проксированный) | Гарантированная скорость 512kbit/s Доступность по 80 и 443 портам: https://api.heado.ru https://gamma.heado.ru https://update.heado.ru |
| Устройства ввода | Клавиатура в случае отсутствия сенсорного экрана или мыши |
Установка ПО «HEADO»
1. Скачать и запустить инсталлятор «suite_service_mi_setup.exe»
2. В появившемся окне, нажмите на кнопку «Next»
3. В появившемся окне, введите полученный ключ доступа (AccessKey) и нажмите на кнопку «Next». (см. Рис.1.)
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
(при необходимости, создайте директорию 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)
CSV формат номенклатурного справочника
Необходимо разработать модуль экспорта для автоматического формирования и выгрузки номенклатурного справочника товаров в CSV формате Heado. Модуль должен иметь возможность формировать CSV файл по расписанию в настраиваемый каталог обмена с ПО Heado.
CSV файл рекомендуется именовать по маске: yyyyMMdd_hhmm.csv
Где, yyyyMMdd – год, месяц, день. hhmm – час, минута.
Требования к CSV:
1. Кодировка файла - UTF-8 без BOM;
2. Формат файла должен соответствовать RFC 4180, что подразумевает:
4. Для опциональных полей необходимо передавать пустые значения.
CSV файл рекомендуется именовать по маске: yyyyMMdd_hhmm.csv
Где, yyyyMMdd – год, месяц, день. hhmm – час, минута.
Требования к CSV:
1. Кодировка файла - UTF-8 без BOM;
2. Формат файла должен соответствовать RFC 4180, что подразумевает:
- В качестве разделителя используется запятая («,»). Если в названии товара или его категории содержится запятая, то данное поле требуется заключить в "кавычки";
- CSV файл и номенклатура в нем, не должны быть разделены на несколько порций, т.к. новый файл сбрасывает привязку товаров к группам/меткам из предыдущей загрузки;
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 | Опционально Единица измерения товара:
|
| 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
(при необходимости, создайте директорию 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)
CSV формат по товарным запасам
Необходимо разработать модуль экспорта для автоматического формирования и выгрузки товарного запаса в CSV формате HEADO. Модуль должен иметь возможность формировать CSV файл по расписанию в настраиваемый каталог обмена с ПО HEADO.
Требования к CSV:
1. Кодировка файла - UTF-8 без BOM;
2. Формат файла должен соответствовать RFC 4180, что подразумевает:
4. Для опциональных полей необходимо передавать пустые значения.
Требования к CSV:
1. Кодировка файла - UTF-8 без BOM;
2. Формат файла должен соответствовать RFC 4180, что подразумевает:
- В качестве разделителя используется запятая («,»). Если в названии товара или его категории содержится запятая, то данное поле требуется заключить в "кавычки";
- CSV файл и номенклатура в нем, не должны быть разделены на несколько порций, т.к. новый файл сбрасывает привязку товаров к группам/меткам из предыдущей загрузки;
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
(при необходимости, создайте директорию 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)
CSV формат по прямым показателям
Необходимо разработать модуль экспорта для автоматического формирования значений показателей в CSV формате HEADO. Модуль должен иметь возможность формировать CSV файл по расписанию в настраиваемый каталог обмена с ПО HEADO.
Требования к CSV:
1. Кодировка файла - UTF-8 без BOM;
2. Формат файла должен соответствовать RFC 4180, что подразумевает:
4. Название полей в CSV не выгружается.
Требования к CSV:
1. Кодировка файла - UTF-8 без BOM;
2. Формат файла должен соответствовать RFC 4180, что подразумевает:
- В качестве разделителя используется запятая («,»)
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
Появился вопрос ?
При возникновении ошибки, предоставьте логи ПО «HEADO»
