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

Версия от 2024-03-20
Общее описание работы
  1. Торговая система в автоматическом или в ручном режиме, формирует CSV файл CSV с данными, которые соответствует спецификациям HEADO и выгружается в желаемый каталог обмена на ПК/Сервере.
  2. На ПК/Сервер устанавливается ПО «HEADO» (мидсервер), который обрабатывает CSV файлы в каталоге обмена данными
  3. После успешной обработки CSV файла, файл сразу удаляется, а данные отправляются в облако HEADO
Минимальные системные требования к ПО
  1. OS (Операционная система): С Windows 7+
  2. CPU (Процессор): CPU: 1.6GHz celeron
  3. Internet (Интернет): 512kb/s
  4. RAM (оперативная память): 2GB
  5. HDD Free (свободное место): 1GB свободного места
Установка ПО «HEADO»
1. Скачать подходящий инсталлятор, последней версии
2. Скопируйте credentials.ini в папку, где сохранен инсталлятор
3. В появившемся окне, нажмите на кнопку «Next»
4. В появившемся окне, нажмите на кнопку «Install».
5. В появившемся окне, поставьте галочку «Launch Midservice» и нажмите кнопку «Finish»
6. В появившемся окне командной строки, дождитесь установки и запуск службы Midservice.exe
ВАЖНО: Для установки ПО «HEADO» требуется получить credentials.ini, который содержит специальный ключ доступа (Auth_Key/Access Key) с типом терминала "Административный". Не рекомендуется использовать более одной копии ПО с одним и тем же ключом одновременно.
Спецификация CsvParser
Необходимо разработать модуль экспорта для автоматического формирования данных в CSV формате HEADO. Модуль должен иметь возможность формировать CSV файл по расписанию в настраиваемый каталог обмена с ПО HEADO.
CSV файл рекомендуется именовать по маске: yyyyMMdd_hhmm.csv
Где, yyyyMMdd – год, месяц, день. hhmm – час, минута.
Фиксированные параметры для всех раннеров
ПАРАМЕТР ЗНАЧЕНИЕ ОПИСАНИЕ
1 Экранирование Двойные кавычки (") Текстовые/строковые значения должны быть заключены в двойные кавычки, имеющиеся кавычки должны быть дублированы.
Например, [кукла "Маша"] => ["кукла ""Маша"""]
2 Перевод строки Определяется автоматически Тип переноса строки един для каждого файла.
3 Десятичный разделитель Точка (.)
Параметры форматов по умолчанию, настраиваются индивидуально для каждого раннера
ПАРАМЕТР ЗНАЧЕНИЕ ПО УМОЛЧАНИЮ ОПИСАНИЕ
1 delimiter Запятая "," Разделитель колонок (можно изменить)
2 encoding UTF-8 Кодировка (можно изменить на поддерживаемую).
3 has_header false Заголовки колонок в первой строке
4 EOF_marker Отсутствует Маркер конца файла, строка, в RecieptRunner для поддержки формата CommonCSV может быть установлено "___EOF___"
5 override Отсутствует Задаёт значения полей по умолчанию. Например
override:
  status: 1

В этом случае всем значениям в поле status будет присвоено 1.
6 file_mask false Относительный путь к обрабатываемым файлам, индивидуальный для каждого раннера
7 fieldnames Полный список полей, для форматов ниже Порядок полей может быть изменен. Поля с именами, не предусмотренными спецификацией runner игнорируются
Параметры для полей с использованием формул, настраиваются индивидуально для каждого раннера
Колонки
ПАРАМЕТР ЗНАЧЕНИЕ ПО УМОЛЧАНИЮ ОПИСАНИЕ
1 fields колонка
   настройка колонки
(Опционально)
Поля, в которых будут использоваться формулы для преобразования входных данных. Например:
store_ext_id:
     formula:
Где:
- store_ext_id - название столбца.
- formula - преобразование данных, аналогично Excel.
Настройка колонок
ПАРАМЕТР ЗНАЧЕНИЕ ПО УМОЛЧАНИЮ ОПИСАНИЕ
1 formula string (Опционально)
Указывает формулу для преобразования данных.
2 multiplier decimal (Опционально)
Приводит числовое поле к нужному формату с помощью умножения.
3 prefix string (Опционально)
Добавляет строковое значение в поле. Работает по логике: <поле> + .
ReceiptRunner

Настройки

ИМЯ ПОЛЯ ЗНАЧЕНИЕ ПО УМОЛЧАНИЮ ОПИСАНИЕ
1 params.isg отсутствует Список соответствий меток и диапазонов ИСГ в формате "min,max: mark, где min и max — кол-во дней до истечения срока годности (для указания только одной границы диапазона можно указать "min", или "max), а "mark" — метка.
Требует наличие полей expiry_date или expires_in_days
Перечень и формат передаваемых данных
ИМЯ ПОЛЯ ФОРМАТ ОПИСАНИЕ
1 store_ext_id string(40) Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
2 pos_ext_id string(64) «Внешний идентификатор устройства» (кассы/сервера) из торговой системы предприятия, состоящий из латинских букв или цифр
3 ext_id string(40) Стабильный и уникальный «Внешний идентификатор чека» в торговой системе. Если в торговой системе уникальный ИД чека отсутствует, то рекомендуем использовать в качестве его маски комбинацию из следующих идентификаторов:
- ИД торговой сети,
- ИД торговой точки,
- ИД устройства (кассы, ECR, POS, АРМ),
- ИД кассовой смены,
- номера чека в кассовой смене.
4 posit_index int (Опционально)
Число от 1 до 9999. Номера строк одного чека в файле должны идти по порядку.
5 date ГГГГ-ММ-ДД Дата чека
6 time ЧЧ:ММ:СС Время чека
7 price_ext_id string(40) Уникальный «Внешний идентификатор товара» из справочника торговой системы предприятия, состоящий из цифр или латинских букв. Если длина более 40, то значение обрезается до 40 символов
8 name string(200) Наименование товара
9 count decimal(10,4) Количество товара, всегда больше 0
10 posit_total decimal(10,4) Сумма по всей строке (после применения скидки)
11 posit_discount decimal(10,4) Скидка по всей строке
12 seller string(64) ФИО кассира/продавца
13 categories string() Иерархия групп товаров и доп.меток (акции и тд). Имена категорий и подкатегорий, которые будут использоваться в фильтрах для настройки показателей (KPI) должны быть уникальными. В качестве разделителя значений, используйте двойной амперсанд &&. Формат групп/меток: string(120), максимальное кол-во категорий - 100 штук.
Пример: Категория1&&Категория2&&Метка
14 is_purchase bool Тип чека:
«0» или «false» - Возврат
«1» или «true» – Продажа
15 expiry_date ГГГГ-ММ-ДД (Опционально)
Дата истечения срока годности товара
16 expires_in_days int (Опционально)
Кол-во дней до истечения срока годности товара. Имеет приоритет над expiry_date
17 attributes string() (Опционально)
Словарь атрибутов, сериализованный в строку. Названия атрибутов должны быть уникальными. В качестве разделителя между названием и значением используется знак равно (=), в качестве разделителя между парами "название-значение" используется двойной амперсанд (&&). Значения могут быть отрицательными (например, при возвратах). Формат названий — string(20), латинские символы. Формат значений — decimal(12, 4).
Пример: Атрибут1=1&&Атрибут2=-123.45
PriceRunner

