Як завантажити каталог через API маркетплейсу чи облікової системи

Що вміє завантаження каталогу через API

• Перенесення каталогу — назви, ціни, залишки, категорії, фото й характеристики приходять напряму, в актуальному стані на момент звернення.
• Категорії й виробники — знаходяться серед ваших за назвою, а відсутні створюються.
• Захист ваших правок — перемикачі «Не оновлювати» і «Фіксована ціна» в картці товару.
• Замовлення тим самим підключенням — у більшості майданчиків вмикаються окремим перемикачем.
• Оновлення за розкладом — каталог оновлюється сам, кожне звернення лишає слід у журналі.

API беруть тоді, коли інший бік — система з власним програмним інтерфейсом, і у вас є до нього доступ (ключі, токен чи логін інтеграції). Для найбільших майданчиків є окремі статті з їхніми ключами й особливостями:

Перелік у вікні імпорту ширший і поповнюється. Інтеграції, що приносять тільки замовлення (каси, частина маркетплейсів), зібрано в огляді імпорту замовлень через API.

1

Перелік доступних типів підключення

1. Перелік доступних типів підключення — всі API-джерела (Shopify, eBay, Wix, Amazon, WooCommerce та інші) зібрані в одному списку вибору шаблону.

Де це і хто має доступ

Меню

Довідники → Операції → Завантаження даних

Захист картки

картка товару → секція «Захист під час імпорту»

Право доступу

вікно «Завантаження даних» у «Правах груп»

Підготувати

ключі доступу з кабінету майданчика з правом читання товарів

Що потрібно від майданчика: ключі доступу

Ключі видає сама система-джерело: майже в кожного маркетплейсу чи платформи є розділ для розробників або інтеграцій, де створюється ключ, токен чи пара «логін-пароль застосунку». Для одних сервісів достатньо одного токена, для інших потрібні кілька значень — точний перелік є в статті кожного майданчика з переліку.

Як підключити

1. Створіть шаблон і оберіть потрібну інтеграцію зі списку.
2. Введіть ключі доступу й натисніть «Перевірити підключення» (є в більшості підключень, у шаблоні Rozetka її немає). Кнопка звертається до майданчика тими самими ключами, що й прогін, і відповідає назвою магазину або текстом відмови — так швидше знайти зайвий пробіл у токені.
3. У секції «Вибір даних для завантаження» увімкніть набори даних (які є). Товари й замовлення — окремі перемикачі: ввімкнули лише замовлення — товари не приїдуть, і навпаки.
4. Натисніть «Завантажити» тоді, коли можете відразу подивитися на результат. Перевірте на кількох товарах назви, ціни, картинки й категорії, а також що сталося з картками, які у вас уже були (як знайти).
5. Коли все працює, поставте шаблон на розклад.

Один шаблон — одне підключення до одного акаунта. Під кожен майданчик чи акаунт заводять окремий шаблон зі своїми ключами й розкладом.

Що переноситься в каталог

Через API в каталог приходить те саме, що й з файлу: назви, ціни, залишки, категорії, картинки й характеристики — рівно те, що система-джерело віддає у своєму інтерфейсі. Різниця в тому, що дані завжди свіжі: не зліпок на момент вивантаження, а стан на момент звернення.

У шаблоні вмикаються набори даних: «Товари», «Категорії», «Фото», «Атрибути», «Опції», «Виробники», «Замовлення». Вибору окремих полів немає: ввімкнено «Товари» — назва, опис, ціна й залишок приїжджають одним пакетом.

Товари не задвоюються: програма шукає заведену картку за парою «артикул виробника + назва» (маркетплейси артикул виробника зазвичай не віддають, тож на практиці — за назвою). Знайдену картку прогін перезаписує, а не додає другу.

Категорії й виробники, які створює прогін

Категорія приходить із джерела назвою або повним шляхом. Програма спершу шукає вашу категорію з такою самою назвою й кладе товар у неї, і лише якщо не знаходить — створює нову гілку. Тому дублів на кшталт «Ноутбуки (2)» не з'являється, доки назви збігаються.

