Файл импорта объявлений

Что означает каждая колонка, как её заполнять, какие есть проверки и что делать с ошибками.

Как пользоваться инструкцией

Инструкция состоит из трёх частей:

1. Правильный файл — как выглядит правильно заполненный файл и как он проходит импорт.
2. Справочник колонок — что означает каждая колонка, что в ней писать и что именно проверяет система.
3. Частые ошибки — объяснение простыми словами и примеры «было → стало».

Примеры сделаны для категории «Паркинг»: в других категориях отличаются только колонки условий аренды и атрибутов.

Правила файла

• Формат. CSV или XLSX. В XLSX считывается только первый лист. Первая строка — заголовок, далее — объявления, по одному на строку.
• Объём. До 1000 строк с данными и до 20 МБ.
• CSV. Кодировка — UTF-8. Разделитель (запятая, точка с запятой или табуляция) система определяет сама по заголовку. Текст с запятыми или переносами строк берите в кавычки.
• Один файл — одна категория. Категорию выбирают до загрузки. Колонки атрибутов должны относиться именно к этой категории, поэтому проще всего взять шаблон нужной категории и не менять заголовки.
• Пустая ячейка — «не изменять». Пустая строка пропускается. Строка с пустым action тоже игнорируется, и это не ошибка.
• Блоки заменяются целиком. Цены, атрибуты, фото и видео: если в блоке заполнена хотя бы одна колонка, предыдущие значения этого блока удаляются и остаётся только то, что в файле.
• Лишние колонки. Неизвестные колонки система игнорирует.

Напоминание о правилах на шаге «Загрузка файлов».

---

Часть 1. Правильный файл: от шаблона до итога

Так выглядит успешный импорт трёх новых объявлений в категории «Паркинг». Ниже — что и где писать, а полный справочник колонок — в части 2.

1. Скачайте шаблон и возьмите из него заголовок колонок

На шаге 2 откройте блок с шаблонами и выберите тип файла. «Шаблон с примерами» содержит примеры строк, «Пустой шаблон» — только заголовки.

2. Заполните таблицу: по одному объявлению в строке

Основное: action = publish. adv_id для новых оставляем пустым. external_id — ваш уникальный код (owner-guide-1). Далее название, описание, адрес и координаты. Цвета заголовков: синий — служебные колонки, оранжевый — основные данные.

3. Добавьте фото и видео

В колонки photo_1 … photo_8 вписываем названия файлов из ZIP-архива (или прямые ссылки на изображения). Первое фото — главное. video_1 … video_5 — ссылки на видео, в примере их нет.

4. Укажите цены

Каждая цена — пара «период + стоимость»: час — 40, день — 300, месяц — 5500. main_price — период, который покажут в карточке как основной, price_unit — его единица (day).

5. Заполните условия аренды и атрибуты

zastava = 1 означает, что залог нужен, тогда zastava_deposit — его сумма. В колонках attr:… выберите значение из списка; несколько значений записывают через вертикальную черту, например Легковий транспорт|Мототранспорт.

6. Прикрепите таблицу и архив с фото и нажмите «Проверить»

Таблица — слева, ZIP — справа. Названия фото в таблице должны совпадать с названиями файлов в архиве.

7. Просмотрите результат проверки

В примере: «3 будет создано» и «0 с ошибками». Блок «Блоки, которые будут полностью заменены» напоминает, в скольких объявлениях заменяются цены, атрибуты и фото.

8. Подтвердите импорт

В окне нажмите «Применить импорт».

⚠️ Внимание: после этого отменить импорт невозможно.

9. Итог: новые объявления на модерации

Новые объявления всегда проходят модерацию. После одобрения они появятся на сайте.

---

Часть 2. Справочник колонок

В таблицах ниже: что означает колонка, как её заполнять и что именно проверяется. Если проверка не пройдена, в отчёте будет ошибка для этой строки (см. часть 3).

ℹ️ Значения из списков (периоды аренды, значения атрибутов) приведены так, как их принимает система. Значения атрибутов пишите точно как в шаблоне.

Служебные колонки

