Імпорт каталогу з eBay через API

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

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

Де це у програмі

У вікні імпорту створіть шаблон і оберіть тип «eBay». Це API-джерело: файл не потрібен. Один шаблон — одне підключення до одного акаунта продавця eBay.

1

User-токен eBay

2

Кнопка «Перевірити підключення»

1. User-токен eBay — вставте сюди токен, якщо не підключаєтесь через застосунок.
2. Кнопка «Перевірити підключення» перевіряє зв'язок з акаунтом eBay без завантаження даних.

Як відбувається підключення

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

Другий спосіб — ручний user-токен вашого застосунку eBay. Він знадобиться переважно для розробки чи тестового середовища. Якщо ви вводите токен вручну, Elbuz працює саме за ним; ручний токен завжди в пріоритеті над отриманим через прив'язку.

Як підключити крок за кроком

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

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

Що потрапляє в картку: маппінг полів

Кожен лот eBay розкладається в поля картки Elbuz так:

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

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

Кількість у картці одразу перетворюється на статус наявності: більше нуля — «В наявності», нуль — «Немає на складі». Окремо цей статус з eBay не приходить і руками в шаблоні не налаштовується.

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

Кожен наступний запуск не додає лоти вдруге, а шукає вже заведену картку — за назвою. Номер лота (ItemID) ключем пошуку тут не служить: він зберігається окремо, як прив'язка картки до лістингу, і потрібен уже для зворотного оновлення цін і залишків на eBay. Сам механізм пошуку однаковий для всіх API-підключень і розібраний в огляді імпорту каталогу через API.

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

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

Чого повторний прогін у вже заведеної картки не чіпає:

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

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

Лот завершився або його зняли з продажу

У каталог потрапляють лише активні лоти. Elbuz просить у eBay лоти, що завершуються від сьогодні і на 120 днів уперед, і з отриманого бере тільки ті, у яких стан лістингу — активний. Завершені й чернеткові позиції не приходять узагалі.

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

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

Варіації лота

Якщо лот має варіації (розмір, колір), кожна приходить окремою карткою з назвою на кшталт «Назва лота — M / Red», зі своєю ціною, залишком і артикулом. Назва самого лота записується всім його варіаціям у поле «Назва родини (варіації)» — за ним варіації одного лота видно в сітці разом. Головним товаром з опціями (секція «Варіанти (опції)» у картці) вони при цьому не стають: кожна варіація живе самостійною карткою. Специфіки варіації стають опціями, а звичайні характеристики лота — характеристиками.

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

Скільки триває прогін і чим він обмежений

Каталог приходить сторінками по сто лотів, і між сторінками Elbuz витримує паузу в одну секунду: денні ліміти звернень у eBay спільні на застосунок, і стриманий темп тут безпечніший за швидкий. Замовлення забираються сторінками по п'ятдесят із паузою у дві секунди — запит замовлень лімітований найжорсткіше.

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

На одну відповідь eBay Elbuz чекає до 120 секунд у сучасному інтерфейсі (замовлення, перевірка підключення) і до 180 секунд у старому, яким забирається каталог. Якщо eBay відповідає відмовою через ліміт — а в старому інтерфейсі ще й помилкою на своєму боці, — запит повторюється до трьох разів із паузою, що зростає — дві секунди, потім чотири, — і лише після цього прогін зупиняється з помилкою в журналі.

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

Каталог і замовлення

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

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

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

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

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

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

Службові категорії, які створює завантаження

Категорія лота приходить одним рядком виду Root:Sub:Leaf і розгортається в шлях «Root / Sub / Leaf». Спершу Elbuz шукає вашу категорію з таким самим повним шляхом, потім — категорію з такою самою назвою будь-де в дереві, перебираючи рівні шляху від останнього до кореня, і тільки якщо не знаходить нічого — створює гілку заново. Тому дублів на кшталт «Ноутбуки (2)» не з'являється, доки назви збігаються.

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

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

Якщо зняти «Активність» з картки

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

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

Навіщо зводити каталог eBay в Elbuz

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

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

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

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

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

Якщо прогін обірвався

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

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

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

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

Якщо завантажили не те

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

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

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

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

Перша типова причина, чому нічого не тягнеться, — доступ. Якщо ви підключаєтесь через прив'язку застосунку, переконайтесь, що вона виконана; якщо вводите user-токен вручну — що він дійсний і не протермінований. Кнопка «Перевірити підключення» одразу покаже, чи приймає eBay ваш доступ. Без доступу прогін навіть не звертається до майданчика: у журналі з'являється рядок «eBay: акаунт не підключено».

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

Що далі після завантаження

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

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

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

Назад на eBay Elbuz віддає тільки ціну й залишок — і робить це за прив'язкою, яку створило завантаження каталогу. Картку лістингу (опис, фото, категорію) вивантаження не чіпає: нею й далі володіє ваш магазин на eBay. Публікація нових лотів — окрема галочка «Публікувати нові товари» в шаблоні вивантаження; без неї оновлюються лише вже прив'язані позиції. Для публікації потрібні зіставлена категорія eBay і налаштовані в Seller Hub адреса складу й бізнес-політики (доставка, оплата, повернення) — інакше в журналі буде рядок про те, що публікація неможлива, а самі товари пропустяться.

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

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

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

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

Де взяти токен eBay?

За звичайного підключення токен вводити не треба — доступ видається через прив'язку застосунку кодом і оновлюється автоматично. Ручний user-токен потрібен переважно для роботи з власним застосунком чи тестовим середовищем.

Що робити з денними лімітами eBay?

eBay обмежує кількість звернень за добу. Якщо оновлення впираються в ліміт, зменшіть частоту розкладу. Elbuz і так витримує паузи між сторінками; для великого каталогу досить оновлюватися раз на добу.

Чи зберігаються категорії лотів?

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

Повторний імпорт задвоїть лоти?

Ні, поки назви лотів не міняються: повторний прогін шукає вже заведену картку за назвою і перезаписує її, а не створює копію. А от перейменований на eBay лот стара картка вже не «впізнає» — тоді в каталозі з'явиться нова, а стара лишиться зі старими даними.

Що буде з карткою, коли лот завершиться?

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

Можна тягнути з eBay тільки замовлення?

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