Імпорт лістингів і замовлень з Etsy

Etsy — міжнародний майданчик для handmade, вінтажу й товарів для творчості, з основною аудиторією у США та ЄС. На відміну від класичних маркетплейсів, тут продавець створює власні лістинги: картку веде він сам, а не майданчик. Це означає, що Elbuz може працювати з Etsy у повному циклі — забирати лістинги в базовий каталог, приймати замовлення, оновлювати ціни й залишки, а за потреби й публікувати нові лістинги.

Загальний порядок для всіх API-джерел каталогу описано в огляді імпорту каталогу через API, спільні правила замовлень — в огляді імпорту замовлень. Тут — про Etsy.

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

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

1

Поле «Shop ID»

2

Поле «Shipping profile ID»

1. Shop ID можна лишити порожнім — визначиться автоматично.
2. Shipping profile ID потрібне для публікації лістингів.

Як підключити: код прив'язки

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

У картці «Підключення» лишаються два необов'язкові поля:

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

Як підключити крок за кроком

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

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

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

Elbuz забирає активні лістинги магазину разом із фотографіями й даними про наявність.

Ціна й залишок беруться саме з блоку наявності лістинга — того, що Etsy показує покупцеві, — і лише якщо його немає, Elbuz бере значення з самої картки.

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

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

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

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

Окремо про вимкнені товари. З Etsy приходять лише активні лістинги, тому в картку завжди пишеться «увімкнено»: вимкнули товар руками в Elbuz — наступний прогін увімкне його назад.

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

Лістинг зник з Etsy — що буде з карткою

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

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

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

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

Замовлення

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

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

Чек лягає документом «Замовлення покупця», і лягає непроведеним. Це важливо для складу: саме завантаження замовлень наявність у каталозі не зрушує — ні залишок, ні резерв не зміняться, поки документ не проведуть.

Статус документа береться зі зіставлення, яке налаштовують кнопками «Статуси замовлення», «Статуси оплати» й «Статуси доставки» в секції «Повʼязані налаштування» картки шаблону. Для Etsy ключ зіставлення — стан чека, як його називає сам майданчик; якщо стану в чеку немає, Elbuz підставляє shipped для відправленого або paid для оплаченого. В оплаті кодів рівно два: paid і unpaid. Стан, якого в зіставленні немає, дає документ з першим статусом довідника.

1

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

2

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

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

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

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

Оновлення цін і залишків

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

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

У відбір вивантаження товар потрапляє, лише якщо в нього стоїть позначка «Вивантажувати у файл (на сайт)», а його категорія ввімкнена й теж бере участь у вивантаженнях. Це окремо важливо для товарів, що лягли у службову категорію «Товари - etsy»: вона створюється вимкненою, тож поки ви не розкладете такі товари по своїх категоріях, назад на Etsy вони не поїдуть.

У журналі вивантаження на кожні 50 успішно оновлених лістингів стоїть рядок «Etsy: оновлено лістингів: N», у кінці — «Etsy: ціни та залишки оновлено, лістингів: N (помилок: M)». Відмову по конкретному лістингу Etsy пояснює своїм текстом, і він потрапляє в журнал окремим червоним рядком разом із назвою товару.

Публікація нових лістингів

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

Один новий лістинг — це п'ять звернень до Etsy: чернетка, фотографія, читання й запис блоку наявності з ціною, залишком і артикулом, активація. Обов'язкові для Etsy поля, яких у картці товару немає, Elbuz заповнює фіксованими значеннями: «зроблено мною», «виготовляється на замовлення», фізичний товар. Якщо ваш випадок інший — вінтаж або матеріали для творчості, — поправте це в самому лістингу після публікації. Заголовок при цьому обрізається до 140 символів, опис — до 5000 і йде без HTML-розмітки, кількість ставиться не менша за одиницю.

У кінці прогону журнал підсумовує: «Etsy: створено нових лістингів: N (помилок: M). Публікація лістингу на Etsy платна ($0.20)» — плату бере майданчик, за кожен опублікований лістинг. Товари, пропущені через незіставлену таксономію, рахуються окремим рядком.

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

Помилкове завантаження. Картки, які завело це підключення, знаходяться у вікні «Товари» за колонками «Джерело: назва» й «Джерело: код» (для Etsy код — etsy), а ті, які підключення лише перезаписало, — за сьогоднішньою «Датою оновлення». Порядок тут спільний для всіх API-підключень і розібраний в огляді імпорту каталогу: масового відкоту значень у програмі немає, збережену історію має тільки ціна.

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

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

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