Колонка	Что это	Как заполнять	Что проверяется
action	Что сделать со строкой	publish — создать новое объявление или обновить существующее. archive — перенести в архив. Для возврата из архива тоже используют publish.	Колонка обязательна. Пустое значение: строка игнорируется, это не ошибка. Любое другое слово — ошибка строки.
adv_id	Идентификатор объявления в системе	Для новых объявлений оставьте пустым. Для обновления можно взять из файла «Экспорт своих объявлений».	Должен быть корректным идентификатором (например, 12345 не подойдёт). Объявление должно принадлежать вам и быть из выбранной категории.
external_id	Ваш собственный код объявления	Придумайте уникальный код для каждого объявления, например park-001. По нему система узнаёт объявление в следующих импортах. Без кода каждая строка создаёт новое объявление.	До 64 символов. Только латиница, цифры, дефис, подчёркивание и точка: без пробелов и кириллицы. Не повторяется в файле.

Основные данные

Колонка	Что это	Как заполнять	Что проверяется
title	Название объявления	Коротко: что, где, чем выгодно. Например: «Місце в паркінгу біля метро Позняки, Київ».	От 30 до 70 символов.
description	Описание объявления	Расскажите о расположении, условиях, охране, подъезде. Переносы строк допустимы, если весь текст взят в кавычки.	От 100 до 10 000 символов.
address	Адрес	Текстом: улица, дом, город.	До 255 символов. Обязателен для нового объявления. При обновлении игнорируется: адрес импортом изменить нельзя.
lat, lon	Координаты (широта и долгота)	Десятичные числа с точкой: 50.3992 и 30.6330. Указывайте точку, где действительно расположен объект.	Обязательны для нового объявления. Широта от −90 до 90, долгота от −180 до 180. Должны быть числами. При обновлении игнорируются.

Фото и видео

