Хорошоп API: що вміє, на якому тарифі і як підключити

Коротка відповідь: Хорошоп API це JSON-інтерфейс, який працює на домені вашого магазину за адресою https://ваш-домен/api/ і дає змогу зовнішнім програмам читати й змінювати товари, замовлення, клієнтів, категорії та комплекти. За сторінкою тарифів horoshop.ua, API доступне з тарифу Pro, а на B2B до нього додається B2B API для груп покупців і рівнів цін. Для підключення в адмінці створюють окремого користувача, від імені якого програма отримує токен.

Більшості магазинів писати код під API не доводиться: CRM, облікові системи й сервіси доставки мають готові інтеграції, які налаштовуються без власного коду. Самостійна робота з ним потрібна, коли готового рішення немає, наприклад для власної синхронізації з постачальниками чи нестандартної аналітики. Нижче розібрано, що в API є, і як ним користуються на практиці.

Швидкий старт: як почати працювати з Horoshop API

1. Перевірте тариф і модуль API. API є в тарифах Pro і B2B (сторінка тарифів horoshop.ua). Окремого перемикача в адмінці немає: якщо будь-який запит повертає 409 «Api module is not available», модуль у магазині вимкнений, і ввімкнути його може тільки підтримка Хорошоп (чат в адмінці або support@horoshop.ua). Усі типові помилки розібрано в статті помилки Хорошоп API.
2. Створіть користувача для API: Налаштування → Адміни. Запам’ятайте поле «Логін». Для авторизації через API потрібен саме логін, а не email: в адмінку Хорошоп пускає і за email, а /api/auth/ відповідає, що користувача не знайдено.
3. Отримайте токен. Надішліть POST-запит із заголовком Content-Type: application/json на адресу https://ваш-домен/api/auth/. Токен має 32 символи і живе 600 секунд.
4. Викличте функцію. Токен передають у тілі кожного наступного запиту. Нижче приклад експорту каталогу: функція повертає ціни, залишки й артикул для показу на вітрині.

Авторизація: curl -X POST https://ваш-домен/api/auth/ -H 'Content-Type: application/json' -d '{"login":"api","password":"ваш-пароль"}'

Успішна відповідь має вигляд {"status":"OK","response":{"token":"3199c39700714eec4f6ada0b4242335b"}}. Якщо логін або пароль неправильні, status буде ERROR, а причина в response.message.

Експорт каталогу: curl -X POST https://ваш-домен/api/catalog/export/ -H 'Content-Type: application/json' -d '{"token":"ВАШ_ТОКЕН","offset":0,"limit":500}'

У відповіді масив товарів лежить у response.products. Один запит повертає не більше 500 товарів, тому великий каталог читають сторінками: збільшуйте offset на 500, поки не прийде статус EMPTY. Для вибірки офіційна документація описує параметри expr (розділ, артикул), includedParams і excludedParams. Для інтеграції з обліком дивіться також статтю про інтеграцію Хорошоп з 1С.

Які дані можна передавати через Хорошоп API?

Офіційна документація Хорошоп API ділить функції на кілька розділів. Ось що в них є станом на жовтень 2026 року:

Окремо є вебхуки, про них нижче. Повний перелік параметрів кожної функції, приклади запитів і можливі помилки описані в документації, посилання на неї є в довідці Хорошоп і в кінці статті.

Як працює запит до API: логін, токен, відповідь