Перечень и формат передаваемых данных

ИМЯ ПОЛЯ ФОРМАТ ОПИСАНИЕ
1 name string(200) Наименование товара
2 categories string() (Опционально)
Иерархия групп товаров и доп.меток (акции и тд). Имена категорий и подкатегорий, которые будут использоваться в фильтрах для настройки показателей (KPI) должны быть уникальными. В качестве разделителя значений, используйте двойной амперсанд &&. Формат групп/меток: string(120), максимальное кол-во категорий - 100 штук.
Пример: Категория1&&Категория2&&Метка
При наличии идентификаторов торговых точек, перед дополнительной меткой в квадратных скобках можно указать ИД (store_ext_id) торговых точек (через запятую) на которую применяется данная метка на товар
Пример: Категория&&Подкатегория&&..&&[1,3]Акция.
3 price decimal(10,4) (Опционально)
Цена позиции
4 price_ext_id 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
8 alc_volume decimal(10,4) (Опционально)
Объем единицы товара в декалитрах, используемый в журнале учета объема розничной продажи алкогольной продукции
9 net_weight decimal(10,4) (Опционально)
Вес нетто единицы товара выраженный в килограммах
10 gross_weight decimal(10,4) (Опционально)
Общий вес единицы товара выраженный в килограммах
11 volume decimal(10,4) (Опционально)
Объем единицы товара выраженный в кубических метрах
12 area decimal(10,4) (Опционально)
Площадь единицы товара выраженная в квадратных метра
13 length decimal(10,4) (Опционально)
Длина единицы товара выраженная в метрах
14 height decimal(10,4) (Опционально)
Высота единицы товара выраженная в метрах
15 width decimal(10,4) (Опционально)
Ширина единицы товара выраженная в метрах
16 items int (Опционально)
Количество унитарных единиц в единице товара
InventoryRunner