• Товари без категорії лягають у службову категорію «Товари - код джерела», яка створюється вимкненою і без участі у вивантаженнях. Розкладайте картки звідти вільно: місце в дереві повторний прогін не змінює. Видалена категорія з'явиться знову порожньою, щойно в джерелі знайдуться товари без категорії. Порядок розкладання — в огляді завантаження даних.
• Виробники заводяться так само: новий бренд із джерела додається в довідник із позначкою підключення. Не перейменовуйте такі бренди: наступний прогін не знайде бренд під новою назвою, заведе його ще раз під старою і перечепить товари. Назву бренда змінюйте на боці майданчика.

Яким документом лягає замовлення

Якщо перемикач «Замовлення» ввімкнено, кожне замовлення з майданчика заводиться документом «Замовлення покупця» — непроведеним. Сам тип документа товар не списує, а резерв з'являється лише після проведення: завантаження замовлень наявність у каталозі не зрушить.

Статус документа береться зі зіставлення статусів майданчика з вашими — кнопками «Статуси замовлення», «Статуси доставки» й «Статуси оплати» в секції «Повʼязані налаштування» картки шаблону. Незіставлений статус дає перший статус довідника — «як нове».

Повторне завантаження дубля не створює: документ шукається за номером замовлення в джерелі разом із кодом джерела. Як замовлення проходить пошук покупця й товарів — в огляді імпорту замовлень.

Що повторний прогін робить із вашими правками

Повторне оновлення перезаписує все, що майданчик віддав у цьому прогоні: назву, опис, ціну, стару ціну, кількість, наявність, бренд, артикул, теги й ознаку «увімкнено/вимкнено». Виправили назву або дописали опис у Elbuz — наступний прогін поверне текст із майданчика без попередження.

Що повторний прогін у вже заведених товарів не чіпає:

• Фото. Картинки додаються тільки новим карткам: замінене вами фото не перезаллється, але й нові фото з майданчика до старої картки не доїдуть.
• Характеристики. Наявні значення лишаються. Виняток — Rozetka: вона дописує ті, яких у картці ще немає, не зачіпаючи наявних.
• Місце в дереві категорій. Перенесли картку у свою категорію — там вона й лишиться. Виняток — Horoshop: картці без «Не оновлювати» він ставить категорію, яку товар має на сайті.
• Адресу сторінки (ЧПУ). Вона проставляється лише в момент створення картки.

Щоб закріпити картку цілком, відкрийте її, секція «Захист під час імпорту», перемикач «Не оновлювати». Такій картці прогін не змінює ні ціну, ні залишок, ні наявність, ні бренд.

У прямих підключеннях до майданчиків позначка тримає й назву з описом; у завантаженні з «Мого складу» і SalesDrive назву й опис фід перезапише попри неї. Той самий прапорець є колонкою «Не оновлювати (прапор)» у вікні «Товари» — за нею зручно і фільтрувати, і проставляти позначку прямо в сітці.

1

Не оновлювати

2

Фіксована ціна

1. Не оновлювати — імпорт не змінює цей товар.
2. Фіксована ціна — імпорт не змінює ціну товару.

Два майданчики пишуть в одну картку

Якщо два підключення тягнуть той самий товар, вони сходяться в одній картці: вона шукається за назвою (і за артикулом виробника, коли джерело його віддає), а не за майданчиком. У полі лишається значення того прогону, що завершився останнім; пріоритету джерел у шаблонах немає.

Позначка «Джерело: назва» в картці при цьому не перемикається — там лишається шаблон, який картку створив, тож дивитися по ній, хто востаннє записав ціну, не можна. Розвести два джерела можна лише перемикачем «Не оновлювати» на картці. Загальні правила — в огляді завантаження даних.

Що буде з товаром, який зник із джерела

Прямі підключення до майданчиків працюють за принципом «що прийшло — те й оновили». Товар, якого в цьому прогоні не було, лишається в каталозі з останньою ціною й залишком: не деактивується, залишок не обнуляється, у журналі про нього нічого. Зняті з продажу позиції прибирайте руками, інакше вони потрапляють у вивантаження зі старими цифрами.

Інша річ — коли товар змінив стан на самому майданчику. Ознака «увімкнено» приходить із джерела: у Shopify товар зі станом, відмінним від Active, приїде в Elbuz вимкненим. Rozetka окремим проходом забирає стан карток у кабінеті — з помилками, невалідні, на модерації, приховані модератором, поза допустимим діапазоном ціни — і пише кількість по кожній групі в журнал.

