Importing documents

2026-07-202026-10-05

Sklad loads supplier delivery notes and price lists from XLSX, XLS, CSV and XML files. The file is processed by the abrest service: it finds the file's goods in the catalogue, creates missing ones together with their groups and characteristics, and builds a new document from the file's rows.

Before you start

The abrest service is running on the server.
Your work profile has an abrest: section with enabled: true and the service address - the same way as the abasyn: section for online shop synchronisation.
Services are activated for the profile with the service activation button in the configuration editor.
For translating names and finding goods by similar names - a configured local LLM. Import works without it, but a good is then found only by an exact match.

How to import a document

Open Прихідні накладні (delivery notes) or Прайси (price lists). Other documents do not support import.
Select the supplier in the contragent list. Import settings are kept separately for each supplier and each document kind: a supplier's price list and delivery note have different settings. A delivery note is received into the firm selected on the form and into your workstation's storage.
Файл → Імпорт документу... and pick the file.

If a document of this kind has already been imported from this supplier, the import starts straight away with the saved settings. Otherwise automatically composed settings appear first.

First import from a supplier

abrest analyses the file and proposes settings:

finds the header row;
recognises columns by their headers: item name («Назва», «Найменування», «Товар», «Name»), price («Ціна», «Price»), barcode («Штрихкод», «EAN», «Barcode»), article («Артикул», «SKU»), description («Опис», «Характеристики»);
a column whose header matches a document field name is written to that field;
proposes the remaining columns as item characteristics;
looks for group rows by cell formatting, merged cells or Excel row grouping (the "plus" buttons left of the row numbers);
if it recognises the language of the names, adds translation to English. If you do not need it, delete the translation section.

The proposal opens in the Налаштування імпорту (import settings) window. Review it and press OK - the settings are saved for the supplier and the import starts. Cancel aborts the import without saving anything.

Changing the settings

Saved settings open from the contragent table: the menu of the table's top-left cell → Редагувати параметри імпорту. If the selected supplier has no settings yet, a general template opens; after OK it becomes this supplier's settings, and the file is no longer analysed on import.

The import settings window

Settings are written in YAML - indentation with spaces matters. The window helps:

To the right of each field in the fields section the matching document column title is shown in grey. «Віртуальне поле» (virtual field) means the document has no such column: the value becomes an item characteristic or is used only during processing.
Ctrl+J on a bg_color value opens a colour picker; on a yes/no value it offers true or false.
A mark next to the line number shows a problem. A red circle is an error: the settings cannot be saved until it is fixed. A yellow triangle is a warning, such as an unknown setting name: on saving the program lists the warnings and asks whether to save anyway.
On saving, the cursor jumps to the first problem line.

Import progress

A panel appears over the form:

a title with counters «Імпорт: N завантажено, M пропущено...» (N loaded, M skipped);
a progress bar with a percentage;
after 10 seconds - time elapsed and roughly how much remains;
a list of skipped rows as «[Reason] Рядок N: description»:
- [Помилка] (error) - the row could not be processed, the description says why;
- [Виключено] (excluded) - the row belongs to a category with the exclude action;
- [Без полів] (no fields) - the row has none of the configured columns.

Rows are counted from the header row, without group rows, so the number does not always match the Excel row number.

The new document appears in the list as soon as the first rows are loaded. Сховати (hide) hides the panel; the import continues and the counters stay visible in the status bar. At the end the panel title shows «Імпорт завершено. Завантажено: N, пропущено: M.» or «Імпорт завершено з помилками...» - then the reason is added as the last line of the list.

Troubleshooting

Message	Cause
«Службу Abrest не налаштовано для хоста ...»	The profile has no `abrest:` section, or it has `enabled: false`.
«У вас немає токена авторизації для доступу до ...»	Services are not activated for the profile.
«Потрібно вибрати контрагента для роботи з документом»	No supplier selected.
«... не підтримує імпорт через Abrest»	Import was started from a form other than delivery notes or price lists.
`Header row not found`	The file has no row containing every header from the settings. Headers are compared exactly, including case and spaces.
`Unknown field(s) in import config`	A field in `fields` is not a document column and has no `tag`. Rename it to a document column, add `tag`, or delete it.

Complete example

A price list in XLSX with a three-level category hierarchy recognised by row formatting, supplier category overrides, characteristics, and translation from Ukrainian to English.

---
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: Дата імпорту
...

What happens here:

The header row is the first row containing «Назва товару», «Штрихкод», «Артикул», «Ціна», «РРЦ» and «Виробник». Everything above it is skipped.
Bold rows in 14-point font are categories, bold rows on green are subcategories, rows on light green are product types. Such rows are not imported; they set the group for the goods below them.
Categories and subcategories are created as catalogue groups (depth: 2), while the product type becomes the «Тип товару» characteristic (default: tag). The category name is also written to the «Категорія» characteristic.
Goods of the «Власна марка» category go into the existing group 42, rows of the «Знято з виробництва» category are dropped, goods of «Змішані добрива» stay in the group one level up, without a subgroup of their own.
The barcode is used both for finding the item and for the document's «Код товару» column; the price goes to «Поточна закупка», the recommended retail price to «Ціна продажу».
«Виробник» and the import date become characteristics of new goods; they are not written to the document because a price list has no such columns.

General settings