Перечень и формат передаваемых данных

ИМЯ ПОЛЯ ФОРМАТ ОПИСАНИЕ
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) (Опционально)
Количество товара в пути (в транзите) на момент выгрузки состояния
KpiRunner

Перечень и формат передаваемых данных

ИМЯ ПОЛЯ ФОРМАТ ОПИСАНИЕ
1 kpi_id bigint Прямой идентификатор показателя в HEADO
2 store_ext_id string(40) Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
3 ts string(ISO 8601 datetime) Дата/время регистрируемого значения
4 value decimal(10,4) Значение показателя за указанный час (система агрегирует значения кратные одному часу)
4 weight decimal(10,4) (Опционально)
Вес показателя (для корректной работы AVG-показателей, по умолчанию = 1).
В интерфейсах значение показателя за период определяется по формуле SUM(value*weight)/SUM(weight)
AccountRunner

Настройки

ИМЯ ПОЛЯ ЗНАЧЕНИЕ ПО УМОЛЧАНИЮ ОПИСАНИЕ
1 account_params.block_missing false true|false – после обработки файла блокируются аккаунты, не входящие в этот файл.

Перечень и формат передаваемых данных

ИМЯ ПОЛЯ ФОРМАТ ОПИСАНИЕ
1 login string(200) Обязателен при создании аккаунта и при отсутсвии ext_id (ид сотрудника)
2 ext_id string(40) (Опционально)
Уникальный идентификатор сотрудника. Обязательно при обновлении, если отсутствует Login
3 name string(200) (Опционально)
ФИО пользователя, рекомендуем "Фамилия И.О."
4 phone string(15) (Опционально)
Служебный телефон
5 email string(200) (Опционально)
Адрес служебной электронной почты
6 status [ 0, 1, 2 ] (Опционально)
0 - Not active,
1 - Active,
2 - Block
7 manager_login string(200) (Опционально)
Логин руководителя
8 role ["PartnerTopManagerRole",
"PartnerDivisionManagerRole",
"PartnerHeadRole",
"PartnerZoneManagerRole",
"PartnerLogisticsRole",
"PartnerManagerRole",
"PartnerSellerRole",
"PartnerAuxiliaryRole",
"PartnerMonitorRole",
"PartnerPayerRole",
"PartnerCategoryManagerRole"]
(Опционально)
Топ-менеджер
Дивизиональный директор
Региональный директор
Зональный директор
Логист
Директор магазина
Продавец
Вспомогательная роль
Оператор контроля
Плательщик
Категорийный менеджер
9 access ["allow", "deny"] (Опционально)
allow - доступ разрешен
deny - доступ запрещен
PlansRunner

Настройки

ИМЯ ПОЛЯ ЗНАЧЕНИЕ ПО УМОЛЧАНИЮ ОПИСАНИЕ
1 plans_params.store_ext_id отсутствует (Опционально) br>Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр. Если не указан, в запросе будет передана директива ""@batch"", указывающая на то, что сервер должен опубликовать планы по всем затрагиваемым store_ext_id
2 plans_params.auto отсутствует true - Использовать сервисную аналитику распределения по периодам.
false - Не использовать аналитику (равномерное распределение по нижним периодам)

Перечень и формат передаваемых данных