Галочка «Видаляти записи в базовому каталозі, яких немає в завантаженому файлі» в секції «Що завантажувати» реально працює лише там, де каталог приходить фідом, — у «Мого складу» і SalesDrive.

Оновлення за розкладом

Шаблон ставлять на розклад, і Elbuz сам звертається до джерела: нові товари додаються, ціни й залишки оновлюються. Частота — від кількох разів на день до раз на добу; великі маркетплейси обмежують частоту запитів, тож надто частий розклад впирається в їхні ліміти.

Розклад працює, доки зв'язок із джерелом живий. Маркетплейс недоступний, ключі протухли чи відкликані — чергове оновлення не відбудеться, і це видно в журналі. Тому перші тижні журнал переглядайте.

Два завантаження за розкладом одночасно не йдуть: друге лишає в журналі «Скасовано завантаження за розкладом, причина — завантажується інший шаблон» і чекає наступного спрацювання. Замок прогону, що помер без запису в журнал, знімається сам (як).

Наприкінці прогону програма сама перераховує поля за вашими формулами, застосовує правила націнки до нових товарів і оновлює їхні пошукові дані. На вітрину й майданчики каталог сам не поїде: це робота окремого «Вивантаження даних» зі своїм шаблоном і розкладом (коли завантажене поїде далі).

Вимкнути шаблон чи видалити

Пілюля «Активний» / «Вимкнений» у шапці картки знімає шаблон з розкладу; ключі, налаштування й завантажені товари лишаються. Кнопка «Завантажити» працює й на вимкненому шаблоні: щоб підключення точно нічого не змінило, приберіть ключі або захистіть картки товарів.

1

Стан шаблону

2

Завантажити

3

Історія запусків

1. Стан шаблону — у демо показано «Вимкнений».
2. Завантажити — запускає завантаження за шаблоном.
3. Історія запусків — журнал попередніх завантажень.

Видалений шаблон не повертається, ключі доведеться вводити наново; разом із ним видаляються завдання розкладу. Товари, категорії, виробники й позначка джерела в картках лишаються. Системні шаблони видалити не можна. Детальніше — в огляді завантаження даних.

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

Журнал прогону відкривається в Центрі операцій — правій панелі, яка не блокує роботу: картку шаблону можна закрити.

• Каталог приходить сторінками, на кожну — свій рядок: «Shopify: сторінка каталогу 3, отримано товарів: 75».
• У кінці — підсумок: «каталог завантажено, товарів: 240».
• Далі «Оновлення значень на основі формул», у частини підключень — «Перевірка цілісності даних» та «Індексування товарів», і останній рядок «Завантаження даних завершено!» з приписом «Витрачено часу».
• Помилка майданчика пишеться червоним, із текстом причини від майданчика; картка операції в Центрі закривається як помилкова, якщо є хоча б один такий рядок.

У сітці «Товари» оновлення підтверджують колонки «Дата оновлення» (ставиться кожній зміненій картці), «Джерело: назва» (шаблон, яким картку заведено) і «Джерело: код» (код майданчика).

Колонки «Дата завантаження» і «Витрачено часу» у списку шаблонів оновлюються навіть тоді, коли майданчик віддав помилку, тож про успіх судять за журналом. Довшу історію показує кнопка «Історія запусків» у шапці картки шаблону: «Запусків за період», «Середня тривалість», «Найдовший», «З помилками».

Якщо зв'язок обірвався посеред прогону

• Товари пишуться в каталог пачками по 500, щойно набереться пачка. Обрив ділить результат надвоє: дійшле лежить оновленим, решта — зі старими даними.
• Негайний повтор безпечний: прогін перезапише ті самі позиції й добере решту, дублів не буде ні в каталозі, ні в замовленнях.
• При перевищенні ліміту звернень або помилці сервера запит повторюється три-чотири рази, залежно від майданчика, з паузою, що зростає; лише потім прогін зупиняється з помилкою. Одного запиту програма чекає від 60 до 300 секунд.
• Стелі на кількість позицій немає. Дані забираються сторінками по 25–1000 позицій, у частини підключень — із паузою між сторінками, щоб не впертися в ліміти.

Якщо підключили не те