Каталог не чекає кінця прогону. Лістинги приходять сторінками по 100, а в базовий каталог лягають пачками по 500 — щойно пачка набралася. Тому обрив ділить результат надвоє: усе, що встигло лягти пачками, лишається в каталозі оновленим, а недочитана пачка зникає — її візьме наступний прогін.

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

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

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

Межі: пачки, ліміти, повтори

Числа, за якими видно, чого чекати від великого магазину:

• Сторінка каталогу — 100 лістингів, запис у каталог — пачками по 500. Стелі на кількість позицій за прогін немає: скільки віддасть Etsy, стільки й приїде.
• Сторінка замовлень — 100 чеків, позиції приходять разом із чеком, окремих запитів на кожен товар не потрібно.
• Одного звернення Elbuz чекає до 120 секунд, на встановлення зв'язку відводить до 30. Не дочекався — прогін зупиняється з помилкою в журналі.
• Ліміт звернень Etsy. Коли майданчик відповідає «забагато запитів», Elbuz робить до трьох спроб, тобто повторює запит ще двічі. Перед повтором чекає стільки, скільки назвав сам Etsy (але не довше за 30 секунд), інакше дві, потім чотири секунди. Якщо й третя спроба впирається в ліміт, прогін зупиняється з помилкою «HTTP 429: rate limit».
• Оновлення цін — два звернення на кожен лістинг; публікація нового — п'ять, плюс плата майданчика за публікацію.

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

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

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

1

Стан шаблону

2

Завантажити

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

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

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

Розклад

Etsy працює поллінгом: Elbuz звертається до майданчика за розкладом. Розклад задають кнопкою «Налаштування розкладу» в секції «Повʼязані налаштування» картки шаблону. Для магазину з рівним потоком замовлень вистачає кількох запусків на день; каталог достатньо оновлювати раз на добу.

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

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

Сценарії

Перенести каталог з Etsy в Elbuz і тримати його свіжим

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

Що вийде: кожен активний лістинг стає карткою товару. Лістинг з новим заголовком заводить нову картку, зі знайомим — перезаписує назву, опис, кількість, теги й артикул у наявній. Фотографії приїдуть тільки з галочкою «Фото».

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

Приймати замовлення з Etsy, не рухаючи склад до перевірки

Що ввімкнути: у тому самому шаблоні галочку «Замовлення», а в секції «Повʼязані налаштування» — зіставлення станів чека зі своїми статусами кнопками «Статуси замовлення», «Статуси оплати» й «Статуси доставки».

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

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

Вести залишок в Elbuz і передавати ціни й залишки на Etsy

Що ввімкнути: окремий шаблон вивантаження типу «Etsy» з галочкою «Товари». У товарів має стояти позначка «Вивантажувати у файл (на сайт)», а їхня категорія — бути ввімкненою й з тією ж позначкою. Зв'язок товару з лістингом дає попереднє завантаження каталогу з Etsy.

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

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

Доробляти картки в Elbuz так, щоб завантаження їх не затерло

Що ввімкнути: у картці товару, секція «Захист під час імпорту», перемикач «Не оновлювати» — якщо картку треба закріпити цілком, або «Фіксована ціна» — якщо своїми мають лишитися тільки ціни.

Що вийде: з «Не оновлювати» прогін картку пропускає, з «Фіксована ціна» — оновлює все, крім цін.

Чого не буде: картка з «Не оновлювати» не отримає з Etsy і свіжого залишку. І захист не допоможе, якщо лістинг перейменували в кабінеті Etsy: за новим заголовком прогін стару картку не впізнає й заведе поруч нову.

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

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

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

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

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

Чи треба реєструвати застосунок Etsy?

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

Що вписувати в поле Shop ID?

Можна нічого не вписувати: Elbuz визначить ідентифікатор магазину сам. Заповнити поле варто, якщо на акаунті кілька магазинів або якщо в журналі з'явилося повідомлення, що Shop ID визначити не вдалося.

Чому новий лістинг залишився чернеткою?

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

Чому товари потрапили в категорію джерела, а не в потрібну?

Etsy передає категорію числовим кодом таксономії, а зрозуміле ім'я Elbuz бере з довідника, який завантажують окремо — кнопкою «Завантажити довідник майданчика» у вікні «Зіставлення категорій та атрибутів з маркетплейсами». Поки довідника немає, ім'я категорії порожнє й товари лягають у службову категорію «Товари - etsy», вимкнену й без участі у вивантаженнях. Розкладіть їх по своєму дереву — далі оновлення потраплятимуть саме туди.

Чому в замовленнях з Etsy немає телефону?

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

Чи затре повторне завантаження мої правки в картці?

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

Я зняв лістинг з продажу на Etsy — товар у Elbuz вимкнеться?

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

Що зупиниться, якщо вимкнути шаблон?

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