Коротко: більшість помилок Хорошоп API мають одну з п’яти причин. Відповідь 409 «Api module is not available» означає, що модуль API у магазині вимкнений, і ввімкнути його може тільки підтримка Хорошопу. «User with such username/password not found» найчастіше з’являється, коли замість логіна вводять email. UNAUTHORIZED посеред роботи означає, що токен застарів. Код 429 означає, що вичерпано годинний ліміт запитів. EMPTY помилкою не є: дані просто скінчилися.
Ми підключаємо Хорошоп API для кількох віджетів widgetis і зібрали тут усе, на що натрапили. Загальний огляд того, що вміє API і на якому тарифі воно є, у статті Хорошоп API: що вміє і як підключити. Тут тільки помилки і їхні рішення.
Які статуси повертає Хорошоп API і що вони означають?
Кожна відповідь API це JSON з полем status, а подробиці лежать у полі response. Код HTTP при цьому часто 200 навіть для помилки, тому перевіряйте саме status.
| Статус | Що означає | Що робити |
|---|---|---|
| OK | Запит виконано | Нічого |
| EMPTY | Даних немає: сторінки експорту скінчилися або фільтр нічого не знайшов | Зупинити перебір сторінок, це не помилка |
| WARNING | Імпорт виконано частково: частина рядків не застосувалась | Прочитати пояснення в response і виправити ці рядки |
| UNAUTHORIZED | Токен неправильний або застарів | Отримати новий токен і повторити запит |
| ERROR | Помилка в запиті або неправильний логін і пароль при авторизації | Прочитати response.message |
| HTTP_ERROR | Помилка з кодом у response.code, наприклад 429 | Дивитися код, для 429 чекати |
Що означає 409 «Api module is not available»?
Відповідь 409 «Api module is not available. Please contact support.» означає, що модуль API для цього магазину вимкнений. Логін і пароль тут ні до чого: Хорошоп перевіряє модуль раніше за токен, тому 409 приходить навіть на запит з вигаданим токеном. Авторизація при цьому може видати токен, і це збиває з пантелику.
- Перевірте тариф. За сторінкою тарифів horoshop.ua, API є в тарифах Pro і B2B. Порівняння тарифів є в статті тарифи Хорошоп 2026.
- Попросіть підтримку ввімкнути модуль. Напишіть у чат в адмінці магазину або на support@horoshop.ua. Самостійно в адмінці модуль не вмикається.
- Не вірте фразі «у нас API працює». Готові інтеграції CRM і фіди для Google Shopping працюють і без модуля API, тому те, що вони працюють, ще нічого не доводить.
Швидка перевірка без логіна і пароля: надішліть POST-запит на https://ваш-домен/api/catalog/export/ з тілом {"token": "x"}. Якщо у відповідь прийшов 409, модуль вимкнений. Якщо прийшов UNAUTHORIZED з текстом «Incorrect auth data», модуль працює, а неправильний тільки токен, як і має бути.
Чому API не пускає з правильним паролем?
Найчастіша причина: на адресу /api/auth/ надіслали email замість логіна. Адмінка Хорошопу пускає і за email, і за логіном, а API приймає тільки поле «Логін» користувача. З email приходить ERROR «User with such username/password not found», а з логіном і тим самим паролем приходить OK і токен.
- Відкрийте в адмінці Налаштування → Адміни і знайдіть користувача, від імені якого працює інтеграція.
- Скопіюйте поле «Логін», а не email.
- Надішліть POST на https://ваш-домен/api/auth/ з тілом {"login": "логін", "password": "пароль"} і заголовком Content-type: application/json.
- У відповіді з status OK візьміть токен з response.token і передавайте його в кожному наступному запиті.
Ще дві дрібниці з документації. Хорошоп просить надсилати тільки POST з JSON у кодуванні UTF-8 без BOM: приклади GET-запитів з документації прибрали як небезпечні. І заводьте окремого користувача на кожну інтеграцію, щоб за потреби вимкнути одну, не чіпаючи решту.
Чому UNAUTHORIZED з’являється посеред синхронізації?
Токен живе недовго: за документацією, 600 секунд. Якщо програма отримала токен на початку і читає великий каталог годину, наступні запити отримають UNAUTHORIZED. Правильна реакція: отримати новий токен і повторити той самий запит один раз. Якщо і після нового токена приходить UNAUTHORIZED, проблема в логіні, паролі або правах користувача.
Не тримайте токен у кеші годину «про запас». Ми так і робили спочатку, і синхронізація гарантовано падала посередині. Тепер кешуємо токен на 10 хвилин і повторюємо запит при UNAUTHORIZED.
Що робити з помилкою 429 і як не втратити прогрес?
Код 429 приходить як HTTP 200 з тілом {"status": "HTTP_ERROR", "response": {"code": 429, "message": "... Retry after N seconds"}}. Це годинний ліміт запитів, і він спільний для всіх інтеграцій магазину: CRM, облік, ваш скрипт і ручні перевірки витрачають одну квоту. Чекати іноді доводиться майже годину, ми бачили N = 2 676 секунд.
- Чекайте рівно N секунд з повідомлення, а не повторюйте запит кожну хвилину: повтори теж рахуються.
- Продовжуйте з того самого offset. Зберігайте номер сторінки, на якій зупинились, щоб не читати каталог спочатку.
- Не перевіряйте API руками у робочий час, коли працює нічна синхронізація чи CRM: ви з’їдаєте їхню квоту.
Як прочитати весь каталог і отримати правильні ціни?
Експорт каталогу віддає не більше 500 товарів за запит, тому каталог читають сторінками: offset 0, 500, 1 000 і так далі, поки не прийде EMPTY або менше рядків, ніж просили. Фільтр за артикулом у цьому методі не працює, тож це завжди повний перебір. Каталог на 21 000 товарів це близько 45 запитів і кілька хвилин.
Пастка з ціною: у відповіді поле price це базова ціна, а discount це відсоток знижки. Покупець на сайті платить price × (100 − discount) / 100. Товар з price 485 і discount 40 на сайті коштує 291 ₴. Якщо імпортувати price як є, усі товари зі знижкою вийдуть дорожчими, ніж на вітрині. Поле price_old це закреслена ціна, яку магазин поставив вручну.
Так ми читаємо каталог для віджетів 1+1=3 і рекомендацій у кошику: щоб у подарунок чи в рекомендації не потрапив товар, якого вже немає, або товар з неправильною ціною. Ще одне поле, яке варто знати: presence.id 1 означає «в наявності», 2 означає «немає в наявності». Якщо вам потрібна не власна програма, а обмін з CRM, почніть з готових інтеграцій зі статті яку CRM підключити до Хорошоп.
Логін і пароль API відкривають дані всього магазину. Давайте їх окремому користувачу під одну інтеграцію і тільки тому, хто пояснив, що саме читатиме і що записуватиме.Віджети для середнього чека на Хорошоп
Часті питання
Як виправити помилку «Api module is not available» у Хорошоп?
Ця відповідь з кодом 409 означає, що модуль API у магазині вимкнений. Перевірте, що тариф Pro або B2B, і напишіть у підтримку Хорошопу через чат в адмінці або на support@horoshop.ua з проханням увімкнути модуль API. Самостійно в адмінці він не вмикається, а логін і пароль тут ні до чого.
Чому Хорошоп API пише «User with such username/password not found»?
Найчастіше через те, що в запит до /api/auth/ передали email замість логіна. Адмінка пускає за email, а API приймає тільки поле «Логін» з картки користувача в Налаштування → Адміни. Якщо логін правильний, перевірте пароль і те, що користувач не вимкнений.
Скільки живе токен Хорошоп API?
За документацією Хорошопу, 600 секунд. Довга синхронізація має отримувати новий токен, коли приходить UNAUTHORIZED, і повторювати той самий запит. Кешувати токен на годину не варто: запити посередині роботи почнуть падати.
Скільки товарів можна отримати одним запитом експорту?
Не більше 500, навіть якщо в limit вказати більше. Великий каталог читають сторінками через offset, поки не прийде статус EMPTY. Пам’ятайте про годинний ліміт запитів: при його вичерпанні API відповідає кодом 429 і кількістю секунд, які треба почекати.