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

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

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

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

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

1

API-логін eMAG

2

API-пароль eMAG

3

Майданчик (ro/bg/hu)

1. API-логін eMAG — логін з кабінету продавця eMAG.
2. API-пароль eMAG — пароль з кабінету продавця eMAG.
3. Майданчик — вибір ro (Румунія), bg (Болгарія) або hu (Угорщина).

Що потрібно для підключення

eMAG не використовує токени чи «застосунки розробника» — підключення відбувається за трьома значеннями:

• API-логін — окремий логін для API з кабінету продавця eMAG (це не той самий логін, яким ви заходите у веб-кабінет; API-доступ видається окремо).
• API-пароль — пароль до цього API-доступу.
• Площадка (країна) — ro (Румунія), bg (Болгарія) або hu (Угорщина). За цим значенням Elbuz обирає правильну доменну зону API eMAG.

Білий список IP — обов'язково

Головна особливість eMAG, через яку найчастіше «не працює»: маркетплейс приймає API-виклики лише з дозволених IP-адрес. Поки IP-адресу Elbuz не внесено до білого списку у вашому кабінеті eMAG, навіть правильні логін і пароль не спрацюють — eMAG просто відхилить звернення. Тому перший крок підключення — додати IP Elbuz у білий список у налаштуваннях доступу кабінету продавця. Потрібну IP-адресу підкаже підтримка Elbuz.

Вимога GPSR

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

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

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

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

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

Ще дві особливості. Характеристики eMAG передає не назвами, а кодами: щоб у картці стояли зрозумілі підписи, Elbuz окремо читає довідник характеристик тієї категорії, до якої належить оферта. Якщо назву для якогось коду отримати не вдалося, характеристика все одно збережеться — але з технічною підписом виду «#123»; це підказка, що довідник категорії не відповів, а не втрата даних. Варіанти в eMAG об'єднуються рідним для майданчика поняттям «родина» (family): позиції однієї родини приходять у Elbuz зв'язаними в сім'ю.

Окремо варто знати про PNK (part_number_key) — це код картки товару в каталозі eMAG, спільної для всіх продавців. Elbuz зберігає його разом із товаром: саме за PNK ваша оферта прив'язана до конкретної картки маркетплейсу, і саме він потрібен, коли ви публікуєте товар на вже наявну картку eMAG замість створення нової.

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

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

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

Для знайденої картки прогін переписує значеннями eMAG: Назва, Опис повний, Виробник, Артикул, Штрихкод EAN, Ціна, Стара ціна, Кількість, Активність, Назва родини і Теги (теги eMAG не передає, тому поле просто очищується). Правки, зроблені руками в цих полях, наступного завантаження не переживуть.

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

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

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

Якщо офер зник з eMAG або змінив стан

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

Інша річ, коли офер на місці, але змінився. Тут прогін реагує:

• eMAG віддав офер вимкненим — у картці знімається Активність;
• залишок став нулем — у картку лягає 0 і статус наявності «Немає на складі»; залишок більший за нуль повертає «В наявності».

Зняти «Активність» чи видалити картку

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

На самому eMAG від цього не станеться нічого: офер там як був у продажу, так і лишиться, просто Elbuz більше не надсилатиме йому нову ціну й залишок. Знімають товар з вітрини маркетплейсу в кабінеті продавця, а не галочкою в Elbuz.

Врахуйте й те, що наступне завантаження поверне «Активність» такою, якою її бачить eMAG: якщо офер там активний, галочка з'явиться знову. Утримати картку вимкненою можна тим самим прапором «Не оновлювати».

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

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

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

Що стає із замовленням eMAG

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

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

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

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

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

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

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

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

Кілька країн eMAG в один каталог

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

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

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

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

Коли підключення налаштовано й перевірено, поставте шаблон на розклад кнопкою налаштування завдання прямо у формі. Elbuz сам звертатиметься до eMAG за свіжими даними: ціни й залишки оновлюватимуться, нові товари додаватимуться. Кожен запуск лишає слід у журналі: рядок на кожну прочитану сторінку каталогу («eMAG: сторінка каталогу 3, отримано оферів: 300»), підсумковий рядок із загальною кількістю оферів і червоні рядки на помилки API. Перші кілька разів варто туди зазирати — саме за цими числами видно, що прогін справді щось привіз.

Скільки це триває і чи є стеля

Стелі за кількістю оферів немає. Elbuz читає каталог сторінками по 100 оферів і зупиняється тоді, коли eMAG поверне неповну сторінку. Накопичене записується в каталог порціями по 500 оферів, а не в самому кінці.

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

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

На один запит відводиться 30 секунд на з'єднання і 120 секунд на відповідь. Якщо eMAG відповідає «забагато запитів», Elbuz чекає й повторює — до трьох спроб із наростаючою паузою.

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

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

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

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

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

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

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

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

Друга — плутанина з логіном. API-доступ eMAG це окремі логін і пароль, не ті, якими ви заходите у веб-кабінет. Якщо підставити «звичайні» дані входу, авторизація не пройде. І третє — країна: якщо обрати не ту площадку (ro замість bg тощо), Elbuz звертатиметься не до тієї доменної зони, і каталог не приїде.

Якщо завантажили не з тією країною

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

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

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

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

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

Категорії та виробники, які завів імпорт

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

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

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

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

Чого завантаження eMAG не робить

• Не знімає з продажу те, що зникло з eMAG. Картка лишається активною з останньою відомою ціною й залишком — див. розділ про зниклі офери.
• Не оновлює фото й характеристики вже завантажених карток. Вони беруться тільки в момент створення картки.
• Не перераховує валюту. Ціна лягає числом у валюті майданчика.
• Не заповнює ціну собівартості. Тому правила націнок базового каталогу, які рахують від неї, для товарів eMAG не спрацьовують.
• Нічого не надсилає на eMAG. Зворотний бік — окремий шаблон вивантаження, про нього нижче.

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

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

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

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

Коли завантажене поїде назад на eMAG

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

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

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

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

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

Логін і пароль правильні, а eMAG не пускає — чому?

Майже завжди IP-адресу Elbuz не внесено до білого списку в кабінеті eMAG. Маркетплейс приймає API-виклики лише з дозволених адрес. Додайте IP Elbuz у білий список — адресу підкаже підтримка.

Який логін вводити — від веб-кабінету?

Ні. У eMAG API-доступ це окремі логін і пароль, які видаються в кабінеті продавця для інтеграцій. Дані входу у веб-кабінет тут не підходять.

Що вписати у поле країни?

Код площадки: ro (Румунія), bg (Болгарія) або hu (Угорщина). За ним Elbuz обирає правильну доменну зону API. Продаєте в кількох країнах — заведіть окремий шаблон під кожну.

Що таке GPSR і чи потрібен він для імпорту?

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

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

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

Я виправив ціну в Elbuz — наступне завантаження її поверне?

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

Товар зник з eMAG. Він вимкнеться в Elbuz сам?

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

Скільки оферів можна завантажити за раз?

Обмеження на кількість немає: Elbuz читає каталог сторінками по 100 оферів, поки eMAG не поверне неповну сторінку, і записує їх у каталог порціями по 500. Тривалість задає обмеження майданчика — не частіше одного запиту на 3 секунди. Скільки зайняв ваш прогін, показує колонка «Останнє завантаження» у списку шаблонів.