Etsy

Які товари можна продавати на Etsy

Etsy допускає товари, які продавець виготовив, розробив, особисто відібрав або постачає відповідно до правил платформи. Це можуть бути прикраси, кераміка, декор, одяг власного дизайну, матеріали для рукоділля. Вінтажні речі мають бути віком від 20 років. Для товарів, виготовлених за власним дизайном стороннім виробником, потрібно розкривати інформацію про виробничого партнера.

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

Як має працювати обмін

Для підключення потрібен окремий сервіс обміну — програма, яку розробник створює між Торгсофт і Etsy. Вона читає експорт Торгсофт, звертається до API Etsy та готує файли замовлень для завантаження в облік.

Кількість для продажу має визначатися за даними Торгсофт з урахуванням резервів і ще не імпортованих замовлень Etsy. Ціну для публікації можна брати з Торгсофт за погодженим правилом. У замовленні потрібно зберігати фактичну ціну покупки на Etsy, включно із застосованою знижкою.

Крок 1. Підготувати товари й визначити склад

До розробки обміну потрібно перевірити фактичну наявність товарів і виправити розбіжності в обліку. Далі визначити центр обліку, з якого виконуватимуться замовлення Etsy.

Для кожного виробу та його складського варіанта потрібна окрема облікова позиція. Наприклад, біла футболка розміру M і біла футболка розміру L повинні мати власні ідентифікатори й залишки. Артикул Etsy, або SKU, має однозначно вказувати на відповідну позицію.

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

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

Крок 2. Налаштувати файловий обмін у Торгсофт

Для описаної схеми потрібна опція «Синхронізація з інтернет-магазином». Після її активації доступне меню «Склад → Синхронізація з Інтернет-магазином».

1. Створити об’єкт синхронізації з назвою, за якою можна впізнати магазин Etsy.
2. На вкладці «Центри обліку» вибрати склади, залишки яких дозволено передавати для продажу, та перевірити параметр «Товар списувати з».
3. Налаштувати адресу доставки інформації для файлового обміну із сервісом, який підготував розробник.
4. У налаштуваннях товарного файлу вибрати потрібні поля та ввімкнути формування назв колонок. Це допоможе сервісу правильно розпізнавати дані.
5. Вибрати кодування UTF-8 та погодити його обробку з розробником. Документація Торгсофт вимагає BOM для текстового файлу замовлення в цьому кодуванні.
6. Налаштувати резервування товарів рахунка та розклад синхронізації.

Торгсофт може експортувати товари у файл TSGoods.trs — CSV із роздільником ;, або у формат YML. Для початкового підключення зручно погодити один формат і сталий набір колонок. Порядок та склад полів налаштовуються в програмі.

Сервіс має забирати цей файл, перетворювати записи на запити Etsy та повертати замовлення у файлах .sal. Etsy самостійно такі файли Торгсофт не обробляє. Усі перетворення виконує розроблений сервіс.

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

Крок 3. Отримати доступ до Etsy API

Etsy пропонує різні рівні доступу. Seller App призначений для власного магазину продавця. Для сервісу, який підключатимуть різні продавці, розробник починає з Personal App. Для використання багатьма магазинами потрібно отримати Commercial Access; Etsy розглядає такі заявки вручну.

Тип застосунку потрібно вибирати за його фактичним призначенням. Умови доступу описані в документації Etsy Open API v3.

Власник магазину дозволяє доступ через OAuth 2.0 з PKCE: відкриває сторінку Etsy та підтверджує права застосунку. Сервіс повинен зберігати отримані токени й оновлювати доступ через refresh token.

Для читання оголошень потрібен дозвіл listings_r, для їх зміни — listings_w, для отримання замовлень — transactions_r. Передавання даних про відправлення потребує transactions_w та окремого дозволу Etsy на відповідний метод.

Кожний API-запит повинен містити x-api-key у форматі keystring:shared_secret. Для захищених операцій також потрібен заголовок Authorization: Bearer …. Деталі наведені в інструкції з авторизації. Пароль облікового запису Etsy сервісу передавати не потрібно.

Крок 4. Зіставити товари Торгсофт з оголошеннями Etsy

Для першого запуску можна використати оголошення, які продавець уже підготував на Etsy. Розробник пов’язує їхні товарні варіанти з позиціями Торгсофт і перевіряє відповідність артикулів.

Одне оголошення Etsy може містити кілька варіантів. Тому для зв’язку потрібно зберігати магазин shop_id, оголошення listing_id та відповідний товарний варіант Etsy. Кожному складському варіанту Торгсофт має відповідати конкретна комбінація характеристик.

Приклад зіставлення з умовними ідентифікаторами:

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

Що потрібно для автоматичного створення оголошень

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

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

Крок 5. Завантажувати замовлення в Торгсофт

Сервіс повинен регулярно отримувати замовлення через API. Якщо для застосунку доступні webhooks — автоматичні повідомлення Etsy про події, — можна додати обробку order.paid. Після повідомлення потрібно завантажити актуальні дані замовлення. Etsy також документує події скасування, відправлення й доставки.

Для webhooks потрібна загальнодоступна адреса приймання та перевірка підпису запиту. Їх доступність для вибраного застосунку потрібно перевірити під час реєстрації. Періодичне отримання замовлень варто зберегти для відновлення пропущених подій. Вимоги описані в документації webhooks.

