Імпорт каталогу через API маркетплейсів і систем

Файлові способи завантаження вимагають файлу: щось вивантажити, кудись передати, потім прочитати. Якщо ж ви вже продаєте на маркетплейсі або ведете облік у зовнішній системі, каталог можна тягнути напряму через API — за ключами доступу, без жодних файлів. Це найшвидший спосіб, коли джерело вміє віддавати дані через свій інтерфейс.

Ця стаття — груповий огляд усіх API-підключень для каталогу. Загальний порядок у них однаковий, тож тут описано спільну частину, а для великих майданчиків є окремі детальні статті з їхніми особливостями. Про завантаження в цілому дивіться огляд завантаження даних.

Коли підходить

API беруть тоді, коли інший бік — це система з власним програмним інтерфейсом: маркетплейс (Rozetka, Amazon, eBay і подібні), інтернет-магазин на популярній платформі (Shopify, WooCommerce, Wix) або облікова система («Мій склад», CRM SalesDrive). Ви вже там працюєте, дані там є — лишається під'єднатися й забрати їх напряму, без вивантаження таблиць.

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

Як це працює загалом

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

Що потрапляє в каталог з API

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

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

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

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

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

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

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

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

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

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

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

Де взяти ключі доступу

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

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

Каталог і замовлення — оберіть, що тягнути

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

1

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

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

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

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

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

Які майданчики й системи підтримуються

Нижче — інтеграції, з яких можна тягнути каталог. «Каталог + замовлення» означає, що те саме підключення вміє забирати ще й замовлення, якщо ввімкнути відповідний перемикач.

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

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

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

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

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

Як побачити, що прогін відпрацював

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

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

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

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

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

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

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

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

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

Стелі на кількість позицій за один прогін немає: скільки віддасть майданчик, стільки й приїде. Дані забираються сторінками по 25–1000 позицій залежно від майданчика, у частини підключень — із паузою між сторінками, щоб не впертися в його ліміти. Скільки триває саме ваш каталог, вигадувати не треба — це видно в колонці «Витрачено часу» списку шаблонів і у вікні «Історія запусків», де є «Середня тривалість» і «Найдовший».

Куди завантажений каталог їде далі

У базовому каталозі товар з'являється одразу, ще під час прогону — пачка за пачкою. Наприкінці програма сама доводить набір до робочого стану: перераховує поля за вашими формулами, застосовує правила націнки до щойно доданих товарів, оновлює їхні сортувальні та пошукові дані. Окремо це запускати не треба.

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

Кілька майданчиків одразу

Один шаблон — це одне підключення до одного акаунта. Якщо ви продаєте на кількох майданчиках або маєте кілька акаунтів, під кожен заводять окремий шаблон зі своїми ключами. Вони не заважають один одному й можуть мати різний розклад. Так в один базовий каталог Elbuz зводяться товари з різних джерел, а ви керуєте ними з одного місця — замість того щоб перемикатися між кабінетами майданчиків. Це, власне, і є сенс усієї затії: зібрати розкидані по маркетплейсах товари в єдиний каталог і далі працювати з ним централізовано.

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

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

Службові категорії та виробники

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

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

Розкладати картки з такої категорії можна вільно: місце товару в дереві повторний прогін не змінює. А от видаляти саму категорію безглуздо — наступний прогін створить її знову, щойно в джерелі знайдуться товари без категорії. Уже розкладені товари назад у неї при цьому не повернуться: вона просто з'явиться порожньою.

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

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

Стан шаблона перемикає пілюля «Активний» / «Вимкнений» у шапці його картки. Вимкнення робить рівно одне: знімає шаблон з розкладу — планувальник бере тільки активні. Усе інше лишається на місці: ключі, галочки, налаштований розклад, завантажені товари, категорії й прив'язки карток до майданчика. Увімкнули назад — наступного разу за розкладом шаблон відпрацює так, ніби нічого не було.

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

Видалення — операція іншого порядку. Шаблон зникає зі списку назавжди: повернути його з інтерфейсу не можна, ключі доведеться вводити наново. Разом із ним видаляються завдання розкладу, заведені під цей шаблон. А от усе, що він встиг завантажити, лишається в базі: товари, категорії, виробники, прив'язки карток до майданчика й позначка джерела в них. Системні шаблони видалити не можна взагалі.

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

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

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

Часті труднощі

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

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

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

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

Де взяти ключі доступу?

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

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

Так, якщо інтеграція це вміє. У шаблоні є окремі перемикачі: завантажувати товари, завантажувати замовлення. Ви обираєте, що саме потрібно.

Чи затре повторне оновлення мої правки в картці?

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

Підключив, а нічого не завантажується — чому?

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

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

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

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

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

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

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