Товари, які створило підключення, відбирає фільтр у вікні «Товари» за колонкою «Джерело: назва» або «Джерело: код»; далі виділіть рядки й видаліть пакетом — програма перепитає «Видалити вибрані товари?». Фільтр працює й після видалення шаблону.

Картки, які вже були у вас і які підключення лише перезаписало, цей фільтр не покаже — у них лишилося старе джерело. Їх збирає відбір за колонкою «Дата оновлення».

Повернути старі значення масово нема чим — журналу правок товару в програмі немає. Окремо зберігається лише ціна: якщо ведення історії цін увімкнене, попередню видно в картці товару, блок «Історія ціни товару». Масові дії для виправлення — в огляді завантаження даних.

Сценарії

Уперше перенести каталог із майданчика в Elbuz

Задача: товари вже живуть на Shopify, Rozetka чи іншому майданчику, а вести каталог ви хочете в Elbuz.

Що ввімкнути: шаблон потрібного типу, ключі у формі й кнопка «Перевірити підключення»; у секції «Вибір даних для завантаження» — «Товари» і, якщо потрібні картинки, «Фото»; далі «Завантажити».

Що вийде: кожен товар стає карткою базового каталогу з позначкою джерела. Товар, назва якого збіглася з уже заведеною карткою, нової картки не отримає — прогін перепише наявну. Перейменуєте товар на майданчику — наступний прогін заведе нову картку, а стара лишиться з останніми цифрами. На вітрину нічого не поїде, доки не відпрацює «Вивантаження даних».

Ціну ставлю сам, залишок — із майданчика

Задача: кількість і наявність потрібні з майданчика, а ціну ви рахуєте в Elbuz.

Що ввімкнути: у картці товару, секція «Захист під час імпорту», перемикач «Фіксована ціна».

Що вийде: прогін прямого підключення оновить залишок, наявність, назву й опис, а ціни лишить вашими. «Не оновлювати» для цієї задачі не підходить: він заморозить і залишок.

Кілька карток я веду вручну

Задача: частину товарів ви переписали під себе — назву, опис, характеристики — і не хочете, щоб прогін повертав текст із майданчика.

Що ввімкнути: перемикач «Не оновлювати» у секції «Захист під час імпорту» картки; для багатьох карток одразу — колонка «Не оновлювати (прапор)» у сітці «Товари».

Що вийде: пряме підключення таку картку пропускає цілком. Залишок із майданчика до неї більше не доїде — його доведеться вести самим.

Той самий товар продаю на двох майданчиках

Задача: один асортимент виставлено на двох майданчиках або у двох акаунтах, і обидва треба звести в один каталог.

Що ввімкнути: окремий шаблон на кожне підключення зі своїми ключами і своїм розкладом.

Що вийде: товари з однаковою назвою сходяться в одній картці зі значеннями прогону, що завершився останнім (чому). «Не оновлювати» закриває картку від обох підключень одразу — вибрати, котре з них пише, не можна.

Що робити, коли каталог не завантажується

Часті запитання

Чим API кращий за файл?

Не треба нічого вивантажувати й завантажувати руками: підключилися за ключами один раз, поставили на розклад — і каталог оновлюється сам, напряму з джерела.

Одне підключення може тягнути і товари, і замовлення?

Так, якщо інтеграція це вміє: у шаблоні окремі перемикачі «Товари» і «Замовлення» (хто що вміє).

Що буде з товарами, якщо видалити шаблон?

Вони лишаться в каталозі разом із позначкою джерела. Непотрібні відберіть у вікні «Товари» за колонкою «Джерело: назва» і видаліть пакетом.

Мого майданчика немає в списку?

Перевірте перелік прямо у вікні імпорту — він ширший і поповнюється. Немає API-інтеграції — завантажте каталог файлом: готовим форматом або універсальним імпортом.

Скільки майданчиків можна підключити одночасно?

Скільки завгодно: під кожен акаунт — окремий шаблон зі своїми ключами й розкладом, і всі вони наповнюють один базовий каталог.

Суміжні теми

• Якщо потрібно забирати ще й замовлення — Імпорт замовлень через API.
• Якщо треба зрозуміти загальну механіку завантаження, обриву й відкату — Огляд завантаження даних.
• Якщо API у джерела немає, а є файл — Універсальний імпорт.