Колонка	Что это	Как заполнять	Что проверяется
photo_1 … photo_8	Фотографии объявления	Название файла из ZIP-архива (park1_1.jpg) или прямая ссылка на изображение (https://…). Первое фото — главное.	Для нового объявления нужно хотя бы одно фото, максимум 8. Блок заменяется целиком. Сами файлы (формат, размер, повреждения) проверяются только после подтверждения импорта, ошибки будут в отчёте о применении.
video_1 … video_5	Видео	Полная ссылка на видео, например https://www.youtube.com/watch?v=…	До 5 ссылок. Каждая должна быть ссылкой на видео, которое можно встроить на страницу. Блок заменяется целиком.

Цены

Колонка	Что это	Как заполнять	Что проверяется
price_N_period	Период аренды (N от 1 до 10)	година, день, тиждень, місяць. Можно с числом: «2 день», «3 тиждень». Русские варианты (час, неделя, месяц) тоже принимаются.	Период должен быть из списка. Не повторяется в одной строке. Для нового объявления нужна хотя бы одна пара.
price_N_value	Стоимость периода	Целое число в гривнах без копеек и пробелов: 300.	Целое число, не меньше нуля. Дробное (50.5), отрицательное (-50) и текст не подходят. Колонки пары заполняются вместе: с периодом без цены или ценой без периода строка не пройдёт. Блок цен заменяется целиком: было три цены, в файле одна — останется одна.
main_price	Какой период показывать в карточке как основной	Укажите один из заполненных периодов, например «день». Если оставить пустым, основным станет первый заполненный период.	Значение должно совпадать с одним из заполненных периодов. Влияет только на отображение в карточке, не на расчёты.
price_unit	Единица основной цены	hour, day или month (также по-украински: година, день, місяць). Должна соответствовать main_price.	Только значения из списка. Другое (например, «рік») — ошибка поля.

Условия аренды (категория «Паркинг»)

Колонка	Что это	Как заполнять	Что проверяется
zastava	Нужен ли залог	1 или 0. Также принимаются так/ні, да/нет, yes/no, true/false, + и −.	Любое другое слово («можливо») — ошибка поля.
zastava_deposit	Сумма залога	Целое число в гривнах: 1500. Указывайте, если залог нужен.	Обязательна, если zastava = 1. Должна быть целым числом.

Атрибуты категории (категория «Паркинг»)

Названия колонок атрибутов всегда начинаются с attr: и пишутся точно так, как в шаблоне. Значения берите только из списка ниже (он же на втором листе шаблона). Несколько значений записывают через вертикальную черту без лишних пробелов.

Колонка	Что это	Как заполнять	Что проверяется
attr:Тип паркування	Тип парковочного места	Багаторівневі, Відкрита площадка, Гараж, З навісом, Приватний двір, Підземний паркінг.	Обязателен для нового объявления. Значение должно быть из списка.
attr:Тип транспорту	Какой транспорт можно парковать	Вантажівки, Легковий транспорт, Мототранспорт, Мікроавтобуси. Несколько значений через вертикальную черту.	Обязателен для нового объявления. Значения должны быть из списка.
attr:Особливості	Дополнительные удобства	Відеонагляд, Доступ 24 / 7, Зарядка для електроавто, Освітлення, Охорона. Несколько значений через вертикальную черту.	Необязательный. Значение должно быть из списка.

ℹ️ Атрибуты — это блок. Если при обновлении вы заполнили хотя бы одну колонку attr:, система проверяет, что все обязательные атрибуты категории тоже заполнены, а предыдущие значения блока заменяются теми, что в файле.

---

Часть 3. Частые ошибки и что с ними делать

Ошибки бывают двух уровней:

• Ошибка файла останавливает проверку: система не видит ни одного объявления, поэтому файл нужно исправить и загрузить ещё раз.
• Ошибка строки касается одного объявления: остальные строки пройдут проверку, а проблемные можно исправить и загрузить отдельным импортом.

А. Ошибки всего файла

Они появляются на шаге 3 в блоке «Возникла ошибка». После исправления файла нажмите «Попробовать ещё», снова выберите категорию и загрузите файл.

1. Нет обязательной колонки

Что это значит. В заголовке таблицы отсутствует колонка action. Без неё система не знает, что делать со строками.

Как исправить. Добавьте колонку action (и не удаляйте другие колонки шаблона). Надёжнее всего — скопировать заголовок из шаблона.

2. Две колонки с одинаковым названием

Что это значит. В заголовке колонка title встречается дважды: на 3-й и 16-й позициях. Система не может выбрать, какое значение правильное.

Как исправить. Оставьте только одну колонку с таким названием. Проверьте, что при копировании не добавились дубликаты.

3. Колонка другой категории

Что это значит. В таблице есть колонка атрибута, которой нет в выбранной категории (здесь attr:Тип техніки из другой категории). Файл составлен для другой категории.

Как исправить. Либо выберите правильную категорию, либо скачайте шаблон нужной категории и перенесите данные в него.

4. В файле только заголовок

Что это значит. В таблице нет ни одной строки с данными. Пустые строки пропускаются, поэтому система не нашла объявлений.

Как исправить. Добавьте хотя бы одну строку с объявлением. Проверьте, что сохранён правильный лист: в XLSX читается только первый.

5. Неподдерживаемый формат файла

Что это значит. Для таблицы подходят только .csv и .xlsx. Другие форматы (.txt, .xls, .ods, .xlsm) не принимаются, защищённые паролем файлы тоже.

Как исправить. Сохраните таблицу как CSV (UTF-8) или XLSX и загрузите её ещё раз.

ℹ️ Есть и другие ошибки файла, которые возникают реже: файл больше 20 МБ, больше 1000 строк или 300 колонок, файл не удалось прочитать (непонятная кодировка), файл защищён паролем. Исправление во всех случаях одно: уменьшите или восстановите файл и загрузите его снова.

Б. Ошибки отдельных строк

Если проверка файла прошла, но часть строк содержит ошибки, на шаге 4 будет счётчик «с ошибками» и кнопка «Скачать отчёт с ошибками». Остальные строки пройдут импорт. В примере 26 строк: 2 создадутся, 1 пропущена (пустой action), 23 с ошибками.

Отчёт — это ваш файл, в котором остались только проблемные строки, а в двух последних колонках, errors и warnings, написано, что именно не так. Найти объявление в отчёте можно по колонке external_id. Исправьте ячейки, уберите колонки errors и warnings и загрузите исправленные строки отдельным импортом. На снимке ниже показаны только колонки external_id и errors.

Фрагмент отчёта: в квадратных скобках — код ошибки и колонка, далее — пояснение системы.

В таблицах ниже: что написано в отчёте → что это значит → как исправить. Код в квадратных скобках можно использовать для поиска в этой инструкции.

Название, описание, адрес, координаты

Что написано в отчёте	Что это значит	Как исправить (было → стало)
[E_FIELD_LENGTH/title] title must be 30–70 characters, got 10	Название слишком короткое или слишком длинное. Для нового названия нужно от 30 до 70 символов.	Было: «Паркомісце» (10). Стало: «Місце в паркінгу біля метро Позняки, Київ» (41).
[E_FIELD_LENGTH/description] description must be 100–10 000 characters, got 23	Описание слишком короткое (или слишком длинное).	Было: «Гарне місце біля метро.» Стало: описание от 100 символов: уровень паркинга, охрана, освещение, подъезд.
[E_FIELD_REQUIRED/address] address is required for new advertisements	Для нового объявления не указан адрес.	Впишите адрес: «вул. Анни Ахматової, 13, м. Київ».
[E_FIELD_TYPE/lat] lat/lon must be numeric decimal values; got lat="п'ятдесят"	В координатах написано не число.	Было: «п'ятдесят». Стало: 50.3992 (с точкой).
[E_FIELD_COORDINATES/lat] coordinates out of range: lat 95, lon 30.6	Широта должна быть от −90 до 90, долгота от −180 до 180.	Было: 95. Стало: 50.3992. Проверьте, что широта и долгота не перепутаны и записаны числом.

Цены

Что написано в отчёте	Что это значит	Как исправить (было → стало)
[E_FIELD_PRICE_PAIR/price_2_period] price_2: period and value must be provided together	В паре «период + стоимость» заполнена только одна ячейка.	Заполните обе: price_2_period = місяць и price_2_value = 5500. Или очистите обе.
[E_FIELD_TYPE/price_1_value] price value must be a non-negative integer, got "50.5"	Цена должна быть целым числом не меньше нуля: без копеек, минуса и букв.	Было: 50.5, -50 или «п'ятдесят». Стало: 50.
[E_FIELD_TYPE/price_2_period] unrecognised rental period "квартал"	Такого периода аренды нет. Доступны: година, день, тиждень, місяць (или час, день, неделя, месяц).	Было: «квартал». Стало: «місяць» (или запишите цену за три месяца как «3 місяць»).
[E_FIELD_PRICE_DUPLICATE/price_2_period] period "година" appears more than once in this row	Один и тот же период указан в двух парах.	Оставьте одну пару на каждый период.
[E_FIELD_TYPE/price_unit] price_unit "рік" is not allowed; valid: hour, day, month	Единица основной цены не из списка.	Было: «рік». Стало: day (или hour, month).

Условия аренды, атрибуты, видео, фото

Что написано в отчёте	Что это значит	Как исправить (было → стало)
[E_FIELD_TYPE/zastava] zastava must be a boolean (yes/no/1/0/…), got "можливо"	Для залога допустимы только «да/нет».	Было: «можливо». Стало: 1 или 0.
[E_FIELD_REQUIRED/zastava_deposit] zastava_deposit is required when zastava is set	Залог нужен, а сумма не указана.	Впишите сумму: 1500. Или измените zastava на 0.
[E_REF_INVALID/attr:Тип паркування] value "Підвал" is not in the reference list	Такого значения нет в списке допустимых для этой колонки.	Было: «Підвал». Стало: значение из списка, например «Підземний паркінг».
[E_FIELD_REQUIRED/attr:Тип транспорту] attr:Тип транспорту is a required attribute of this category	Обязательный атрибут категории не заполнен.	Заполните: Легковий транспорт. То же правило действует и при обновлении, если заполнен хотя бы один атрибут.
[E_FIELD_VIDEO_INVALID/video_1] video_1: "це не посилання" is not a recognised video embed URL	В колонке видео должна быть ссылка на видео, которое можно встроить.	Было: «це не посилання». Стало: https://www.youtube.com/watch?v=… или очистите ячейку.
[E_FIELD_REQUIRED/photo_1] at least one photo is required for new advertisements	В новом объявлении нет ни одного фото.	Укажите в photo_1 название файла из ZIP или ссылку на изображение.

Ключи и действие строки

Что написано в отчёте	Что это значит	Как исправить (было → стало)
[E_FIELD_LENGTH/external_id] external_id must be ≤64 chars and contain only letters, digits, '-', '_', '.'; got "оголошення 1"	В коде есть кириллица, пробел или другие запрещённые символы, либо он слишком длинный (более 64).	Было: «оголошення 1». Стало: park-001.
[E_ROW_ACTION_INVALID/action] action must be "publish" or "archive", got "створити"	В колонке action разрешены только publish и archive (или пусто, чтобы пропустить строку).	Было: «створити». Стало: publish.
[E_ROW_DUPLICATE_KEY/external_id] external_id "dup-1" appears in multiple rows (2 occurrences)	Один код повторяется в файле. Отклоняются все строки с этим кодом.	Дайте каждому объявлению уникальный external_id: dup-1, dup-2.
[E_FIELD_TYPE/adv_id] adv_id must be a valid UUID, got "12345"	В колонке adv_id указан не идентификатор объявления.	Для новых объявлений оставьте пустым. Для обновления возьмите значение из файла «Экспорт своих объявлений».
[E_ROW_NOT_FOUND/external_id] Оголошення не знайдено	Вы просите заархивировать объявление, которого с таким кодом у вас нет.	Проверьте external_id. Если объявление ещё не создано, архивировать нечего.
[E_ROW_CATEGORY_MISMATCH/adv_id] advertisement … belongs to a different category and cannot be updated via this import	Объявление с таким external_id уже существует в другой категории. Категорию импортом изменить невозможно.	Используйте другой external_id для нового объявления или импортируйте эту строку в той категории, где объявление уже есть.

В. Ошибки фото и видео (после подтверждения)

Изображения проверяются только после того, как вы нажали «Применить импорт». Поэтому этих ошибок не видно на шаге 4: они попадают в отчёт о применении на шаге 6. Объявление с проблемным фото не создаётся, остальные объявления импортируются.

Код в отчёте	Что это значит	Как исправить
IMG_NOT_FOUND_IN_ARCHIVE	В таблице указано название файла, которого нет в ZIP-архиве.	Сверьте названия фото в таблице и в архиве: буквы, цифры и расширение должны совпадать.
IMG_FETCH_FAILED	Фото по ссылке не удалось загрузить (ссылка не работает или не ведёт на изображение).	Проверьте ссылку в браузере: она должна открывать именно изображение. Или добавьте файл в архив.
IMG_FORMAT_NOT_ALLOWED	Формат файла не поддерживается.	Используйте JPEG, PNG или WebP.
IMG_TOO_SMALL / IMG_TOO_LARGE	Файл слишком большой или слишком маленький по размеру.	Замените фото на более качественное и повторите импорт.
IMG_CORRUPTED	Файл изображения повреждён.	Сохраните фото заново из редактора и добавьте в архив.
IMG_DUPLICATE_MAIN	Одно и то же фото указано главным в двух разных объявлениях.	Используйте для каждого объявления собственное главное фото.

---

Перед загрузкой: короткий чек-лист

• Беру заголовок из шаблона своей категории, ничего не удаляю и не переименовываю.
• У каждого объявления уникальный external_id латиницей. Для новых объявлений adv_id пустой.
• Название 30–70 символов, описание от 100, адрес и координаты заполнены.
• Цены — целые числа, каждый период со стоимостью, main_price и price_unit соответствуют заполненным ценам.
• Значения атрибутов — из списка, обязательные атрибуты заполнены.
• Названия фото в таблице совпадают с названиями файлов в ZIP.
• После проверки открываю отчёт, если есть «с ошибками», исправляю их и загружаю отдельно.