Імпорт документів

2026-07-202026-10-07

Склад завантажує прихідні накладні та прайси постачальників з файлів XLSX, XLS, CSV та XML. Файл обробляє служба abrest: вона знаходить у довіднику товари з файлу, створює відсутні разом з групами та характеристиками і складає з рядків файлу новий документ.

Що потрібно на початку

Служба abrest запущена на сервері.
У вашому робочому профілі є секція abrest: з enabled: true та адресою служби - так само, як секція abasyn: для синхронізації з інтернет-магазином.
Для профілю активовано служби кнопкою активації служб у редакторі конфігурації.
Для перекладу назв і пошуку товарів за схожістю назви - налаштована локальна LLM. Без неї імпорт працює, але товар знаходиться лише за точним збігом.

Як імпортувати документ

Відкрийте Прихідні накладні або Прайси. Інші документи імпорт не підтримують.
У списку контрагентів виберіть постачальника. Налаштування імпорту зберігаються окремо для кожного постачальника і кожного виду документа: прайс і накладна одного постачальника мають різні налаштування. Накладна оприбутковується на вибрану у формі фірму та на склад вашого робочого місця.
Файл → Імпорт документу... і виберіть файл.

Якщо від цього постачальника документ такого виду вже імпортували, імпорт одразу починається з збереженими налаштуваннями. Інакше спершу з'являться налаштування, складені автоматично.

Перший імпорт від постачальника

abrest аналізує файл і пропонує налаштування:

знаходить рядок заголовків;
розпізнає стовпці за заголовками: назву товару («Назва», «Найменування», «Товар», «Name»), ціну («Ціна», «Price»), штрихкод («Штрихкод», «EAN», «Barcode»), артикул («Артикул», «SKU»), опис («Опис», «Характеристики»);
стовпець, заголовок якого збігається з назвою поля документа, записує в це поле;
решту стовпців пропонує як характеристики товару;
шукає рядки-групи за оформленням комірок, об'єднаними комірками або групуванням рядків Excel («плюсиками» ліворуч від номерів рядків);
якщо розпізнав мову назв, додає переклад на англійську. Якщо переклад не потрібен, видаліть секцію translation.

Запропоноване відкривається у вікні Налаштування імпорту. Перевірте його і натисніть OK - налаштування збережуться за постачальником, і імпорт почнеться. Скасувати перериває імпорт, нічого не зберігаючи.

Зміна налаштувань

Збережені налаштування відкриваються з таблиці контрагентів: меню лівої верхньої комірки таблиці → Редагувати параметри імпорту. Якщо для вибраного постачальника налаштувань ще немає, відкриється загальний шаблон; після OK він стане налаштуваннями цього постачальника, і аналіз файлу при імпорті вже не запускатиметься.

Вікно «Налаштування імпорту»

Налаштування записуються у форматі YAML - відступи пробілами мають значення. Вікно допомагає:

Праворуч від кожного поля в секції fields сірим підписано заголовок відповідної колонки документа. «Віртуальне поле» - такої колонки в документі немає: значення стане характеристикою товару або використовується лише під час обробки.
Ctrl+J на значенні bg_color відкриває вибір кольору, на значеннях так/ні - пропонує true або false.
Значок біля номера рядка показує проблему. Червоне коло - помилка: налаштування не збережуться, доки її не виправлено. Жовтий трикутник - попередження, наприклад невідома назва налаштування: при збереженні програма перелічить попередження і запитає, чи зберігати.
Під час збереження курсор переходить до першого проблемного рядка.

Перебіг імпорту

Поверх форми з'являється панель:

заголовок з лічильниками «Імпорт: N завантажено, M пропущено...»;
смуга виконання з відсотком;
через 10 секунд - скільки часу минуло і скільки приблизно залишилось;
список пропущених рядків у вигляді «[Причина] Рядок N: опис»:
- [Помилка] - рядок не вдалося обробити, опис пояснює чому;
- [Виключено] - рядок належить категорії з дією exclude;
- [Без полів] - у рядку немає жодного стовпця з налаштувань.

