Як оновлювати товари на сайті Хорошоп (Horoshop) з Elbuz

Що вміє вивантаження на Хорошоп

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

Де це і хто має доступ

Меню

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

Створити

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

Налаштувати

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

Право доступу

вікно «Вивантаження даних»; для картки — «Детальне налаштування шаблону вивантаження»

Підготувати

користувача API в адмінпанелі Хорошопу

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

1

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

2

Логін

3

Стан шаблону

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

Як підключити сайт

Підключення тримається на адресі сайту й парі логін-пароль. Сайт має бути доступний у момент прогону: Elbuz звертається до нього напряму.

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

Які товари їдуть на сайт

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

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

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

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

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

Набір полів ви складаєте самі. Кнопка «Налаштування вивантаження полів» у картці шаблону відкриває список, де в кожного поля є прапорець «Оновлювати». У новому шаблоні увімкнені три поля: «Ціна», «Статус наявності» і «Категорія».

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

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

1

Оновлювати

2

Поле API article

3

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

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

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

Рядок, який сайт називає article, — ключ: за ним сайт шукає товар і вирішує, оновити картку чи завести другу.

• У нового шаблону рядок називається «ID товару (рядок UUID)». Туди лягає артикул сайту, коли каталог завантажено із цього сайту, — міняти нічого не треба.
• У старішого шаблону рядок може брати «Артикул виробника», який у карток із сайту частіше порожній. Впишіть у колонку «Формула» цього рядка {Товар БК: ID товару (рядок UUID)}.

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

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

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

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

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

Як товар лягає в потрібний розділ

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

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

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

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

У першому варіанті сайт шукає розділ «Головна» і не знаходить його: товар не заводиться або лягає не туди. Зауваження сайту до окремих товарів видно в журналі (прогін), а шлях найпростіше перевірити пробним прогоном.

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

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

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

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

1

Поле API parent

2

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

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

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

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

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

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

Поле «Статус наявності» передає сайту не число, а слово. Типову назву статусу Elbuz замінює коротким словом, яке розуміє сайт. Типовими вважаються:

• російські В наличии, Нет в наличии, Ожидание 2-3 дня, Предзаказ, Под заказ;
• українські В наявності, Немає в наявності, Немає на складі, Під замовлення, Під замовлення 2-3 дні, Очікування 2-3 дні.

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

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

Наявність на Хорошопі не оновлюється: що перевірити

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

1. Чи є шаблон вивантаження. У «Вивантаженні даних» має бути шаблон типу «CMS Хорошоп API». Шаблон завантаження з Хорошопа наявність на сайт не відправляє.
2. Чи був прогін. Сайт нічого не забирає сам: подивіться дату останнього прогону й чим він закінчився.
3. Чи ввімкнене поле. У рядку «Статус наявності» списку полів має стояти «Оновлювати».
4. Чи змінився статус у Elbuz. На сайт їде статус, а не кількість: кількість нуль при статусі «В наявності» дасть «у наявності».
5. Чи товар пройшов відбір. Товари, що не пройшли відбір, випадають мовчки.
6. Чи не відсіяла галочка «Вивантажувати лише нові дані». Зніміть її й запустіть прогін.
7. Чи сайт упізнав товар. Різний артикул у Elbuz і на сайті — оновиться інша картка (джерело артикула).
8. Чи сайт не відкинув значення. Рядок «Хорошоп прийняв пакет із зауваженнями» — наприклад, своя назва статусу, якої сайт не знає: задайте для неї текст.

Як перевірити й запустити вивантаження

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

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

1

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

2

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

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

Запуск вручну й за розкладом — як у всіх шаблонів: Запуск руками і за розкладом.

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

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

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

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

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

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

Сценарії

Оновлювати на сайті лише ціни й наявність

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

Що ввімкнути: у картці шаблону — галочку «Товари»; у вікні «Налаштування вивантаження полів» прапорець «Оновлювати» лише в рядках «Ціна» і «Статус наявності». Рядок «Категорія» в новому шаблоні ввімкнений — зніміть прапорець і з нього.

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

Свої назви статусів наявності

Задача: статуси наявності в Elbuz мають власні назви, а сайт має показувати свої слова.

Що ввімкнути: прапорець «Оновлювати» в рядку «Статус наявності»; у вікні «Налаштування оновлення за наявністю товару» для кожного статусу — текст у колонці «Назва на сайті (у файлі)» і позначку «Активність налаштування».

Що вийде: на сайт поїде вписаний текст, навіть якщо назва статусу типова. Статус без тексту й без типової назви поїде назвою з Elbuz як є.

Модифікації мають зібратися в одну картку

Задача: модифікації товарів мають стати на сайті варіантами головного товару, а не окремими картками.

Що ввімкнути: прапорець «Оновлювати» в рядку «ID головного товару». Головний товар теж має проходити відбір шаблону.

Що вийде: модифікація отримає в це поле артикул головного товару. Якщо головний товар у вигрузку не потрапляє, поле не надсилається, і модифікація поїде як звичайний товар. Самому головному товару це поле не надсилається.

Каталог приїхав із сайту — розділи за id

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

Що ввімкнути: прапорець «Оновлювати» в рядку «Категория ID UUID» і зняти його з рядка «Категорія».

Що вийде: сайт отримає id розділу, що приїхав разом із розділом. Службові рівні «Головна / Каталог товарів» ні на що не впливають. Розділ, заведений в Elbuz вручну, такого id на сайті не має.

Що робити, коли сайт не оновився

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

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

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

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

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

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

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

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

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

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

З колонки в рядку поля article. У нового шаблону це «ID товару (рядок UUID)»; у старішому джерело міняють формулою (джерело артикула).

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

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

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

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

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

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

Суміжні теми

• Якщо каталог або замовлення треба забрати із сайту в Elbuz — Імпорт каталогу й замовлень з Хорошоп.
• Якщо треба налаштувати розклад, відбір чи прочитати журнал — Шаблони вивантаження.
• Якщо формула в списку полів не складається — Формули полів.