Rozetka Seller API: як забрати замовлення, коли вебхуків немає
Rozetka не надсилає вебхуків, а фільтрує замовлення лише за датою. Розбираємо, як через це виглядає надійний цикл імпорту — і які три речі ламають наївну реалізацію.
Більшість інтеграцій починають із питання «куди Rozetka надішле вебхук». Відповідь: нікуди. Seller API Rozetka — це API запитів, а не подій: доки ви самі не спитаєте, чи є нові замовлення, ви про них не дізнаєтесь.
Це змінює всю архітектуру. Замість endpoint-а, який чекає, потрібен цикл, який ходить за розкладом, помʼятає, де зупинився минулого разу, і не створює дублів, коли той самий прогін відбувся двічі. Нижче — контракт так, як він поводиться насправді, і три місця, де наївна реалізація тихо втрачає замовлення.
Контракт: що потрібно знати перед першим запитом
Значення нижче взяті з офіційної документації Seller API і звірені на реальному кабінеті.
- База
- api-seller.rozetka.com.ua — окремий хост від публічного сайту
- Авторизація
- POST /sites із логіном продавця й паролем, закодованим у base64. У відповідь — токен, який живе близько 24 годин.
- Читання замовлень
- GET /orders/search — обовʼязково з розгортанням позицій, доставки й покупця, інакше в замовленні не буде ні товарів, ні адреси
- Фільтр за часом
- Лише за ДАТОЮ, не за часом. Точності «з такої-то хвилини» контракт не дає.
- Позиції
- Масив покупок у складі замовлення; рядок зі станом «видалено» присутній у відповіді й мусить бути пропущений
- Статуси
- Числові й залежать від налаштувань конкретного кабінету — не універсальний перелік
- Запис статусу
- PUT /orders/{id} — після логіну, тим самим токеном
- Товари
- GET /items/search для читання; PUT /items/update-price-stock/{id} для ціни й залишку. Створити лістинг через API неможливо.
- Валюта
- Гривня
Цикл імпорту
- 1
Логін і токен
Обмінюємо логін/пароль на токен. Токен варто кешувати: логін на кожен запит — це і зайва латентність, і зайвий шум в аудиті на боці маркетплейсу.
- 2
Читання курсора
Дістаємо збережену дату останнього успішного прогону. Першого разу беремо добу назад, а не «весь час»: імпорт усієї історії на першому ж запуску — найшвидший спосіб отримати таймаут і незрозумілий частковий стан.
- 3
Запит із перекриттям
Питаємо замовлення, змінені з дати курсора МІНУС один день. Перекриття — не перестороженість, а наслідок фільтра лише за датою (нижче докладно).
- 4
Нормалізація
Зводимо відповідь у власну модель замовлення чистою функцією без побічних ефектів: її можна протестувати на збереженому payload без жодного мережевого виклику.
- 5
Ідемпотентний запис
Створюємо замовлення з ключем, побудованим з id замовлення Rozetka. Повторний прогін не створює другого замовлення — він знаходить наявне.
- 6
Збагачення
На кожному проході — не лише на створенні — оновлюємо статус, оплату, спосіб доставки й номер накладної, якщо Rozetka їх уже віддала.
- 7
Запис курсора
І лише після успішного проходу зсуваємо курсор. Курсор, який зсувається до обробки, втрачає рівно ті замовлення, на яких прогін упав.
Чому денний курсор мусить мати перекриття
Фільтр «змінені з дати X» не має часової складової. Це означає, що ви не можете спитати «що змінилося за останні 15 хвилин» — тільки «що змінилося за сьогодні».
Звідси проблема межі доби. Прогін о 23:58 бачить сьогоднішні замовлення й записує курсор «сьогодні». Прогін о 00:03 питає «змінені з сьогодні» — а «сьогодні» вже інша дата, і замовлення, створене о 23:59, не потрапляє ні в перший запит, ні в другий. Воно просто зникає, і найгірше в цьому те, що ніщо не падає: логи чисті, лічильники зелені, а замовлення немає.
Лікування дешеве: питати завжди з дати курсора мінус один день. Ви щоразу перечитуєте до доби вже відомих замовлень — і саме тому попередній крок, ідемпотентність, обовʼязковий, а не бажаний. Без нього перекриття щодня створювало б дублікати; з ним воно безкоштовне.
Три речі, які ламають наївну реалізацію
- Рядок позиції зі станом «видалено» приходить у відповіді разом із живими. Хто його не фільтрує — отримує замовлення з товаром, якого покупець не купував, і сумою, що не збігається з кабінетом.
- Числові статуси не універсальні: у різних кабінетах ті самі числа можуть означати різні стани. Тому маппінг статусів має бути ОДНИМ явним блоком, який видно й можна звірити, а не константами, розсипаними по коду. І перехід, у якому ви не впевнені, безпечніше не надсилати взагалі, ніж вгадати.
- Перехід у доставку вимагає накладної. Спроба виставити «відправлено» без номера накладної не є станом, у який Rozetka дозволить перевести замовлення, тож цей перехід не має бути частиною автоматичного зворотного синку.
Ціни та залишки: тільки те, що вже опубліковано
Оновлення ціни й кількості працює за артикулом: у Rozetka поле артикула лістингу зіставляється з SKU товару у вашій системі. Це означає дві речі. Перша — дисципліна артикулів важливіша за будь-який код: товар без SKU або з SKU, який відрізняється регістром чи пробілом, не зіставиться. Друга — API оновлює лише наявні лістинги; створити новий товар через нього не можна, тому публікація нової позиції лишається дією в кабінеті продавця.
Кількість варто надсилати лише для товарів, де ви справді ведете облік залишків. Товар, який ви продаєте під замовлення, не має отримувати кількість «0» тільки тому, що поле залишку порожнє — це знімає його з продажу без жодної на те причини.
Кожен запис у чужий акаунт вимкнений за замовчуванням
Продавець приходить із товарами, які вже живуть на маркетплейсі. Тому читання можна вмикати одразу, а будь-який запис — ціни, залишки, статуси — лише після пробного прогону, який показує, що саме зміниться, нічого не змінюючи. Це не перестороженість: перший же помилковий масовий пуш цін по живому каталогу коштує дорожче, ніж уся інтеграція.
Часті запитання
Чи має Rozetka вебхуки для замовлень?
Ні. Seller API відповідає на запити, але сам подій не надсилає, тому нові замовлення можна отримати лише періодичним опитуванням. Практичний інтервал — 15 хвилин: частіше не має сенсу через фільтр лише за датою, рідше — вже помітно менеджеру.
Скільки живе токен Seller API?
Приблизно добу. Логін варто робити ліниво — коли токена немає або він перестав приймати запити, — а не на кожен виклик.
Чому пароль кодується в base64?
Так описано в контракті логіну. Це кодування, а не шифрування: пароль однаково має зберігатися зашифрованим у вас, а сам обмін відбуватися лише через HTTPS.
Чи можна створити товар на Rozetka через API?
Ні. Через API можна читати наявні лістинги й оновлювати їхню ціну та залишок. Створення нової позиції відбувається в кабінеті продавця.
Як не отримати дублікати замовлень при повторному прогоні?
Ключем ідемпотентності, побудованим з id замовлення Rozetka, на рівні запису в базу. Це обовʼязкова умова, а не оптимізація: перекриття курсора щодня перечитує вже відомі замовлення.
Чи потрібен окремий воркер?
У Obriym CRM — ні: опитування вбудоване й ходить за розкладом на боці CRM, продавцю потрібно лише зберегти логін кабінету. Якщо ви будуєте інтеграцію самостійно, воркер потрібен — і саме йому адресований цикл, описаний вище.
Не хочете будувати це самі?
В Obriym CRM цикл опитування, ідемпотентність, збагачення статусів і зворотний синк уже реалізовані — треба лише зберегти логін кабінету Rozetka.
Спробувати безкоштовно