ИМЯ ПОЛЯ ФОРМАТ ОПИСАНИЕ
1 store_ext_id string(40) Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр.
2 metric string(42) Идентификатор показателя с префиксом. В зависимости от префикса в запросе будут переданы:
p/ — прямой идентификатор;
e/ — внешний идентификатор.
Не может быть указан, при наличии kpi_id или kpi_ext_id.
3 kpi_ext_id string(40) Уникальный «Внешний идентификатор показателя» из торговой системы предприятия, состоящий из латинских букв или цифр. Опционален, при указании kpi_id.
4 kpi_id int (Опционально)
Прямой идентификатор показателя в системе HEADO (необязателен при наличии параметра kpi_ext_id, имеет приоритет)
5 plan decimal(14,4) Если >=0, то установка планового значения.
Если <0, то удаление.
6 corr_plan (Опционально)
Корректировка дневного плана
7 year int Год
8 month int Месяц
9 day int (Опционально)
День. Если не указан или =-1, то выставляется план на месяц, иначе - на день
ShiftRunner

Перечень и формат передаваемых данных

ИМЯ ПОЛЯ ФОРМАТ ОПИСАНИЕ
1 store_ext_id string(40) Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
2 pos_ext_id string(64) «Внешний идентификатор устройства» (кассы/сервера) из торговой системы предприятия, состоящий из латинских букв или цифр
3 name string Стабильный и уникальный «Внешний идентификатор чека» в торговой системе. Если в торговой системе уникальный ИД чека отсутствует, то рекомендуем использовать в качестве его маски комбинацию из следующих идентификаторов:
- shift/start - открыта кассовая смена,
- shift/stop - закрыта кассовая смена
4 ts string(ISO 8601 datetime) Дата/время регистрируемого события
EventRunner

Настройки

ИМЯ ПОЛЯ ЗНАЧЕНИЕ ПО УМОЛЧАНИЮ ОПИСАНИЕ
1 event_params.event_map отсутствует Маппинг событий (shift/start, shift/stop, и т. д.) к строкам/массивам строк. Пример элементов маппинга:
shift/start: Открыта
shift/stop: ['Закрыта', 'Закрытие смены']

Перечень и формат передаваемых данных