1. Створіть користувача для API в адмінці: Налаштування → Адміни. Логін і пароль цього користувача програма використовує для входу. Краще окремий користувач на кожну інтеграцію, щоб за потреби вимкнути одну, не чіпаючи решту.
2. Отримайте токен. Програма надсилає логін і пароль на адресу https://ваш-домен/api/auth/ і отримує токен довжиною 32 символи. За документацією, токен живе 600 секунд, тож довгі синхронізації мають уміти оновлювати його.
3. Викликайте функції. Кожен запит іде на адресу https://ваш-домен/api/назва-функції/ і містить токен. Хорошоп наполегливо радить JSON POST із заголовком Content-type: application/json і кодуванням UTF-8 без BOM. Приклади GET-запитів із документації прибрали як небезпечні, бо їх можна перехопити.
4. Розберіть відповідь. Вона завжди у форматі JSON із полем status: OK означає успіх, EMPTY немає даних (наприклад, сторінки експорту скінчилися), UNAUTHORIZED потрібна повторна авторизація, ERROR чи HTTP_ERROR помилка з поясненням у response.message.

Що таке вебхуки Хорошоп і навіщо вони?

Вебхук це повідомлення, яке Хорошоп сам надсилає на адресу вашої системи, коли на сайті щось сталося. Без нього CRM мусила б щохвилини питати «чи є нові замовлення», навантажуючи і свій сервер, і сайт. За документацією, підписатися можна на такі події:

• оформлення замовлення (order_created) і зміна його статусу (order_update);
• зміна статусу оплати замовлення (order_paid);
• реєстрація користувача (user_signup) і зміна його даних (user_update);
• запит зворотного дзвінка (request_call_me);
• новий коментар на сайті (comments_created).

Дві деталі, які варто знати розробнику. Черга вебхуків відправляється планувальником раз на 5 хвилин, тому затримка в кілька хвилин нормальна. Якщо ваша система відповіла кодом, відмінним від 2xx, Хорошоп повторить спробу приблизно через 10 хвилин, до 10 разів. Події про зміну статусу замовлення і даних клієнта, за журналом оновлень API, з’явилися в грудні 2025 року, про новий коментар у лютому 2026.

Коли магазину справді потрібне API, а коли досить готової інтеграції?

• CRM і облік. Якщо ваша CRM є на сторінці інтеграцій Хорошоп, підключайте її готову інтеграцію: її підтримує розробник CRM. Огляд таких систем є у статті яку CRM підключити до Хорошоп, а про облік у статті про інтеграцію з 1С.
• Прайси постачальників. Якщо постачальників кілька і їхні файли треба оновлювати щодня, часто вистачає вбудованого імпорту з функцією «Постачальник». API потрібне, коли оновлення має йти автоматично за розкладом. Схему розібрано в статті про дропшипінг на Хорошоп.
• Прості передачі даних. Нове замовлення в Google Таблицю чи новий клієнт у розсилку зручніше зробити через Zapier без коду.
• Власна аналітика й нестандартні задачі. Тут API і є правильним інструментом, але закладіть бюджет на розробника і на підтримку інтеграції після оновлень.

Як widgetis використовує Хорошоп API

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

• Експорт товарів щоночі оновлює ціни, наявність і артикули товарів у нашій копії каталогу. Для віджета 1+1=3 з активною акцією каталог додатково оновлюється чотири рази на день, щоб товар, який розпродали вдень, перестав потрапляти в подарунок за кілька годин, а не наступного дня. Рекомендації в кошику теж беруть з API свіжу ціну й наявність, щоб не пропонувати те, чого вже немає.
• Експорт користувачів потрібен 1+1=3, щоб покупці з окремих груп цін, наприклад гуртові чи дропшипери, не отримували товар у подарунок.

Два спостереження з нашої практики, які стануть у пригоді розробнику. Один запит експорту каталогу повертає до 500 товарів, тому великий каталог читається десятками запитів. Хорошоп обмежує кількість запитів за годину і на перевищення відповідає помилкою з кодом 429 у тілі відповіді, тож синхронізація має вміти чекати й продовжувати з того самого місця.

Доступ до API це ключ від даних магазину. Давайте його окремому користувачу під конкретну інтеграцію і лише тим, хто пояснив, що саме читатиме і що записуватиме.

Джерела

• Повна документація Хорошоп API
• Хорошоп: тарифи і функції кожного плану
• Хорошоп: інтеграції і Хорошоп API