Файл імпорту оголошень

Що означає кожна колонка, як її заповнювати, які є перевірки та що робити з помилками.

Як користуватись інструкцією

Інструкція має три частини:

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.
• Після перевірки відкриваю звіт, якщо є «з помилками», виправляю їх і завантажую окремо.