Elbuz підключається до вашого магазину на маркетплейсі, що працює на Mirakl (Leroy Merlin, Conforama, home24, Empik та інші), за адресою кабінету й ключем API: забирає офери й замовлення, повертає ціни, залишки й відвантаження.
Коли це знадобиться:
- Продаєте на кількох площадках Mirakl — кожна підключається своїм шаблоном, механіка однакова.
- Неприйняте замовлення площадка скасовує — Elbuz приймає нові замовлення сам під час кожного завантаження.
- Ціни й залишки рахуєте в Elbuz — вивантаження відправляє їх і виставляє нові офери за штрихкодом.
- Відвантажуєте зі свого складу — ваш статус передає на площадку трек-номер, відправку чи скасування.
З чого почати: скопіюйте адресу кабінету продавця й ключ API та вставте їх у шаблон завантаження типу «Mirakl».
Що вміє підключення Mirakl
- Одне підключення на всі площадки Mirakl — відрізняються лише адреса кабінету й ключ.
- Завантаження оферів — назва, бренд, артикул, , ціна, залишок і категорія.
- Замовлення з автоприйняттям — нові замовлення приймаються на площадці, адреса покупця дописується наступним прогоном.
- Ціни й залишки назад на площадку — одним файлом за запуск, результат — у журналі.
- Нові офери — на наявні картки площадки за штрихкодом.
- Відвантаження й скасування — ваш статус замовлення відправляє на площадку трек-номер, відправку або скасування.
Що потрібно від площадки
Підключення не потребує прив'язки застосунку: ви вставляєте адресу кабінету й ключ, які видає сама площадка. Полів у картці «Підключення» п'ять, обов'язкові перші два.
1
Адреса кабінету продавця площадки2
Обрати зі списку3
Ключ API магазину4
Shop ID5
Код стану товару6
Термін відвантаження- Адреса кабінету продавця площадки — адреса з рядка браузера кабінету.
- Обрати зі списку — підставляє адресу відомої площадки Mirakl.
- Ключ API магазину — з кабінету: ваше ім'я → My user settings → API Key.
- Shop ID — лише якщо ключ відкриває кілька магазинів.
- Код стану товару — на завантаження не впливає.
- Термін відвантаження — на завантаження не впливає.
| Поле у шаблоні | Що вписати |
|---|---|
| Адреса кабінету продавця площадки | Адреса, за якою ви входите в кабінет продавця. Обов'язкове |
| Ключ API магазину | Ключ із кабінету продавця. Обов'язкове |
| Shop ID (якщо в ключа кілька магазинів) | Номер магазину. Потрібен, лише якщо один ключ відкриває кілька магазинів |
| Код стану товару, за замовчуванням 11 (новий) | Стан оферів на площадці (код зі списку станів площадки, 11 — новий). Завантаження його не використовує, його бере вивантаження цієї площадки (вивантаження) |
| Термін відвантаження, днів (за замовчуванням 2) | За скільки днів ви відправляєте замовлення. Так само йде у вивантаження цієї площадки |
Адреса кабінету
Відкрийте кабінет продавця площадки й скопіюйте адресу з рядка браузера цілком — Elbuz сам відріже шлях після домену й допише https://, якщо його немає.
Для частини площадок адреса вже є в програмі: кнопка «Обрати зі списку» під полем показує Leroy Merlin, Conforama, BUT, Maisons du Monde, Vente-unique (усі — Франція), home24 (Німеччина), ePrice (Італія) й Empik Marketplace (Польща). Вибраний рядок підставляється в поле, і його можна правити руками.
Кнопка «Обрати зі списку» з'являється у вже збереженому шаблоні. Площадки, якої немає в списку (La Redoute, Decathlon, Castorama, Carrefour, MediaMarkt, PCComponentes тощо), вписуйте адресою з браузера.
Ключ API
Ключ створюється в кабінеті продавця: ваше ім'я → My user settings → API Key. Mirakl Connect для цього не потрібен: Elbuz працює з кабінетом площадки напряму. Новий ключ скасовує попередній — створивши його, замініть ключ і в шаблоні завантаження, і в шаблоні вивантаження.
Вставивши адресу й ключ, дочекайтеся напису «Усі зміни збережено» — перевірка бере збережені значення — і натисніть «Перевірити підключення». Elbuz запитає в площадки дані магазину й відповість «Підключення працює. Mirakl ‹адреса› — ‹назва магазину› #‹номер›». Якщо магазин на площадці не відкритий, після номера в дужках стоїть його стан. Неправильний ключ дає «Підключення не вдалося: HTTP 401: …».
«Активний» і «Замовлення» в новому шаблоні вже ввімкнені: за 5 хвилин після збереження ключа Elbuz почне забирати замовлення за 30 днів і приймати їх на площадці. Статуси майданчика Elbuz зводить до ваших сам, за назвою; що прийшло і як зведено, видно у вікні «Статуси замовлення» шаблону. Хочете спершу перевірити — зніміть «Замовлення».
Опис методів, якими користується Elbuz: Mirakl Developer Portal, розділ Seller API платформи Mirakl Marketplace.
Що переноситься в картку
Elbuz забирає список ваших оферів на площадці — сторінками по 100 — і кладе кожен у базовий каталог карткою товару.
| Дані офера Mirakl | Поле товару в Elbuz |
|---|---|
| назва товару | Назва |
| бренд | Виробник |
| ваш код офера (SKU магазину) | Артикул |
| EAN (або GTIN, UPC) товару | Штрихкод |
| ціна офера | Ціна |
| початкова ціна знижки, якщо вона більша за ціну | Стара ціна |
| кількість | Кількість |
| активний чи ні | Статус: активний офер — увімкнений товар |
| назва категорії | Категорія — знайдена за назвою або створена |
Опису, фото й характеристик офер не містить, тож у картку вони з Mirakl не приходять. Галочки «Фото», «Атрибути» й решта на шаблон Mirakl не впливають — діють лише «Товари» й «Замовлення». Офер без категорії ляже в службову категорію «Товари - mirakl», яка створюється вимкненою й не бере участі у вивантаженнях (службові категорії).
1
Товари2
Замовлення- Товари — завантажувати ваші офери в каталог.
- Замовлення — завантажувати й приймати замовлення.
Що перезапише повторний прогін
Свою картку повторне завантаження знаходить за кодом офера, який цей шаблон запам'ятав минулого разу, а картку без такої прив'язки — за назвою. Знайдену картку прогін змінює так:
| Що робить прогін | Поля |
|---|---|
| Перезаписує завжди | кількість, ознака «увімкнено» |
| Перезаписує, якщо площадка передала непорожнє значення | назва, виробник, артикул, штрихкод, ціна, стара ціна |
| Не чіпає | опис, фото, характеристики |
Щоб прогін не чіпав картку зовсім, увімкніть у ній перемикач «Не оновлювати» (секція «Захист під час імпорту»); щоб не чіпав лише ціни — «Фіксована ціна». Офер, якого в прогоні не було, лишається в каталозі з останніми ціною й залишком.
Як приходять і приймаються замовлення
Замовлення лягає документом «Замовлення покупця», непроведеним. Перше завантаження бере замовлення за останні 30 днів. Далі Elbuz бере змінені від дати в полі «Завантаження замовлень починаючи з дати (РРРР-ММ-ДД)» блоку «Розширене», із запасом у 12 годин. Наявне замовлення впізнається за номером і оновлюється, а не дублюється.
У документ потрапляють номер замовлення, дати створення й зміни, ім'я, телефон і пошта покупця, адреса доставки й платника, спосіб доставки й оплати, вартість доставки, валюта й позиції. Сума документа — разом із доставкою. Якщо в замовленні кілька рядків, скасовані й відхилені рядки в документ не потрапляють.
Автоматичне прийняття
Замовлення, яке чекає вашого підтвердження (статус WAITING_ACCEPTANCE), Elbuz приймає на площадці сам, усіма рядками, під час того самого завантаження. Наявність товару на складі при цьому не перевіряється. У документ таке замовлення лягає зі статусом площадки SHIPPING.
Не вдалося прийняти — у журналі червоний рядок «Mirakl: замовлення ‹номер› не прийнято автоматично — ‹причина›», а замовлення все одно завантажується в поточному статусі. Наступне завантаження спробує прийняти його знову: замовлення, що чекають прийняття, Elbuz перевіряє щоразу, незалежно від дати останнього завантаження. Якщо площадка відмовляє й далі, прийміть замовлення в кабінеті площадки.
Прийняте замовлення площадка вважає підтвердженим вами. Якщо товару немає, скасуйте замовлення — статусом, зіставленим із CANCELED (відвантаження й скасування), або в кабінеті площадки.
Чому в новому замовленні немає адреси
Частина площадок показує адресу й телефон покупця лише після прийняття замовлення. Тоді документ створюється без них, а наступне завантаження дописує порожні поля — і в документі, і в картці контрагента. Поля, які менеджер уже заповнив чи виправив, повторне завантаження не перезаписує.
Статуси замовлення
Статус площадки Elbuz зводить до вашого сам — за кодом або назвою, а не впізнаний лягає «Новим». Уточнити можна кнопкою «Статуси замовлення» в картці «Повʼязані налаштування» шаблону завантаження: у колонку «Код (назва) на сайті (API)» навпроти свого статусу впишіть код Mirakl.
1
Статуси замовлення2
Налаштування розкладу3
Види доставки- Статуси замовлення — зіставлення кодів Mirakl зі своїми статусами в обидва боки.
- Налаштування розкладу — розклад каталогу; замовлення Elbuz забирає сам кожні 5 хвилин.
- Види доставки — код перевізника площадки для трек-номера.
| Код Mirakl | Що означає |
|---|---|
WAITING_ACCEPTANCE | Чекає прийняття продавцем |
SHIPPING | Прийняте, чекає відправки |
SHIPPED | Відправлене |
RECEIVED | Покупець отримав |
CLOSED | Закрите |
CANCELED | Скасоване |
REFUSED | Відхилене |
1
Код (назва) на сайті (API)2
SHIPPED- Код (назва) на сайті (API) — сюди вписується код статусу Mirakl.
- SHIPPED навпроти «Відвантажено» — цей статус вивантаження передасть на площадку як відправку.
Те саме зіставлення працює і у зворотний бік: статус, навпроти якого стоїть SHIPPED чи CANCELED, вивантаження відправляє на площадку. Якщо в клітинці кілька кодів через кому, на площадку йде перший.
Ваш статус повторне завантаження змінює, лише коли статус на площадці змінився з минулого разу або статус документа після завантаження ще ніхто не міняв. Що відбувається з проведеним замовленням і резервом, описано в статті імпорт замовлень через API.
Як ціни й залишки повертаються на площадку
Зворотний напрямок — окремий шаблон вивантаження того самого типу. У ньому два поля: «Адреса кабінету площадки» й «Ключ API магазину». Shop ID, код стану й термін відвантаження вивантаження бере з шаблону завантаження цієї ж площадки (за адресою кабінету). Шаблону завантаження немає — без Shop ID, стан 11 (новий), відвантаження за 2 дні.
Продаєте на кількох площадках Mirakl — заведіть пару шаблонів на кожну. Прив'язки товарів у площадок окремі: товар, прив'язаний до однієї площадки, на іншу піде новим офером за штрихкодом.
1
Адреса кабінету площадки2
Ключ API магазину3
Мова описів- Адреса кабінету площадки — та сама, що в шаблоні завантаження.
- Ключ API магазину — той самий ключ.
- Мова описів — якою мовою йдуть назва й опис нових оферів; без перекладу — основна.
Оновлюються товари, прив'язані до оферів, тому спершу один раз завантажте каталог з площадки. Без галочки «Публікувати нові товари» товар без прив'язки пропускається без рядка в журналі. Що йде на площадку:
- Ціна — числом із шаблону вивантаження, з двома знаками після коми, не менше нуля. Валюту Elbuz не перераховує: ціни у відборі мають бути у валюті вашого магазину на площадці.
- Залишок — кількість товару, не менше нуля.
- Стан і термін відвантаження — з полів «Код стану товару» й «Термін відвантаження» шаблону завантаження цієї площадки.
- Які товари — визначає відбір шаблону вивантаження, як і для інших каналів.
Чому результат приходить не одразу
Mirakl приймає зміни не по одному оферу, а одним файлом на запуск і обробляє його кілька хвилин. Elbuz відправляє файл і близько хвилини чекає результату. Не дочекався — площадка обробить файл і без Elbuz, а в журналі лишиться рядок «…ще обробляється…».
| Що в журналі | Що це означає |
|---|---|
| «Mirakl: надіслано файл ‹номер›, рядків: N» | Файл пішов на площадку |
| «Mirakl: файл ‹номер› ще обробляється (‹стан›), результат — наступним запуском» | Хвилини не вистачило, площадка обробить файл і без Elbuz |
| «Mirakl: файл ‹номер› оброблено — успішно: N, помилок: M» | Результат файлу |
| «Mirakl: «назва» (код) відхилено: причина» | Площадка відбила рядок; причина — текстом площадки |
| «Mirakl: ціни й залишки — успішно: N, помилок: M» | Підсумок запуску |
Підсумок рахує лише рядки, результат яких уже прийшов. Нуль у ньому одразу після «ще обробляється» — не збій, а очікування. Товари, що лишаються у відборі, вивантаження відправляє кожним запуском, тож виправлений після відмови товар піде з наступним файлом.
Знімати офери Elbuz не вміє: товар, що випав із відбору, просто перестане оновлюватися. Щоб зупинити продаж, вивантажте нульовий залишок або зніміть офер у кабінеті площадки.
Нові офери за штрихкодом
З галочкою «Публікувати нові товари» Elbuz виставляє офер для товару, у якого на площадці офера ще немає. Офер чіпляється до наявної картки площадки за EAN, тому в товару має бути штрихкод щонайменше з 8 цифр. Нових карток Elbuz на Mirakl не створює: якщо картки з таким EAN немає, площадка відхилить рядок.
1
Товари2
Публікувати нові товари3
Замовлення- Товари — ціни й залишки прив'язаних оферів.
- Публікувати нові товари — офери на наявні картки площадки за EAN.
- Замовлення — відвантаження з трек-номером і скасування.
- Код офера — артикул товару. Без артикула або з артикулом довшим за 40 символів — ID товару в Elbuz.
- Немає штрихкоду — рядок «Mirakl: у товару «…» немає штрихкоду (EAN) — офер не створено», товар рахується помилкою.
- Поки площадка обробляє новий офер, товар у наступні файли не йде — у журналі «Mirakl: нові офери ще обробляються площадкою: N».
- Опубліковано — рядок «Mirakl: офер «назва» (код) опубліковано», товар прив'язано до офера.
- Відхилено — прив'язка знімається, і наступний запуск спробує виставити товар знову.
Відвантаження, трек-номер і скасування
Галочка «Замовлення» в шаблоні вивантаження передає на площадку дві події з ваших замовлень Mirakl:
| Ваш статус зіставлено з | Що відправляє Elbuz |
|---|---|
SHIPPED | Трек-номер (якщо заповнено) і підтвердження відправки |
CANCELED | Скасування замовлення |
Зіставлення береться з вікна «Статуси замовлення» шаблону завантаження — окремо у вивантаженні його налаштовувати не треба. Вивантаження працює з замовленнями того шаблону завантаження, у якого та сама адреса площадки.
Трек-номер — поле «Номер накладної (ТТН)» у картці «Доставка» документа (розгорніть «Більше полів»). Перевізник береться з кнопки «Види доставки» шаблону завантаження, якщо там зіставлено код перевізника площадки; інакше Elbuz передає назву служби доставки з документа. Поле номера порожнє — площадка отримає відправку без трек-номера.
Кожна подія відправляється один раз: після відправки Elbuz запам'ятовує новий статус площадки, і повторний запуск замовлення не чіпає. Не відправляються й замовлення, які на площадці вже відправлені, отримані, закриті, скасовані чи відхилені. У журналі — рядки «Mirakl: замовлення ‹номер› → SHIPPED» і підсумок «Mirakl: статусів замовлень передано: N, помилок: M».
Позначити відправленим можна замовлення в статусі SHIPPING, а скасувати — поки площадка це дозволяє. Інакше в журналі рядок «Mirakl: замовлення ‹номер› → SHIPPED не передано — HTTP 400: …» з поясненням площадки.
Оновлення за розкладом
Миттєвих сповіщень Mirakl не надсилає, тож замовлення Elbuz забирає й приймає сам кожні 5 хвилин, якщо в шаблоні відмічені «Замовлення» і заповнено ключ. Це робить спільне завдання «Замовлення з маркетплейсів» у вікні «Розклад завдань», там же міняється інтервал. Каталог у цьому проході не вантажиться, а замовлення, взяті ще й розкладом шаблону, не задвоюються.
Каталог оновлює розклад самого шаблону — кнопка «Налаштування розкладу» в картці «Повʼязані налаштування». Ставте його рідко, наприклад уночі: поки йде каталог, прохід замовлень пропускається до наступного. Файл вивантаження площадка обробляє кілька хвилин, тому запускати вивантаження частіше, ніж вона встигає його обробити, немає сенсу.
Площадка обмежує кількість запитів. Отримавши відмову через ліміт, Elbuz чекає й повторює запит до трьох разів. Не допомогло — у журналі «Mirakl: перевищено ліміт запитів площадки, повторіть пізніше — …». Це не помилка ключа: просто запустіть шаблон пізніше.
Пілюля «Активний» / «Вимкнений» знімає шаблон із розкладу й з автоматичного забору замовлень (вимкнути шаблон). Вивантаження — окремий шаблон зі своїм перемикачем.
Якщо прогін обірвався
- Каталог пишеться пачками по 500 оферів: що встигло лягти — оновлене, решта зі старими даними.
- Замовлення зберігаються одним заходом після читання всіх сторінок; дата для наступної порції зсувається тільки після збереження, тож повтор забере той самий проміжок. Уже прийняті замовлення повторно не приймаються.
- Вивантаження: відправлений файл площадка обробить і без Elbuz; наступний запуск відправить ціни й залишки заново.
Повтор безпечний. Загальні правила: якщо прогін обірвався.
Сценарії
Перенести каталог площадки в Elbuz
Що ввімкнути. Заповніть «Адреса кабінету продавця площадки» й «Ключ API магазину», після «Усі зміни збережено» натисніть «Перевірити підключення», у картці «Вибір даних для завантаження» залиште «Товари».
Що вийде. Кожен офер ляже карткою з назвою, брендом, артикулом, штрихкодом, ціною, залишком і категорією. Опис і фото додайте в Elbuz або з іншого джерела.
Приймати замовлення й відвантажувати з Elbuz
Що ввімкнути. У шаблоні завантаження — галочку «Замовлення», зіставлення кнопкою «Статуси замовлення» (щонайменше SHIPPING, SHIPPED, CANCELED); розклад для замовлень не потрібен — вони приходять самі кожні 5 хвилин. У шаблоні вивантаження з тією самою адресою — галочку «Замовлення».
Що вийде. Нові замовлення приймаються на площадці самі, адреса покупця з'являється наступним прогоном. Менеджер вписує трек-номер у «Номер накладної (ТТН)» і ставить статус, зіставлений із SHIPPED, — найближче вивантаження передасть відправку.
Площадка як канал для каталогу, який ви ведете в Elbuz
Що ввімкнути. Один раз запустіть завантаження з галочкою «Товари» — воно прив'яже картки до оферів. Далі лишіть у шаблоні завантаження тільки «Замовлення», інакше прогін каталогу перезаписуватиме ціну й залишок цифрами площадки. У шаблоні вивантаження — «Товари», за потреби «Публікувати нові товари».
Що вийде. Ціни й залишки прив'язаних товарів підуть на площадку файлом, а товари зі штрихкодом без офера виставляться на наявні картки площадки.
Що робити, коли площадка не віддає чи не приймає дані
| Що ви бачите | Чому так | Що зробити |
|---|---|---|
| «Підключення не вдалося: HTTP 401: …» | Ключ скопійовано не повністю, видалено в кабінеті або вставлено ключ іншої площадки | Створіть ключ заново й вставте разом з адресою тієї самої площадки (ключ API) |
| «Mirakl: вкажіть адресу кабінету площадки й ключ API магазину» | Порожня адреса або ключ | Заповніть обидва поля (що потрібно від площадки) |
| «Mirakl: перевищено ліміт запитів площадки, повторіть пізніше — …» | Ліміт звернень вичерпано й після трьох повторів | У проході замовлень — збільште інтервал завдання «Замовлення з маркетплейсів»; у каталозі — запускайте каталог рідше (розклад) |
| «Mirakl: замовлення ‹номер› не прийнято автоматично — …» | Площадка відмовила в прийнятті | Наступне завантаження спробує ще раз. Рядок повторюється — прийміть замовлення в кабінеті площадки (прийняття) |
| «Mirakl: у товару «…» немає штрихкоду (EAN) — офер не створено» | Новий офер чіпляється до картки площадки за EAN | Заповніть у товарі штрихкод від 8 цифр (нові офери) |
| «Mirakl: «…» (…) відхилено: …» | Площадка відбила рядок файлу: немає картки з таким EAN, неприйнятна ціна тощо | Виправте причину з рядка; вивантаження відправить товар знову |
| Ціну змінили, а на площадці стара | Файл ще обробляється або чекає наступного запуску | Знайдіть у журналі рядок «…ще обробляється…» і перевірте ціну в кабінеті площадки за кілька хвилин (результат файлу) |
| «Mirakl: замовлення ‹номер› → SHIPPED не передано — HTTP 400: …» | Замовлення на площадці не в тому стані: ще не прийняте або вже закрите | Перевірте стан замовлення в кабінеті площадки (відвантаження) |
| Статус змінили, а на площадку нічого не пішло | Статус не зіставлено з SHIPPED чи CANCELED, у вивантаженні немає галочки «Замовлення» або в нього інша адреса площадки |
Перевірте зіставлення в шаблоні завантаження й галочку в шаблоні вивантаження (відвантаження) |
Часті запитання
Моєї площадки немає в списку адрес — її можна підключити?
Так, якщо вона працює на Mirakl. Скопіюйте адресу кабінету продавця з рядка браузера (адреса кабінету).
Чи можна вимкнути автоматичне прийняття замовлень?
Ні, завантаження замовлень Mirakl завжди приймає ті, що чекають прийняття. Не хочете цього — зніміть галочку «Замовлення» й приймайте в кабінеті площадки (прийняття).
Чому в замовленні немає адреси покупця?
Площадка віддає її після прийняття. Наступне завантаження допише адресу й телефон (адреса).
Чому в товарах з Mirakl немає опису й фото?
Офер їх не містить, а Elbuz бере саме офери. Заповніть опис і фото в Elbuz або з іншого джерела (що переноситься).
Чи створює Elbuz нові картки товарів на площадці?
Ні, лише офери на наявних картках за штрихкодом. Нову картку створіть у кабінеті площадки, потім вивантаження прив'яже до неї офер (нові офери).
Ціни в каталозі в гривнях — що піде на площадку?
Те саме число, без перерахунку валюти. Ціни у відборі шаблону вивантаження мають бути у валюті магазину на площадці (вивантаження).
Де це і хто має доступ
- Меню
- Довідники → Операції → Завантаження даних → новий шаблон типу «Mirakl (Leroy Merlin, Conforama, home24…)»
- Інші входи
- Довідники → Операції → Вивантаження даних — шаблон того самого типу для цін, залишків і статусів
- Право доступу
- вікно «Завантаження» у «Правах груп»
- Підготувати
- адресу кабінету продавця площадки й ключ API магазину
Один шаблон — одна площадка. Продаєте і на Leroy Merlin, і на Conforama — заведіть два шаблони з різними адресами.
Суміжні теми
- Якщо потрібна загальна механіка завантаження — розклад, обрив, службові категорії: огляд завантаження даних.
- Якщо менеджер веде замовлення в Elbuz і важливо, що перезапише прогін: імпорт замовлень через API.
- Якщо продаєте ще й на Cdiscount чи Kaufland: підключення Cdiscount, підключення Kaufland.
