Вивантаження каталогу на Хорошоп (Horoshop)

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

Меню

Довідники → Операції → Вивантаження даних

Створити

додати шаблон → тип CMS Хорошоп API

Налаштувати

картка шаблону: «Підключення», галочки складу вивантаження, кнопка «Налаштування вивантаження полів»

Шаблон вивантаження й шаблон завантаження — це два різні записи з різними адресами API в налаштуваннях, навіть коли йдеться про один і той самий сайт. Створення й редагування шаблону, розклад, історія запусків і журнал описані в загальній статті про вивантаження товарів; тут — усе, що специфічне для Хорошопа.

1

Посилання на API

2

Логін

3

Стан шаблону

1. У полі «Посилання на API» — адреса, за якою Elbuz звертається до сайту: https://demo-shop.horoshop.ua/api/.
2. У полі «Логін» — користувач API, від імені якого виконується вивантаження.
3. Пилюля в шапці показує стан шаблону; у демо-шаблоні вона показує «Активний».

Підключення

Файл для цього обміну не потрібен: підключення тримається на адресі сайту й парі логін-пароль.

Користувач API заводиться на боці сайту: адмінпанель Хорошопу → «Налаштування» → «Адміни». Якщо ви вже налаштували завантаження каталогу з цього сайту, беріть ті самі доступи — окремий користувач для вивантаження не потрібен.

Що вивантажується

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

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

Що з каталогу Elbuz потрапляє у вигрузку:

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

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

Список полів: що саме їде на сайт

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

У новому шаблоні увімкнені три поля: «Ціна», «Статус наявності» і «Категорія». Решта вимкнена й чекає на вас.

Назви товару, опису й SEO-полів заведені парами — окремо російською («Наименование RU», «Описание полное RU») і окремо українською. Одна пара — одне поле на сайті, тому вмикати треба ті мови, які реально є в каталозі: порожня українська версія поїде на сайт порожньою.

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

1

Оновлювати

2

Поле API article

3

Формула артикула

1. Флажок «Оновлювати» визначає, чи поїде це поле на сайт під час вивантаження.
2. У колонці «Поле API» — ключ article, за яким сайт шукає товар.
3. У колонці «Формула» — джерело артикула: {Товар БК: Артикул (внутрішній)}.

Перевірте джерело артикула

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

У нового шаблону це поле бере значення з однойменного поля картки — «Артикул виробника». Для каталогу, який ви колись завантажили із цього сайту, це неправильне джерело: сайт віддає свій артикул окремим полем, і в Elbuz він лежить у колонці «ID товару (рядок UUID)», а «Артикул виробника» приходить із сайту як MPN і в таких карток частіше за все порожній.

Тому джерело міняють формулою — у рядку «Артикул виробника» в колонці «Формула» вписують назву потрібної колонки:

{Товар БК: ID товару (рядок UUID)}

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

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

Колонка «Формула»

Замість готового поля у вигрузку можна покласти вираз. У колонці «Формула» працює будь-яке поле товару за іменем колонки, макроси виду {Товар БК: Назва поля} і звичайні функції на кшталт REPLACE чи CONCAT_WS. Найчастіше формулу беруть саме для категорії — про це наступний розділ.

Головна особливість: шлях до розділу

Коли каталог приїхав із сайту через завантаження, у Elbuz разом із товарними розділами з'явилися й службові — «Головна», «Каталог товарів», «Контакти», «Про нас». Вони справді є розділами сайту, і API віддає їх нарівні з рештою. Через це шлях до категорії товару в Elbuz може виглядати так:

Головна / Каталог товарів / Побутова техніка / Пральні машини

А сайт у полі категорії чекає шлях від кореня каталогу:

Побутова техніка / Пральні машини

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

Що програма робить сама

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

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

TRIM(REPLACE({Товар БК: Категорія}, "Мій сайт / Каталог товарів /", ""))

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

1

Поле API parent

2

Формула категорії

1. У колонці «Поле API» — ключ parent: шлях до розділу на сайті.
2. Формула TRIM(REPLACE({Товар БК: Категорія}, "Головна / Каталог товарів /", "")) зрізає з категорії зайві рівні.

Надійніший спосіб: віддавати id розділу

Шлях — не єдиний варіант. API Хорошопа приймає замість нього id розділу, і сама документація Хорошопа радить цей спосіб як основний. У списку полів він називається «Категория ID UUID», і для розділів, що приїхали із сайту, там стоїть саме id розділу на сайті.

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

Наявність їде словом

Поле «Статус наявності» передає сайту не число, а слово. Elbuz бере назву статусу з картки товару й замінює її коротким словом, яке розуміє сайт, якщо назва типова. Типовими вважаються російські В наличии, Нет в наличии, Ожидание 2-3 дня, Предзаказ, Под заказ та українські В наявності, Немає в наявності, Немає на складі, Під замовлення, Під замовлення 2-3 дні, Очікування 2-3 дні.

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

Кількість залишку цим полем не передається — сайт отримує саме слово про наявність.

Характеристики

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

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

Пробне вивантаження

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

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

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

1

Адреса запиту

2

Значення товару

1. Рядок POST https://demo-shop.horoshop.ua/api/catalog/import/ показує, куди саме пішов би запит.
2. У масиві products — значення, які поїхали б у товар: article, price, presence, parent.

Прогін: пачки, журнал, помилки

Товари їдуть на сайт пачками по тисячу в одному запиті; після кожної тисячі в журналі з'являється рядок «Вивантажено рядки 1000 із …». У списку шаблонів і в історії запусків видно, коли прогін був і чим закінчився.

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

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

Повторне вивантаження

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

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

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

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

Чи треба щось віддавати Хорошопу — файл чи посилання?

Ні. Обмін іде напряму через API сайту: Elbuz сам звертається до нього в момент прогону. Нічого викладати у сховище й передавати майданчику не потрібно.

Чи створить Elbuz розділи на сайті?

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

Як оновити тільки ціни й наявність, не чіпаючи описи?

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

Чи можна відкотити помилкове вивантаження?

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

Чи заведе Elbuz товар, якого на сайті немає?

Так, але картку створює сайт — за артикулом. Щоб нова картка склалася, у списку полів мають бути увімкнені назва й розділ. Без розділу сайт не знатиме, куди покласти товар.

Звідки Elbuz бере артикул, за яким сайт шукає товар?

З колонки, указаної в рядку «Артикул виробника» — типово це однойменна колонка картки. Якщо каталог приїхав із сайту, джерело міняють на «ID товару (рядок UUID)»: саме там лежить артикул сайту. Формула працює лише з увімкненим прапорцем «Оновлювати» в цьому рядку, а перевіряють її пробним прогоном — у запиті видно значення article.

Чи їдуть на сайт характеристики товару?

Так, якщо ввімкнена галочка «Атрибути». Значення передаються за кодами атрибутів, окремо для кожної мови.

У шляху категорії стоїть «Головна / Каталог товарів». Що з цим робити?

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

Що робити, якщо прогін обірвався на помилці?

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

Суміжні теми

• Вивантаження товарів на маркетплейс, сайт і у файл — відбір, розклад, журнал, пробний прогін.
• Імпорт каталогу й замовлень з Хорошоп — зворотний напрямок: каталог і замовлення із сайту в Elbuz.
• Формули полів — як працюють вирази в полях каталогу.