Імпорт каталогу і замовлень з Kaufland

Kaufland Marketplace — майданчик мережі Kaufland: Німеччина, Австрія, Чехія, Словаччина та Польща. Кожна країна там окремий майданчик (storefront) зі своїм каталогом і своїми замовленнями. Elbuz підключається до акаунта продавця через офіційний Seller API і працює в обидва боки: забирає ваші офери в базовий каталог, приймає замовлення й повертає на майданчик свіжі ціни та залишки.

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

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

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

1

Client key (Shop-Client-Key)

2

Secret key

3

Майданчик (storefront)

1. Client key (Shop-Client-Key) — публічна половина пари ключів доступу до Seller API.
2. Secret key — секретна половина пари ключів, зберігається прихованою.
3. Майданчик (storefront) — код країни маркетплейсу: de, at, cz, sk або pl.

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

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

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

Що приходить у каталог

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

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

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

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

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

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

1

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

2

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

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

Офер зник із майданчика

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

Інша річ — офер, який ще приходить, але змінив стан на майданчику. Тут розвилка проста:

• стан AVAILABLE — товар в Elbuz увімкнений;
• інший стан і залишок нуль — товар вимикається;
• інший стан, але залишок більший за нуль — товар лишається увімкненим.

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

Службова категорія «Товари - kaufland»

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

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

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

Замовлення

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

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

Що робить повторний прогін із замовленням

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

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

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

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

Замовлення, залишок і резерв

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

Далі так:

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

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

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

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

1

Статуси замовлення

2

Налаштування розкладу

1. Статуси замовлення — зіставлення кодів Kaufland зі своїми статусами.
2. Налаштування розкладу — коли й як часто запускати завантаження.

Оновлення цін і залишків на майданчику

Зворотний напрямок — окремий шаблон вивантаження того самого типу. Elbuz надсилає ціни й залишки пачками (до 150 позицій за раз), майданчик відповідає за кожною позицією окремо, і в журнал потрапляє, скільки рядків пройшло, а скільки відбито. Ключ, за яким оновлюється офер, Elbuz запам'ятовує ще на завантаженні каталогу — тому найнадійніший порядок: спершу один раз завантажити каталог з Kaufland, потім налаштовувати вивантаження.

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

ID групи доставки, ставку ПДВ і майданчик для вивантаження задають не в шаблоні завантаження, а в полі «Версія API (параметри майданчика)» шаблону вивантаження — одним рядком через риску: майданчик|ID групи доставки|ставка ПДВ, наприклад de|3457|standard_rate. Порожній майданчик означає de, порожня ставка ПДВ — standard_rate.

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

Якщо товар веде не тільки Kaufland

Ключ, за яким Kaufland знаходить вашу картку, — назва. Звідси два наслідки, і обидва неочевидні.

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

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

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

Розклад

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

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

Каталог і замовлення поводяться по-різному, і це варто знати до того, як зв'язок обірветься.

Каталог пишеться пачками по 500 оферів. Обрив ділить результат надвоє: усе, що встигло лягти пачками, у каталозі вже оновлене, решта лишилася зі старими даними. Якщо оферів у вас менше п'ятисот, пачка одна — і не запишеться нічого.

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

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

Якщо майданчик відмовив через ліміт звернень, Elbuz робить паузу й пробує ще — до трьох спроб, із паузою, що зростає з кожною. Не допомогло — прогін зупиняється, а в журналі лишається рядок «Kaufland: помилка API — HTTP 429: rate limit». Одного запиту Elbuz чекає до 120 секунд, на саме з'єднання — 30.

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

Скільки Elbuz бере за один прогін

Стелі на кількість оферів чи замовлень немає: скільки віддасть майданчик, стільки й приїде. Числа, які варто знати:

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

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

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

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

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

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

Якщо прогін зробив не те

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

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

Офер, опублікований помилково, Elbuz зняти не вміє — знімають його в кабінеті Kaufland. Прив'язка товару до цього офера в Elbuz при цьому лишається, і наступні прогони надсилатимуть для нього ціну й залишок далі; щоб перестали, приберіть товар із відбору шаблону вивантаження.

Що показує журнал вивантаження: рядок «Kaufland: ціни та залишки оновлено, оферів: N (помилок: M)» — скільки позицій майданчик прийняв і скільки відбив. У публікації свої рядки: Kaufland: опубліковано товар «…» (юніт …), Kaufland: «…» — немає штрихкоду EAN, публікація на Kaufland неможлива, Kaufland: не вказано ID групи доставки (id_shipping_group) — публікація неможлива. Заповніть його в шаблоні.

Сценарії

Перенести каталог Kaufland у Elbuz

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

Що ввімкнути: у шаблоні завантаження заповніть «Client key (Shop-Client-Key)», «Secret key» і «Майданчик», а в картці «Вибір даних для завантаження» поставте галочку «Товари». Потрібні зображення — ще й «Фото».

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

1

Товари

2

Фото

3

Замовлення

1. Товари — завантажувати офери Kaufland до каталогу.
2. Фото — завантажувати зображення карток.
3. Замовлення — отримувати замовлення з Kaufland.

Приймати замовлення й не втрачати роботу менеджера

Задача: замовлення Kaufland мають потрапляти в Elbuz, а менеджер — вести їх далі сам.

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

Що вийде: перший прогін забере всю історію, наступні — лише зміни від дати в полі «Завантаження замовлень починаючи з дати (РРРР-ММ-ДД)» у блоці «Розширене», з запасом у дванадцять годин. Кожне замовлення лягає документом «Замовлення покупця». Уже наявному документу ваш статус змінюється лише тоді, коли статус на Kaufland змінився і його зіставлено. Чого не буде: змін у проведеному документі; нових рядків у вже наявному документі; значень у полях «Сервіс доставки» і «Сервіс оплати» — Kaufland їх не передає.

Kaufland як канал для каталогу, який ви ведете в Elbuz

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

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

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

Навіщо зводити Kaufland в Elbuz

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

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

Де взяти client key і secret key?

Обидва ключі видає сам Kaufland у кабінеті продавця, у розділі налаштувань API. Це пара: публічний ключ ідентифікує магазин, секретний підписує запити. Вставте їх у поля «Client key» і «Secret key» у картці «Підключення» й натисніть «Перевірити підключення».

Що писати в полі «Майданчик»?

Дволітерний код країни, у якій ви продаєте: de, at, cz, sk або pl. Якщо поле порожнє, Elbuz працює з німецьким майданчиком. Для продажів у кількох країнах заведіть окремий шаблон на кожну — каталоги й замовлення там різні.

Чому в товарах немає характеристик?

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

Чому не публікується новий товар?

Найчастіші дві причини, і обидві видно в журналі. Перша — у товару немає штрихкоду EAN: офер на маркетплейсі чіпляється до чужої картки саме за ним. Друга — не вказано ID групи доставки в полі «Версія API (параметри майданчика)» шаблону вивантаження (формат de|3457|standard_rate); без нього публікація не стартує. Якщо ж картки товару в каталозі Kaufland узагалі немає, Elbuz надішле її дані на перевірку майданчика, і офер створиться пізніше.

Чому в замовленні три рядки по одній штуці замість одного на три?

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

Чи затре повторний прогін мої правки?

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

Замовлення скасували на Kaufland — що буде в Elbuz?

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

Товар зник із Kaufland — Elbuz його видалить?

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