Key	Required	Purpose
`file_type`	yes	`xlsx`, `xls`, `csv` or `xml`
`sheet`	no	XLSX/XLS sheet number, counting from `0` (the first by default)
`global`	no	Settings for the whole file
`fields`	yes	What is written and from where - one entry per field

`global`

Key	Default	Description
`root_group_id`	`0`	ID of the catalogue group inside which the file's groups are looked up and created. `0` is the catalogue root.
`tovar_type`	`1`	Type of created goods: `1` - goods, `2` - service/work
`translation`	-	Name translation (see below)

`global.translation`

Key	Default	Description
`from`	-	File language: `uk`, `en`, `de`, `pl`, ...
`to`	-	Target language
`translate_items`	`true`	Translate item names
`translate_groups`	`true`	Translate group names
`translate_tags`	`true`	Translate characteristic values

Translation works only if both from and to are set and an LLM is configured in the abrest service. Each name is translated once.

`fields`

Each entry is a document field or a helper field. The entry name is the document column name in upper case; the settings window shows its title next to it. The main columns:

Price list		Delivery note
`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`	Примітка

An entry with any other name is allowed only if it has tag or value.

There are four kinds of entries.

File column - `source`

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

Key	Required	Description
`source`	yes	Column header in the file, exact and case-sensitive
`type`	no	`number` or `integer` - keeps only the number from the text; `0` if there is none
`tag`	no	Also write the value as an item characteristic with this name

Constant value - `value`

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

Key	Required	Description
`value`	yes	Value for every row; `today` - today's date
`tag`	no	As for `source`

Item groups - `resolve: group_path`

Finds group rows in the file and places goods into catalogue groups, creating missing ones.

`levels`

Group levels - from the broadest to the narrowest. When a row of a higher level appears, all lower levels are reset.

Key	Required	Description
`name`	yes	Any name for the level
`tag`	no	Also write this level's group name as an item characteristic with this name
`detect`	yes	How to recognise a group row of this level

`detect`

Key	Default	Description
`column`	`0`	Column number, counting from `0`, that is checked and from which the group name is taken
`method`	`single_value`	Recognition method (table below)
`outline_level`	-	Excel row grouping level, for `method: outline_level` (XLSX only)
`bg_color`	-	Cell background colour `RRGGBB`
`font_color`	-	Font colour `RRGGBB`
`font_size`	-	Font size
`font_name`	-	Font name, case-insensitive
`bold`	-	Bold: `true` or `false`
`italic`	-	Italic: `true` or `false`

If several formatting attributes are set, all of them must match.

Method	A row is a group if
`single_value`	at most one cell in the row is filled (and the formatting matches, if set)
`merged_cells`	the cell in `column` is merged with its neighbours (XLSX/XLS; for CSV/XML - as `single_value`)
`formatting`	the formatting of the cell in `column` matches. For files where group rows are filled in the same way as item rows
`outline_level`	the row's Excel grouping level equals `outline_level`, and the row qualifies as `single_value` or `merged_cells`

`categories`

Optional. Needed when the supplier's categories do not match the groups of your catalogue. Without it the whole category chain is created as groups.

Key	Description
`depth`	Levels 1 to `depth` are created as groups. Deeper levels get the `default` action. `0` - all levels are created as groups.
`default`	Action for levels deeper than `depth`: `create`, `map`, `tag`, `inherit` or `exclude`
`default_tag_name`	Characteristic name for `default: tag`
`default_group_id`	Group ID for `default: map`
`mapping`	Rules for specific categories, by exact name, case-insensitive

A mapping rule:

Key	Needed for	Description
`source`	all	Category name in the file
`action`	all	`create`, `map`, `tag`, `inherit` or `exclude`
`group_id`	`map`	ID of an existing catalogue group
`tag_name`	`tag`	Characteristic name; without it - `default_tag_name`

Action	Result
`create`	Find or create a group with this name inside the previous one
`map`	Use the existing group `group_id`; the following levels are looked up inside it
`tag`	Do not create a group; write the category name as an item characteristic
`inherit`	Stop here: the item stays in the last group found
`exclude`	Skip the row entirely - it does not reach the document and no item is created

Item - `resolve: find_or_create`

Finds the item in the catalogue and creates it if not found.

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

Key	Required	Description
`name_source`	yes	Header of the item name column
`ean_source`	no	Header of the barcode column
`article_source`	no	Header of the supplier article column

Lookup order:

By barcode, article and name among goods already known from this supplier.
If an LLM and translation are configured - by name similarity. An item found this way is remembered under the supplier's barcode and article, and next time is found at step 1.
Otherwise a new item is created in the group from GROUP_ID. If no group was determined, the item is created without a group and without a link to the supplier.

Processing order

First the header row is located - the first row containing every header named in source, name_source, ean_source and article_source. Everything above it is skipped. Then for each row to the end of the sheet:

If the row matches the detect of some level, it is remembered as the current group and is not imported.
Column values are distributed to the entries in fields.
type: number and value are applied.
The item group is determined. A row from a category with the exclude action is skipped.
The item is found or created.
Only for newly created goods: characteristics are written (tag of fields and levels, characteristics from categories) and translation runs. Re-importing does not change the characteristics of goods already in the catalogue.
The row is added to the document.

Importing documents

Before you start

How to import a document

First import from a supplier

Changing the settings

The import settings window

Import progress

Troubleshooting

Complete example

General settings

global

global.translation

fields

File column - source

Constant value - value

Item groups - resolve: group_path

levels

detect

categories

Item - resolve: find_or_create