API Solar Catalog: як синхронізувати ціни, залишки й замовлення з вашою обліковою системою

Якщо товарів сотні, а ціни й залишки змінюються щодня, вести їх вручну в кількох місцях незручно й ризиковано. У Solar Catalog є два API: для продавців (роздрібних магазинів) і для постачальників (оптовиків). Через них облікова система сама оновлює каталог, а про нові запити й замовлення ваш сервер дізнається одразу. Нижче: що вміє кожне API, як почати і на що звернути увагу.

Чи потрібне вам API

Не завжди. Якщо у вас уже є YML, XML, CSV чи XLSX-прайс за посиланням, достатньо підключити його в кабінеті: каталог сам забиратиме оновлення за розкладом. API потрібне, коли:

• ціни й залишки мають оновлюватися одразу, а не за розкладом;
• ви хочете автоматично відповідати на запити на прорахунок чи обробляти замовлення у своїй системі;
• потрібно отримувати події (вебхуки) про нові запити, оплати чи замовлення дилерів;
• розробник уже інтегрує ваш облік з іншими майданчиками й хоче так само підключити Solar Catalog.

Два API: для продавців і для постачальників

Запити йдуть на https://solar-catalog.com.ua/api/seller/v1 і https://solar-catalog.com.ua/api/supplier/v1 відповідно. Документація відкрита, без реєстрації, українською; до неї є файли OpenAPI і колекції Postman.

Крок 1. Ключ доступу

Продавець створює ключ у кабінеті в розділі «Інтеграції (API)», постачальник у розділі API свого кабінету. Для ключа обираєте:

• назву, щоб потім розуміти, яка система ним користується;
• права: наприклад, лише ціни й наявність, або ще й запити на прорахунок, платежі чи вебхуки. Давайте інтеграції лише ті права, які їй потрібні;
• строк дії: безстроково, 30, 90 чи 365 днів.

Ключ показується один раз, збережіть його в надійному місці. Його передають у кожному запиті заголовком Authorization: Bearer ВАШ_КЛЮЧ.

Крок 2. Оновити ціни й наявність

Продавець оновлює до 1000 товарів одним запитом за артикулами:

PATCH https://solar-catalog.com.ua/api/seller/v1/offers
Authorization: Bearer ВАШ_КЛЮЧ
Content-Type: application/json

{
  "items": [
    {
      "sku": "DEYE-SUN-6K-SG05LP1",
      "price": { "amount": 41200, "currency": "UAH" },
      "availability": "in_stock",
      "stock_quantity": 3
    },
    {
      "sku": "PYLONTECH-US5000",
      "availability": "on_order",
      "expected_at": "2026-11-20"
    }
  ]
}

Ціну можна передавати в гривнях або доларах, покупець бачить гривні за поточним курсом. Наявність: in_stock, on_order, out_of_stock або on_request.

Постачальник оновлює залишки по складах, до 5000 рядків за раз; номер складу береться із запиту GET /warehouses:

PATCH https://solar-catalog.com.ua/api/supplier/v1/stock
Authorization: Bearer ВАШ_КЛЮЧ
Content-Type: application/json

{
  "items": [
    { "sku": "SE-G5.1-PRO", "warehouse": 12, "quantity": 40 }
  ]
}

Для великого каталогу є пакетні запити через чергу: продавець створює чи оновлює до 500 товарів, постачальник до 1000 позицій за раз, а результат перевіряється окремим запитом за номером завдання.

Крок 3. Вебхуки: події без опитування

Щоб не перевіряти API щохвилини, підпишіться на події, і Solar Catalog сам надішле їх на адресу вашого сервера.

Події для продавця: новий запит на прорахунок, покупець прийняв вашу пропозицію (разом із його контактами), запит закрито, перевірено притриману ціну, події оплат (авторизовано, оплачено, помилка, скасовано, повернено), постачальник підтвердив, відправив чи відхилив ваше замовлення.

Події для постачальника: нова заявка дилера, нове замовлення, замовлення скасовано, дилер повідомив про оплату, позиція чекає підтвердження різкої зміни ціни.

Кожен вебхук підписаний: у заголовку X-Solar-Signature приходить час і підпис HMAC-SHA256 від рядка «час.тіло запиту» вашим секретом. Перевірка на PHP:

[$t, $v1] = sscanf($_SERVER['HTTP_X_SOLAR_SIGNATURE'], 't=%d,v1=%s');
$body = file_get_contents('php://input');
$ok = hash_equals(hash_hmac('sha256', $t . '.' . $body, $secret), $v1)
    && abs(time() - $t) < 300;

Якщо ваш сервер не відповів, доставка повторюється через 1 хв, 5 хв, 30 хв, 2, 6 і 12 годин. Адреса вебхука має бути HTTPS.

Що варто знати перед інтеграцією

• Пробний запуск. Додайте ?dry_run=1 до будь-якого запиту на зміну: API перевірить дані й покаже, що змінилося б, нічого не зберігаючи.
• Без дублів. Заголовок Idempotency-Key у пакетних запитах захищає від подвійного запуску, якщо запит повторився через збій мережі.
• Ліміти на ключ: 120 запитів на читання і 60 на запис за хвилину, пакетних 10 за хвилину. Залишок видно в заголовках X-RateLimit-*.
• Помилки приходять у форматі RFC 9457 з поясненням українською й кодом помилки, у кожній відповіді є X-Request-Id для звернення в підтримку.
• Різка зміна ціни. Як і з прайсом, надто різку зміну ціни каталог притримує до перевірки, а покупці чи дилери бачать попередню.
• Версії. Після виходу нової версії стара працює ще 12 місяців, про завершення попереджаємо заголовками, листами й банером у кабінеті.

Часті питання

Скільки коштує API?

Окремої плати за API немає. Діють ті самі умови й ліміти, що й для вашого кабінету.

Чи можна підключити 1С чи BAS?

Так, через API або простіше: вивантажити з облікової системи прайс за посиланням і підключити його в кабінеті. У майстрі підключення прайсу є підказка для 1С і BAS.

Чи можна протестувати, нічого не зламавши?

Так: параметр dry_run=1 перевіряє запит без збереження, а для вебхука є тестова подія, яку можна надіслати на свою адресу.

Чи можна приймати роздрібні замовлення через API продавця?

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

Що почитати далі

• Як продавати на Solar Catalog: покрокова інструкція для магазину.
• Постачальникам: як знайти дилерів через Solar Catalog.