Horoshop API підключення: 5 кроків + помилки

Якщо ви тримаєте магазин на Horoshop і хочете автоматизувати оновлення цін, залишків чи генерацію SEO-описів — рано чи пізно ви впираєтесь в одне завдання: Horoshop API підключення. На перший погляд воно здається простим — у документації п'ять кроків, юзер, токен, поїхали. На практиці ж новачки гублять години через лімит 100 запитів на годину, незрозумілі помилки 403, дубльовані товари після першого ж синку та поле mod_title, про яке ніхто не попередив.

Ця стаття — практичний гайд для власника магазину або розробника, який вперше підключає API Horoshop. Ми пройдемо всі п'ять кроків налаштування, розберемо типові граблі і покажемо, як з лімітом 100 req/hour жити без болю. У кінці — короткий FAQ і посилання на корисні матеріали.

Що дає Horoshop API і кому він взагалі потрібен

Horoshop — українська SaaS-платформа для інтернет-магазинів, яка надає REST-подібне API для роботи з каталогом, замовленнями та клієнтами. Через нього можна вивантажувати та оновлювати товари, отримувати замовлення, синхронізувати залишки з 1С, BAS чи власною ERP, підтягувати дані для аналітики.

Звучить добре, але є нюанс: API доступний лише на тарифах Pro і B2B. На стартовому тарифі вам його просто не активують — це перше, що варто перевірити перед тим, як платити розробнику за інтеграцію. Станом на 2025 рік Pro коштує близько 25–30 USD на місяць, B2B — від 60 USD, точну ціну дивіться на сайті Horoshop.

Типові сценарії інтеграції

• Імпорт товарів з постачальника (дропшипінг, прайси постачальників у XLSX/XML)
• Двостороння синхронізація залишків з 1С або BAS
• Передача замовлень у CRM (KeyCRM, NetHunt, Pipedrive)
• Автоматична генерація SEO-описів через AI-сервіси
• Експорт даних у BI (Looker Studio, Power BI) для аналітики

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

Крок 1. Перевірка тарифу і активація API

Зайдіть в адмінку Horoshop і відкрийте розділ Налаштування → Тариф. Якщо ви бачите Pro або B2B — рухаємось далі. Якщо у вас Start чи Demo, спочатку оформіть апгрейд: API без нього технічно недоступний, ніякі обхідні шляхи не працюють.

Далі напишіть у підтримку Horoshop коротке повідомлення на кшталт: «Прошу активувати API для домену mysite.com.ua, тариф Pro». Активація — ручна, займає від кількох хвилин до одного робочого дня. Без цього кроку запити повертатимуть 403 навіть з правильним токеном — і ви будете годинами шукати помилку в коді.

Поки чекаєте підтвердження, можна підготувати юзера для API.

Крок 2. Створення Content-manager юзера

Horoshop працює за принципом «API-юзер = окремий обліковий запис із обмеженими правами». Не використовуйте свій головний логін адміністратора — це погана практика з точки зору безпеки і логів.

1. Перейдіть у Налаштування → Користувачі
2. Натисніть «Додати користувача»
3. Логін: щось технічне, наприклад api_integration або api_1c
4. Пароль: складний, мінімум 16 символів, з цифрами і спецсимволами
5. Роль: Content-manager (саме ця роль має потрібні права без зайвого доступу)
6. Збережіть і запишіть креденшіали в менеджер паролів

Чому саме Content-manager, а не Admin? Адмін має доступ до фінансів, налаштувань тарифу, банківських даних. Якщо токен витече — наслідки серйозніші. Content-manager обмежений каталогом, замовленнями і клієнтами, цього достатньо для 95% інтеграцій.

Якщо ролі немає у списку

Іноді на старих акаунтах роль Content-manager відсутня. У такому разі створіть кастомну роль із правами: «Каталог: повний доступ», «Замовлення: читання + оновлення статусу», «Клієнти: читання». Уникайте позначки «Налаштування магазину».

Крок 3. Отримання токена і перший запит

Horoshop використовує авторизацію через POST-запит на ендпоінт /api/auth/. Ви відправляєте логін і пароль створеного юзера, у відповідь отримуєте JWT-токен, дійсний близько години (точний термін залежить від версії платформи).

Перший тестовий запит зручно зробити через Postman або curl:

• URL: https://yourdomain.com.ua/api/auth/
• Method: POST
• Body (JSON): {"login":"api_integration","password":"вашпароль"}

У відповідь має прилетіти JSON із полем token. Якщо ви бачите 401 — перевірте логін/пароль. 403 — ще не активований API (повертайтесь до кроку 1). 404 — у домені помилка або сайт не на Horoshop.

Отримали токен? Відмінно. Тепер найважливіше — лімити.

Крок 4. Лімит 100 запитів на годину і як з ним жити

Це місце, де провалюються більшість перших інтеграцій. Horoshop обмежує API до 100 запитів на годину на один токен. Не на день, не на хвилину — саме на годину. Якщо у вас 5000 товарів і ви наївно робите по запиту на кожен POST /api/catalog/import/, інтеграція впаде на 100-му товарі і відновиться лише через годину.

Як обходити ліміт без хитрощів

Спосіб номер один — batch-запити. Ендпоінт /api/catalog/import/ приймає масив товарів. В одному запиті можна передати 100, 500, навіть 1000 товарів (обмеження по розміру тіла — близько 10 МБ). Тобто 5000 товарів = 5–10 запитів, а не 5000.

