Хорошоп — українська платформа для інтернет-магазинів. Якщо ваш магазин працює на ній, каталог живе на сайті: там картки, ціни, описи, SEO-тексти. Elbuz підключається до сайту через API Хорошопу й забирає весь цей каталог до себе — розділи, товари, ціни, залишки, описи обома мовами, — а разом із ним і замовлення покупців. Назад Elbuz вміє оновлювати товари на сайті: ціни, наявність, тексти — набір полів ви обираєте самі.
Загальний порядок для всіх API-джерел описано в огляді імпорту каталогу через API. Тут — те, що стосується Хорошопу.
Де це у програмі
У вікні завантаження створіть шаблон і оберіть тип «API — CMS Хорошоп». Файл не потрібен: підключення відбувається за адресою сайту й парою логін-пароль.
1
Посилання API — адреса API сайту2
Логін користувача API3
Пароль- Посилання API — адреса API сайту, з якого відбувається завантаження.
- Логін користувача API для підключення до сайту.
- Пароль користувача API для підключення до сайту.
Що потрібно для підключення
| Поле у шаблоні | Що вписати |
|---|---|
| Посилання (URL) | Адреса API вашого сайту — домен магазину з /api/ на кінці |
| Логін | Логін користувача API, створеного в адмінпанелі Хорошопу |
| Пароль | Його пароль |
Логін і пароль створюються на боці сайту: адмінпанель Хорошопу → «Налаштування» → «Адміни». Заведіть там окремого користувача для інтеграції — не використовуйте свій особистий обліковий запис адміністратора: окремий доступ зручніше відкликати й простіше змінити, якщо його доведеться перевипустити.
Хорошоп віддає назви й описи тими мовами, які увімкнені на сайті. Щоб в Elbuz приїхала українська версія, українська мова має бути в довіднику мов вашої копії — інакше тексти прийдуть лише однією мовою. Перевірте це до першого завантаження: доливати переклади потім довше, ніж увімкнути мову заздалегідь.
Опис інтеграції на боці платформи: API Хорошоп. Там же описано, як увімкнути доступ і які функції підтримує ваша редакція.
Хорошоп видає тимчасовий ключ доступу з дуже коротким строком життя — близько десяти хвилин. Elbuz отримує його автоматично перед кожною операцією, тож зберігати чи продовжувати нічого не потрібно. Знати про це корисно з іншої причини: якщо в журналі з'явилася помилка авторизації, справа майже завжди в логіні чи паролі, а не в «протухлому токені».
Як підключити крок за кроком
Створіть шаблон типу «API — CMS Хорошоп», впишіть адресу API, логін і пароль користувача інтеграції. Позначте, що завантажувати, і чи тягнути фотографії — при першому завантаженні фото має сенс увімкнути, далі його можна вимкнути, щоб запуски йшли швидше. Збережіть шаблон і запустіть завантаження вручну, не чекаючи розкладу.
Перший запуск варто перевірити очима: подивіться, чи зібралося дерево розділів так само, як на сайті, і звірте кілька товарів — ціну, залишок, описи обома мовами. Великий каталог їде помітно довше за маркетплейс: сторінки по 500 товарів, кожна з описами й SEO-полями. У журналі операції видно, на якій сторінці зараз робота, тож «завис чи йде» визначається одним поглядом.
Спершу розділи, потім товари
Завантаження йде у два кроки, і порядок тут не випадковий. Спочатку Elbuz забирає розділи каталогу сайту разом з їхньою вкладеністю й назвами російською та українською, вибудовує з них дерево категорій у себе — і лише потім вантажить товари, яким уже є куди лягти. Розділи, що вже є в Elbuz, оновлюються, нові додаються; дерево перебудовується повністю, тож ієрархія сайту зберігається.
Що приходить у товарі
Товари забираються сторінками по 500 штук, доки не закінчаться. Набір полів у Хорошопу помітно багатший, ніж у більшості маркетплейсів:
| Дані Хорошопу | Поле товару в Elbuz |
|---|---|
| артикул | Артикул — головний ключ зіставлення |
| артикул батьківського товару | Зв'язок модифікацій у сімʼю |
| розділ каталогу | Категорія |
| назва, назва модифікації | Назва (російською та українською) |
| назва для Rozetka | Окреме поле назви для майданчика |
| бренд | Виробник |
| артикул виробника (MPN), GTIN | MPN і штрихкод |
| ціна і стара ціна, валюта | Ціна, стара ціна |
| наявність, кількість | Статус наявності й залишок |
| короткий опис і опис | Короткий опис, опис (двома мовами) |
| SEO-заголовок, ключові слова, опис, H1 | SEO-поля (двома мовами) |
| ЧПУ-адреса й посилання на товар | Адреса товару на сайті |
| фотографії | Фотографії (якщо ввімкнено галочку) |
У Хорошопу роль ідентифікатора відіграє артикул: за ним товар упізнається при повторних завантаженнях, за ним же модифікації зчіплюються з головним товаром (у дочірньої картки артикул батька вказано окремим полем). Практичний наслідок: артикули на сайті мають бути унікальними й не мінятися. Якщо артикул товару змінили на сайті, для Elbuz це буде новий товар, а старий залишиться сиротою.
Характеристики товару з Хорошопу не завантажуються. Причина в самому API: він віддає значення характеристик, але не віддає їхні назви в людському вигляді, тож зібрати з цього коректну таблицю атрибутів неможливо. Усе інше — описи, ціни, наявність, SEO, фото — приходить повністю. Якщо характеристики вам потрібні в Elbuz, заповніть їх у себе або підтягніть з іншого джерела: прайсу постачальника, фіду виробника.
Замовлення з сайту
Те саме підключення вміє забирати замовлення — вмикається галочкою «Замовлення» у картці «Що завантажувати». Каталог при цьому вантажиться як раніше, замовлення додаються окремим кроком наприкінці.
1
Галочка «Замовлення»- Галочка «Замовлення» вмикає завантаження заказів із сайту.
| Дані Хорошопу | Поле документа в Elbuz |
|---|---|
| номер замовлення | Номер документа (за ним замовлення впізнається повторно) |
| дата оформлення | Дата замовлення |
| ім'я отримувача | Ім'я та прізвище (рядок ділиться на дві частини) |
| пошта й телефон | E-mail, телефон |
| ідентифікатор покупця на сайті | Прив'язка контрагента до джерела |
| місто й адреса доставки | Адреса доставки |
| спосіб доставки, вартість доставки | Вид доставки, ціна доставки |
| спосіб оплати | Вид оплати |
| ознака оплати | Статус оплати «Оплачено» |
| статус замовлення | Статус документа (через зіставлення) |
| коментар покупця | Опис замовлення |
| сума й валюта | Сума документа, валюта |
| позиції: артикул, назва, ціна, кількість, сума | Рядки документа |
Статус замовлення, вид оплати й службу доставки Хорошоп віддає своїми кодами. Зіставте їх зі своїми довідниками кнопками в картці «Пов'язані налаштування» — це окремі таблиці для статусів замовлення, статусів доставки, статусів оплати й видів оплат. Єдине, що Elbuz визначає сам, — ознака оплати: оплачене замовлення одразу отримує статус оплати «Оплачено».
У рядку замовлення Хорошоп передає артикул товару — той самий, за яким приїхав каталог. Тому позиції зіставляються з наявними картками автоматично; якщо ви вантажите і каталог, і замовлення одним шаблоном, збіг повний за визначенням.
Додатково завантаження каталогу запам'ятовує зв'язок кожної картки з сайтом — так само, як це роблять підключення до маркетплейсів. Завдяки цьому позиція замовлення знаходить свій товар найкоротшим шляхом, а не через перебір за назвою.
Уже завантажене замовлення при наступних запусках не перезаписується: дублікат не створюється, але й зміни з сайту в нього не приїжджають. Далі документ веде ваш менеджер в Elbuz, і чергове завантаження не затирає його роботу.
Фільтра за датою в API Хорошопу немає, тож вікно Elbuz відрізає в себе: при регулярних запусках беруться замовлення від минулого завантаження з запасом у дванадцять годин. Перший запуск забирає всю доступну історію, тому він найдовший — далі кожен наступний швидкий.
Оновлення товарів на сайті
Зворотний напрямок — окремий шаблон вивантаження типу «CMS Хорошоп API». Він влаштований гнучкіше за більшість інших: ви самі складаєте список полів, які їдуть на сайт. Відкривається він кнопкою «Налаштування вивантаження полів» у формі шаблону: навпроти кожного поля стоїть прапорець «Оновлювати». Хочете оновлювати лише ціну й наявність — лишіть два прапорці. Потрібно віддавати ще й описи, назви модифікацій, SEO-заголовки — позначте і їх.
Кілька правил, за якими це працює:
- Артикул їде завжди. Це ключ, за яким сайт знаходить товар, тож Elbuz вмикає це поле сам, навіть якщо ви його не позначили.
- Мовні поля тягнуть за собою головне. Якщо ви ввімкнули опис українською, автоматично вмикається й саме поле опису — інакше сайт не зрозуміє, куди класти текст.
- Нові товари теж можна створювати — тоді на сайт обов'язково мають їхати назва й розділ, інакше картку нема з чого зібрати.
Часті труднощі
Перша — помилка авторизації. Оскільки доступ Elbuz отримує сам перед кожною операцією, справа майже завжди в трьох речах: неточна адреса API (забули /api/ на кінці), неправильний логін або вимкнений доступ до API на боці сайту. Перевіряйте саме в такому порядку.
Друга — товари приїхали, а розділи ні. Це означає, що завантаження розділів не відпрацювало: товари в такому разі лягають у категорію джерела. Повторіть запуск, а якщо картина повториться — подивіться журнал: там буде відповідь майданчика.
Третя — дублікати після зміни артикулів. Артикул тут ключ, тож будь-яка його правка на сайті створює в Elbuz новий товар, а старий лишається. Якщо артикули таки довелося змінити, старі картки прибирають руками.
Навіщо зводити Хорошоп в Elbuz
Поки магазин один, адмінпанелі сайту вистачає. Складнощі починаються, коли з'являються постачальники з прайсами, маркетплейси й офлайн-точка: ціну треба перерахувати за правилом, наявність звести з кількох складів, той самий товар віддати на Rozetka, Prom і у власний магазин у різних форматах. Робити це в адмінці сайту незручно — вона про вітрину, а не про облік. Elbuz стає шаром нижче: тут збираються прайси, рахуються націнки, ведеться склад і замовлення, а Хорошоп отримує вже готові ціни й наявність і лишається тим, чим має бути, — вашою вітриною.
Часті питання
Що вписувати в поле посилання?
Адресу API вашого сайту: домен магазину з /api/ на кінці. Логін і пароль — від користувача, створеного в адмінпанелі Хорошопу в розділі «Налаштування» → «Адміни»; окремий користувач для інтеграції зручніший за особистий обліковий запис адміністратора.
Чому не завантажилися характеристики товарів?
API Хорошопу віддає значення характеристик, але не їхні назви в людському вигляді, тому коректно зібрати таблицю атрибутів неможливо — це обмеження джерела. Описи, ціни, наявність, SEO-поля й фотографії приходять повністю.
Як увімкнути завантаження замовлень із сайту?
Поставте галочку «Замовлення» у картці «Що завантажувати» вашого шаблону. Каталог продовжить вантажитися як раніше, а замовлення додадуться окремим кроком. Після першого запуску зіставте статуси й види оплат кнопками в картці «Пов'язані налаштування».
Що буде, якщо змінити артикул товару на сайті?
Товар приїде в Elbuz як новий, а попередня картка залишиться без пари: артикул — головний ключ зіставлення в Хорошопі, за ним же модифікації зчіплюються з головним товаром. Тому артикули варто тримати унікальними й незмінними.
Чи можна оновлювати на сайті тільки ціни, не чіпаючи описи?
Так, саме для цього в шаблоні вивантаження є список полів: лишіть увімкненими ціну й наявність, решту вимкніть. Артикул Elbuz додасть сам — без нього сайт не знайде товар.