Рядки рахуються починаючи від рядка заголовків, без рядків-груп, тому номер не збігається з номером рядка в Excel.

Новий документ з'являється у списку, щойно завантажено перші рядки. Сховати ховає панель, імпорт при цьому триває, лічильники видно в рядку стану. Наприкінці заголовок панелі показує «Імпорт завершено. Завантажено: N, пропущено: M.» або «Імпорт завершено з помилками...» - тоді причина додається останнім рядком списку.

Якщо щось не працює

Повідомлення	Причина
«Службу Abrest не налаштовано для хоста ...»	У профілі немає секції `abrest:` або стоїть `enabled: false`.
«У вас немає токена авторизації для доступу до ...»	Для профілю не активовано служби.
«Потрібно вибрати контрагента для роботи з документом»	Не вибрано постачальника.
«... не підтримує імпорт через Abrest»	Імпорт відкрито не з прихідних накладних і не з прайсів.
`Header row not found`	У файлі немає рядка, що містить усі заголовки з налаштувань. Заголовки порівнюються точно, з урахуванням регістру та пробілів.
`Unknown field(s) in import config`	Поле в `fields` не є колонкою документа і не має `tag`. Перейменуйте його на колонку документа, додайте `tag` або видаліть.

Приклад конфігурації

Прайс у XLSX з трирівневою ієрархією категорій, що розпізнається за оформленням рядків, з перевизначенням категорій постачальника, характеристиками та перекладом з української на англійську.

---
file_type: xlsx
sheet: 0

global:
    root_group_id: 0
    tovar_type: 1
    translation:
        from: uk
        to: en
        translate_items: true
        translate_groups: true
        translate_tags: true

fields:
    GROUP_ID:
        resolve: group_path
        levels:
            - name: category
              tag: Категорія
              detect:
                  column: 0
                  method: formatting
                  bold: true
                  font_size: 14
            - name: subcategory
              detect:
                  column: 0
                  method: formatting
                  bg_color: 92D050
                  bold: true
            - name: product_type
              detect:
                  column: 0
                  method: formatting
                  bg_color: D9FECC
        categories:
            depth: 2
            default: tag
            default_tag_name: Тип товару
            mapping:
                - source: "Власна марка"
                  action: map
                  group_id: 42
                - source: "Знято з виробництва"
                  action: exclude
                - source: "Змішані добрива"
                  action: inherit
    TOVAR_ID:
        resolve: find_or_create
        name_source: "Назва товару"
        ean_source: "Штрихкод"
        article_source: "Артикул"
    TOVAR_CODE:
        source: "Штрихкод"
        type: number
    PRICE_INC:
        source: "Ціна"
        type: number
    PRICE_OUT:
        source: "РРЦ"
        type: number
    MANUFACTURER:
        source: "Виробник"
        tag: Виробник
    IMPORT_DATE:
        value: today
        tag: Дата імпорту
...

Рядок заголовків - перший рядок, де є «Назва товару», «Штрихкод», «Артикул», «Ціна», «РРЦ» і «Виробник». Усе вище нього пропускається.
Жирні рядки шрифтом 14 - категорії, жирні на зеленому тлі - підкатегорії, на світло-зеленому - типи товару. Такі рядки не імпортуються, а задають групу для товарів під ними.
Категорії й підкатегорії створюються як групи довідника (depth: 2), а тип товару стає характеристикою «Тип товару» (default: tag). Назва категорії також записується в характеристику «Категорія».
Товари категорії «Власна марка» потрапляють в наявну групу 42, рядки категорії «Знято з виробництва» відкидаються, товари «Змішаних добрив» лишаються в групі рівнем вище, без власної підгрупи.
Штрихкод іде і в пошук товару, і в колонку «Код товару» документа; ціна - в «Поточна закупка», РРЦ - в «Ціна продажу».
«Виробник» та дата імпорту стають характеристиками нових товарів; у документ вони не пишуться, бо таких колонок у прайсі немає.

Загальні налаштування