Перед створенням файлу для Торгсофт сервіс перевіряє статус оплати, склад замовлення, відповідність усіх товарів, валюту та адресу одержувача. Власний номер замовлення варто формувати з shop_id і receipt_id, щоб розрізняти замовлення кількох магазинів.

Приклад файлу замовлення

Нижче — приклад текстового файлу .sal з умовними даними. Значення GoodID потрібно замінити ключем реального товару. Дані одержувача, номер замовлення, ціну й кількість сервіс бере з Etsy.

[Client]
Name=Ім’я одержувача з Etsy
Country=Germany
City=Berlin
ZIP=10115
Address=Адреса одержувача з Etsy

[Options]
OrderNumber=etsy-12345678-987654321
SaleType=5
CurrencyInternationalCode=USD
Comment=Etsy: оплату покупця підтверджено; відправлення очікує обробки

[1]
GoodID=201
Price=35,00
Count=2

У цьому прикладі SaleType=5 створює рахунок. Позначення оплати в коментарі саме по собі не проводить фінансову операцію. Такий варіант підходить для початкової перевірки імпорту, коли оплату й відвантаження ще обробляє працівник.

Документований формат Торгсофт також підтримує інші сценарії:

Для автоматичного обліку оплаченої покупки можна розглянути SaleType=2 після перевірки фінансових налаштувань. SaleType=3 означає також відвантаження товару, тому його застосування потрібно прив’язати до погодженої складської операції. Подія оплати на Etsy не підтверджує передавання посилки перевізнику.

У документації є попередження: сценарії SaleType=2–5 передбачають наявність потрібного товару; за його відсутності можливий продаж у мінус. Перед імпортом потрібна перевірка доступної кількості. Підтримку валюти замовлення через CurrencyInternationalCode документовано з версії бази даних 493.

Файл слід записувати повністю до того, як він стане доступним для імпорту. Ім’я файлу має складатися з ASCII-символів. Для UTF-8 потрібно виконати вимоги Торгсофт щодо BOM. Перед запуском розробник перевіряє імпорт на встановленій версії програми.

Як оновлювати залишки без повторного продажу зарезервованого товару

Після створення рахунка товар потрібно зарезервувати. У Торгсофт для цього є налаштування «Резервувати товари рахунка». Строк резерву має покривати підготовку замовлення; оплачений виріб не повинен знову потрапляти у доступний залишок через завершення цього строку.

Для сервісу обміну варто визначити таке правило:

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

Наприклад, із 10 готових виробів 2 зарезервовано, ще 1 оплачено на Etsy й очікує імпорту. Якщо страховий запас становить 1, для продажу доступно 6 виробів. Цей приклад передбачає, що початкові 10 — фізична кількість до віднімання резервів.

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

Оновлення варіантів Etsy виконується через updateListingInventory. Цей метод потребує повного набору товарних варіантів оголошення. Сервіс має зберігати всі комбінації та коректні правила залежності ціни, кількості й SKU від характеристик. Деталі наведені в описі оновлення залишків Etsy.

Що робити при скасуванні та поверненні

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

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

Як обліковувати оплату та передавати трек-номер

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

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

Після відправлення сервіс може передати Etsy перевізника та трек-номер через createReceiptShipment. Доступ до цього методу Etsy схвалює окремо: Commercial Access і дозвіл transactions_w не гарантують його доступності. До отримання дозволу продавець додає відправлення в кабінеті Etsy.

Купівля Etsy Shipping Labels через Open API v3 не підтримується. Обмеження наведені в документації виконання замовлень.

Що розробник має передбачити для щоденної роботи

• Захист від повторного імпорту за парою shop_id + receipt_id. Повторна подія або запит не повинні створювати ще один рахунок.
• Облік станів обробки: отримано замовлення, підготовлено файл, передано на імпорт, підтверджено створення документа. Передавання файлу не дорівнює успішному імпорту.
• Звірку за номером замовлення після збою. Якщо результат імпорту невідомий, спочатку потрібно знайти документ у Торгсофт, а потім вирішувати, чи потрібна повторна спроба.
• Послідовне оновлення кожного оголошення та перевірку актуальності даних перед зміною кількості.
• Журнал помилок із номером замовлення, товаром, причиною та потрібною дією працівника. Паролі й токени в журнал потрапляти не повинні.
• Контроль часу останнього успішного експорту, отримання замовлень і оновлення Etsy. За тривалої затримки працівник має отримати повідомлення.

Etsy обмежує кількість API-запитів за секунду та за добу для ключа застосунку. Сервіс повинен враховувати свої квоти й обробляти відповідь 429 з паузою за retry-after. Значення квот потрібно перевіряти в кабінеті розробника та заголовках відповіді, як описано в правилах обмеження запитів.

Обмін має працювати через дозволений API та відповідати умовам Etsy. Дані покупців потрібно використовувати лише в межах дозволеного обслуговування. Передавання їх до рекламних сервісів і небажані маркетингові розсилки заборонені. Для комерційного застосунку доступ до buyer_email запитується окремо; імпорт не повинен залежати від обов’язкової наявності цього поля.

Що перевірити перед автоматичним запуском

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