ИМЯ ПОЛЯ ФОРМАТ ОПИСАНИЕ
1 store_ext_id string(40) Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
2 pos_ext_id string(64) «Внешний идентификатор устройства» (кассы/сервера) из торговой системы предприятия, состоящий из латинских букв или цифр
3 name string Стабильный и уникальный «Внешний идентификатор чека» в торговой системе. Если в торговой системе уникальный ИД чека отсутствует, то рекомендуем использовать в качестве его маски комбинацию из следующих идентификаторов:
- shift/start — Открыта кассовая смена
- shift/stop — Закрыта кассовая смена
- sku/writeoff — Списание товара
- sku/move — Перемещение товара
- sku/income — Приход товара
- sku/return — Возврат товара
4 ts string(ISO 8601 datetime) Дата/время регистрируемого события
5 owner.name string(200) "(Опционально) ФИО. Обязательно при передаче событий sku/*
6 owner.ext_id string(40) (Опционально) Идентификатор ответственного в торговой системе
7 sku.ext_id string(40) (Опционально) Идентификатор SKU в торговой системе. Обязательно при передаче событий sku/*
8 sku.qty decimal(10,4) (Опционально) Количество единиц списываемого товара. Обязательно при передаче событий sku/*
SheduleRunner

Настройки

ИМЯ ПОЛЯ ЗНАЧЕНИЕ ПО УМОЛЧАНИЮ ОПИСАНИЕ
1 schedule_params.wday_map {1,2,3,4,5,6,7,0} (1-Понедельник) Индексы дней недели начиная с понедельника, пропуски недопускаются

Перечень и формат передаваемых данных

ИМЯ ПОЛЯ ФОРМАТ ОПИСАНИЕ
1 store_ext_id string(40) Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
2 wday tinyint или string Индекс дня недели, при wday_map по умолчанию 1-Понедельник, ... 7 - Воскресенье. Если у торговой точки выходной, то расписание не указывается
3 from string(5) ЧЧ:ММ Начало рабочего интервала, если есть перерывы в течение дня, то передавать разными строками
4 to string(5) ЧЧ:ММ Окончание рабочего интервала, если есть перерывы в течение дня, то передавать разными строками
StoreRunner

Настройки

ИМЯ ПОЛЯ ЗНАЧЕНИЕ ПО УМОЛЧАНИЮ ОПИСАНИЕ
1 store_params.create false true|false - при отсутствии ТТ с указанным store_ext_id создавать новую ТТ (требуются country, city, street, house)
2 store_params.reset_tags false true|false - перед передачей новых тегов выполнять сброс существующих
3 store_params.disable_missing false true|false - после обработки файла, блокируються ТТ не входяшие в этот файл
4 store_params.full_string false true|false - требуется передавать весь адрес в 'street'
5 store_params.metatag_in_filters true true|false - определяет, будет ли метатег отображаться в фильтрах

Перечень и формат передаваемых данных (один из параметров 2-5 должен быть обязательно)

ИМЯ ПОЛЯ ФОРМАТ ОПИСАНИЕ
1 store_ext_id string(40) Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
2 name string(100) (Опционально)
Название торговой точки
3 status string(10) (Опционально)
- enabled - Меняет статус торговой точки на Включен"
- disabled - Меняет статус торговой точки на Выключен"
- test - Меняет статус на тестовый. Используется для торговых точек, готовящихся к открытию.
4 meta string (JSON) Описание: Поле содержит JSON строку с произвольной структурой данных в формате json, длиной до 32к символов.
Пример:
""{""""key1"""": """"value1"""", """"stockCostTarget"""": """"Норма товарного запаса в руб"""", """"tradeType"""": """"формат торговой точки""""}""
Требования:
- JSON строка должна быть корректной и валидной.
- JSON строка должна быть заключена в двойные кавычки.
- Все двойные кавычки внутри JSON строки должны быть удвоены.
5 tags string (Опционально)
Список меток торговой точки разделенных запятой/td>
6 country string(60), обязательно при create:true для новых ТТ Название страны по КЛАДР или ФИАС
7 city string(60), обязательно при create:true для новых ТТ Название города по КЛАДР или ФИАС
8 street string(100), обязательно при create:true для новых ТТ Название улицы по КЛАДР или ФИАС
9 street string(20), обязательно при create:true для новых ТТ Дом, включая корпуса, литеры и т.п. (например 10/1а)
OrgRunner

Настройки

ИМЯ ПОЛЯ ЗНАЧЕНИЕ ПО УМОЛЧАНИЮ ОПИСАНИЕ
1 org_params.hierarchy [
"PartnerTopManagerRole",
"PartnerDivisionManagerRole",
"PartnerDivisionAdministratorRole",
"PartnerHeadRole",
"PartnerZoneManagerRole",
"PartnerLogisticsRole",
"PartnerManagerRole"
]
Список, по которому строится иерархия. Сначала указываются высшие роли, затем более низкие
2 org_params.metatag_in_filters true true|false - определяет, будет ли метатег отображаться в фильтрах
3 org_params.use_store_name_in_partner_manager_role false true|false - определяет, использование имени тороговой точни для роли "PartnerManagerRole".
4 org_params.not_found_account_name "{login}" Используется для аккаунтов, у которых нет имени. Можно указать любой другой формат с доступными переменными.
5 org_params.empty_node_account_params Используется для виртуальных аккаунтов, содержит два параметра: "name" и "login_pattern".
6 empty_node_account_params.name "{login}" Можно указать любой другой формат с доступными переменными.
7 empty_node_account_params.pattern "vacancy*" Используется для поиска виртуальных аккаунтов.

Переменные, которые можно использовать в имени

ИМЯ ПОЛЯ ЗНАЧЕНИЕ ПО УМОЛЧАНИЮ ОПИСАНИЕ
1 role string Название роли
2 role_alias string Название псевдонима роли
3 store_ext_id string Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
4 store_name string Название торговой точки
5 login string Логин пользователя
6 manager_login string Логин вышестоящего пользователя
7 manager_login_name string Имя вышестоящего пользователя

Перечень и формат передаваемых данных

ИМЯ ПОЛЯ ФОРМАТ ОПИСАНИЕ
1 store_ext_id string(40) Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
2 role_1 string(200) Указываем первую роль в столбце, а в строке передаем соответствующий логин к роли
3 role_2 string(200) Указываем вторую роль в столбце, а в строке передаем соответствующий логин к роли
4 role_n string(200) Указываем последующие роли в столбце, а в строке передаем соответствующий логин к роли
Появился вопрос ?
При возникновении ошибки, предоставьте логи ПО «HEADO»
    Made on
    Tilda