Ключ	Обов'язковий	Призначення
`file_type`	так	`xlsx`, `xls`, `csv` або `xml`
`sheet`	ні	Номер аркуша XLSX/XLS, рахуючи з `0` (типово перший)
`global`	ні	Налаштування для всього файлу
`fields`	так	Що й звідки записується - по одному запису на поле

`global`

Ключ	Типово	Опис
`root_group_id`	`0`	ІД групи довідника, всередині якої шукаються і створюються групи з файлу. `0` - корінь довідника.
`tovar_type`	`1`	Тип створених товарів: `1` - товар, `2` - послуга/робота
`translation`	-	Переклад назв (див. нижче)

`global.translation`

Ключ	Типово	Опис
`from`	-	Мова файлу: `uk`, `en`, `de`, `pl`, ...
`to`	-	Мова перекладу
`translate_items`	`true`	Перекладати назви товарів
`translate_groups`	`true`	Перекладати назви груп
`translate_tags`	`true`	Перекладати значення характеристик

Переклад працює, лише якщо задано і from, і to, і в службі abrest налаштовано LLM. Кожна назва перекладається один раз.

`fields`

Кожен запис - це поле документа або допоміжне поле. Назва запису - назва колонки документа великими літерами; вікно налаштувань підписує поруч її заголовок. Основні колонки:

Прайс		Прихідна накладна
`TOVAR_CODE`	Код товару	`PAPER_POS`	№ п/п
`TOVAR_AMOUNT`	Кількість	`AMOUNT`	Кількість
`PRICE_INC`	Поточна закупка	`PRICE`	Ціна
`PRICE_OUT`	Ціна продажу	`C_PRICE`	Ціна у валюті
`PRICE_1`...`PRICE_3`	Ціна 1...3	`SELL_PRICE`	Відпускна ціна
`NOTE`	Примітка	`EXT_EAN13`	Зовнішній код
		`TOVAR_EXTARTICLE`	Артикул постачальника
		`TERM_GOOD`	Придатний до
		`NOTE`	Примітка

Запис з будь-якою іншою назвою допустимий, лише якщо має tag або value.

Є чотири види записів.

Стовпець файлу - `source`

PRICE_INC:
    source: "Ціна"
    type: number

Ключ	Обов'язковий	Опис
`source`	так	Заголовок стовпця у файлі, точно, з урахуванням регістру
`type`	ні	`number` або `integer` - лишає з тексту лише число; якщо числа немає - `0`
`tag`	ні	Записати значення ще й як характеристику товару з цією назвою

Стале значення - `value`

IMPORT_DATE:
    value: today
    tag: Дата імпорту

Ключ	Обов'язковий	Опис
`value`	так	Значення для кожного рядка; `today` - сьогоднішня дата
`tag`	ні	Як для `source`

Групи товарів - `resolve: group_path`

Знаходить у файлі рядки-групи і розміщує товари в групах довідника, створюючи відсутні.

`levels`

Рівні груп - від найширшого до найвужчого. Коли трапляється рядок вищого рівня, усі нижчі рівні скидаються.

Ключ	Обов'язковий	Опис
`name`	так	Довільна назва рівня
`tag`	ні	Записати назву групи цього рівня ще й як характеристику товару з цією назвою
`detect`	так	Як розпізнати рядок-групу цього рівня

`detect`

Ключ	Типово	Опис
`column`	`0`	Номер стовпця, рахуючи з `0`, що перевіряється і з якого береться назва групи
`method`	`single_value`	Спосіб розпізнавання (таблиця нижче)
`outline_level`	-	Рівень групування рядків Excel, для `method: outline_level` (лише XLSX)
`bg_color`	-	Колір тла комірки `RRGGBB`
`font_color`	-	Колір шрифту `RRGGBB`
`font_size`	-	Розмір шрифту
`font_name`	-	Назва шрифту, без урахування регістру
`bold`	-	Жирний: `true` або `false`
`italic`	-	Курсив: `true` або `false`

Якщо задано кілька ознак оформлення, мають збігтися всі.