Спосіб номер два — інкрементальні оновлення. Замість того щоб щогодини перезаливати весь каталог, тримайте локальну БД із хешем кожного товару і відправляйте лише змінені записи. На стабільному магазині це 20–50 товарів на день замість тисяч.

Що робити, якщо все одно впираєтесь у ліміт

• Розділіть процеси: ціни оновлюйте раз на годину, описи — раз на добу, нові товари — за подією від постачальника
• Кешуйте відповіді на читання (особливо /api/catalog/export/ — він повертає весь каталог)
• Розгляньте B2B-тариф: там лімітів або немає, або вони значно вищі (уточнюйте у саппорті)
• Реалізуйте retry-логіку з експоненційною затримкою при отриманні 429 Too Many Requests

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

Крок 5. Mod_title і чому одразу краще писати правильно

В Horoshop у кожного товару є два поля для назви: title (службова, для адмінки і внутрішнього обліку) і mod_title (та, що показується покупцю на сайті і в SEO-метатегах). Це специфіка платформи, якої немає у Shopify, WooCommerce чи Prom.ua.

Що відбувається, коли ви через API оновлюєте лише title? На сайті назва не змінюється. Покупець бачить старий варіант, Google теж. Ви годину дивитесь на код, оновлюєте товар вдесяте — без результату. А потім хтось у Telegram-чаті каже: «Чувак, ти ж mod_title не пишеш».

Правило просте: при будь-якому імпорті завжди передавайте обидва поля одночасно. Навіть якщо вам здається, що mod_title не потрібен — він потрібен. Те саме стосується mod_description, mod_h1, mod_keywords — поля з префіксом mod_ керують тим, що бачить користувач і пошуковик.

Якщо ви плануєте автоматизувати написання назв і описів через AI, почитайте окремий матеріал — SEO-опис товару для Horoshop: чек-лист на 12 пунктів. Там детальніше про структуру полів і вимоги пошукових систем.

Типові помилки при інтеграції з Horoshop API

Зібрав найчастіші проблеми, які зустрічаються у клієнтів при першому Horoshop API підключенні:

1. Помилка 403 при правильних креденшіалах — API не активований саппортом. Пишемо в підтримку.
2. Дублювання товарів після імпорту — не передали поле article або id. Horoshop ідентифікує товар саме за артикулом, без нього кожен імпорт створює нові картки.
3. Категорії «не приліплюються» до товару — передавайте parent як ID категорії, а не як назву. Спочатку експортуйте дерево категорій через /api/catalog/export-categories/.
4. Зображення не підтягуються — Horoshop вимагає прямі HTTPS-посилання на JPG/PNG, доступні без авторизації. Google Drive чи Dropbox-лінки не працюють.
5. Ціни обнуляються — у JSON ціна має бути числом, не рядком. Тобто "price": 1299, а не "price": "1299 грн".
6. Залишки не оновлюються — поле називається presence, а не stock. Допустимі значення: «В наявності», «Немає в наявності», «Очікується», «Під замовлення».
7. Токен «протухає» серед робочого дня — реалізуйте автоматичне оновлення кожні 50 хвилин або при отриманні 401.

Якщо обираєте платформу і ще не вирішили остаточно, рекомендую матеріал Horoshop чи Prom.ua у 2026: чесне порівняння для нового магазину — він допоможе зрозуміти, чи варто взагалі вкладатись в інтеграцію саме з Horoshop, чи альтернатива зручніша.

Як прискорити інтеграцію без власного розробника

Якщо у вас немає бек-енд розробника, найняти фрілансера для написання інтеграції з нуля коштує від 500 USD і займає 2–3 тижні. Альтернатива — використати готові no-code сервіси або AI-інструменти, які вже мають коннектор до Horoshop.

Наприклад, Revenza для Horoshop підключається до магазину за тим самим API-юзером, який ви створили вище, і автоматично пише SEO-описи, метатеги та alt-тексти для зображень. Ліміти 100 req/hour обходяться на стороні сервісу — ви про них взагалі не думаєте. Безкоштовний план дозволяє обробити перші 50 товарів і подивитись результат.

Це не реклама заради реклами: для більшості магазинів на 1000–5000 SKU власна інтеграція економічно невиправдана, готовий інструмент окуповується за перший місяць.

FAQ: короткі відповіді на часті питання

Чи можна підключити API на тарифі Start?

Ні. Horoshop API доступний тільки на Pro і B2B. На Start ендпоінти повертають 403 незалежно від налаштувань.

Чи є спосіб збільшити ліміт 100 запитів на годину?

Офіційно — через перехід на B2B-тариф або індивідуальну домовленість із саппортом. Неофіційних обходів через кілька юзерів не радимо: можна отримати бан акаунту.

Який формат відповіді API — JSON чи XML?

Основний формат — JSON. XML підтримується для імпорту через окремий ендпоінт фідів, але для більшості інтеграцій зручніший саме JSON.

Чи можна через API керувати знижками і промокодами?

Частково. Знижки на товар (поле price_old) — так, повноцінні промокоди і акційні правила — обмежено, частина функцій доступна тільки через адмінку.

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

Реалізуйте моніторинг (наприклад, через UptimeRobot чи Healthchecks.io) на endpoint вашого скрипту і алерт у Telegram. Horoshop сам про падіння не повідомить.

Замість висновку

Horoshop API підключення — це не складно, якщо знати про лімит 100 req/hour, особливість mod_title і необхідність активації через саппорт. П'ять кроків, годину часу на тестовий запит, ще пару днів на batch-логіку — і ви маєте робочу інтеграцію, яка економить десятки годин ручної роботи на місяць.

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