Спосіб	Рядок є групою, якщо
`single_value`	у рядку заповнено не більше однієї комірки (і збігається оформлення, якщо задане)
`merged_cells`	комірка в `column` об'єднана з сусідніми (XLSX/XLS; для CSV/XML - як `single_value`)
`formatting`	збігається оформлення комірки в `column`. Для файлів, де рядки груп заповнені так само, як рядки товарів
`outline_level`	рівень групування рядка Excel дорівнює `outline_level`, і рядок підходить під `single_value` або `merged_cells`

`categories`

Необов'язкове. Потрібне, коли категорії постачальника не збігаються з групами вашого довідника. Без нього весь ланцюжок категорій створюється як групи.

Ключ	Опис
`depth`	Рівні з 1-го по `depth` створюються як групи. Глибші рівні отримують дію `default`. `0` - усі рівні створюються як групи.
`default`	Дія для рівнів, глибших за `depth`: `create`, `map`, `tag`, `inherit` або `exclude`
`default_tag_name`	Назва характеристики для `default: tag`
`default_group_id`	ІД групи для `default: map`
`mapping`	Окремі правила для конкретних категорій, за точною назвою без урахування регістру

Правило в mapping:

Ключ	Потрібен для	Опис
`source`	усіх	Назва категорії у файлі
`action`	усіх	`create`, `map`, `tag`, `inherit` або `exclude`
`group_id`	`map`	ІД наявної групи довідника
`tag_name`	`tag`	Назва характеристики; без неї - `default_tag_name`

Дія	Результат
`create`	Знайти або створити групу з такою назвою всередині попередньої
`map`	Використати наявну групу `group_id`; наступні рівні шукаються вже в ній
`tag`	Не створювати групу, а записати назву категорії як характеристику товару
`inherit`	Далі не йти: товар лишається в останній знайденій групі
`exclude`	Пропустити рядок повністю - у документ він не потрапить, товар не створюється

Товар - `resolve: find_or_create`

Знаходить товар у довіднику, а якщо не знайшов - створює.

TOVAR_ID:
    resolve: find_or_create
    name_source: "Назва товару"
    ean_source: "Штрихкод"
    article_source: "Артикул"

Ключ	Обов'язковий	Опис
`name_source`	так	Заголовок стовпця з назвою товару
`ean_source`	ні	Заголовок стовпця зі штрихкодом
`article_source`	ні	Заголовок стовпця з артикулом постачальника

Порядок пошуку:

За штрихкодом, артикулом і назвою серед товарів, уже відомих від цього постачальника.
Якщо налаштовано LLM і переклад - за схожістю назви. Знайдений так товар запам'ятовується за штрихкодом і артикулом постачальника, і наступного разу знаходиться вже на кроці 1.
Інакше створюється новий товар у групі з GROUP_ID. Якщо групу не визначено, товар створюється без групи і без прив'язки до постачальника.

Порядок обробки

Спершу шукається рядок заголовків - перший рядок, що містить усі заголовки, згадані в source, name_source, ean_source і article_source. Усе вище нього пропускається. Далі для кожного рядка до кінця аркуша:

Якщо рядок підходить під detect якогось рівня, він запам'ятовується як поточна група і не імпортується.
Значення зі стовпців розкладаються по полях з fields.
Застосовуються type: number і value.
Визначається група товару. Рядок з категорії з дією exclude пропускається.
Шукається або створюється товар.
Лише для щойно створених товарів: записуються характеристики (tag полів і рівнів, характеристики з categories) і виконується переклад. Уже наявним у довіднику товарам повторний імпорт характеристик не змінює.
Рядок додається в документ.

Імпорт документів

Що потрібно на початку

Як імпортувати документ

Перший імпорт від постачальника

Зміна налаштувань

Вікно «Налаштування імпорту»

Перебіг імпорту

Якщо щось не працює

Приклад конфігурації

Загальні налаштування

global

global.translation

fields

Стовпець файлу - source

Стале значення - value

Групи товарів - resolve: group_path

levels

detect

categories

Товар - resolve: find_or_create