Hosturm API

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

Початок

Базова адреса: https://api.hosturm.com/v1

Ключ видає Hosturm на ваш магазин. Передавайте його в кожному запиті:

curl -H "Authorization: Bearer ВАШ_КЛЮЧ" \
     https://api.hosturm.com/v1/products

Відповідь завжди JSON. Успіх: {"ok":true,"data":…}. Помилка: {"ok":false,"error":{"code":…,"message":…}}.

Запис даних — через POST. Захист сервера ріже методи PUT і DELETE, тому потрібний метод указуйте параметром ?_method=PUT при звичайному POST. Так само роблять Laravel і Google API. 
curl -X POST "https://api.hosturm.com/v1/products/101?_method=PUT" \
     -H "Authorization: Bearer ВАШ_КЛЮЧ" \
     -H "Content-Type: application/json" \
     -d '{"price": 199, "quantity": 12}'

Товари

МетодЩо робить
GET /productsсписок; параметри page, per_page (до 200), search, category_id, status
GET /products/{id}картка товару з описом і категоріями
POST /products/{id}?_method=PUTціна, акційна ціна, залишок, статус, модель, артикул, назва, опис
POST /products/bulk-stockмасове оновлення цін і залишків, до 500 позицій за раз

Масове оновлення — найчастіший сценарій

curl -X POST https://api.hosturm.com/v1/products/bulk-stock \
     -H "Authorization: Bearer ВАШ_КЛЮЧ" \
     -H "Content-Type: application/json" \
     -d '{"items":[{"id":101,"price":185,"quantity":50},
                   {"id":102,"quantity":30}]}'

У відповіді — скільки оновлено, скільки не вдалося і чому.

Замовлення

МетодЩо робить
GET /ordersсписок; параметри status_id, date_from, date_to, page, per_page
GET /orders/{id}замовлення з позиціями, підсумками, доставкою й оплатою
POST /orders/{id}/status?_method=PUTзмінити статус: {"status_id":3,"comment":"…","notify":true}
GET /order-statusesдовідник статусів магазину

Каталог і клієнти

МетодЩо робить
GET /categoriesусі категорії з деревом, прапорцями «у меню» й «активна»
POST /categories/{id}?_method=PUTназва, опис, показ у меню, порядок, статус
GET /customersсписок із пошуком за іменем, поштою, телефоном
GET /customers/{id}картка з кількістю й сумою замовлень

Вітрина: сторінки, банери, головна, тема

МетодЩо робить
GET /pages · /pages/{id}інформаційні сторінки («Про нас», «Оплата і доставка»…)
POST /pages/{id}?_method=PUTзаголовок, текст, meta, показ у підвалі, порядок
GET /banners · /banners/{id}банери й слайди головної
POST /banners/{id}?_method=PUTзаголовок, посилання, картинка, порядок слайдів
GET /blocksблоки головної сторінки з порядком
POST /blocks?_method=PUTпорядок блоків: {"blocks":[{"id":860,"sort":0}]}
GET /themeтема вітрини за замовчуванням і лого
POST /theme?_method=PUT{"default_theme":"dark"} — світла, темна або як у системі покупця

Службове

МетодЩо робить
GET /pingперевірка ключа
GET /shopназва магазину, валюта, мова, версія API
GET /healthстан шлюзу, без ключа

Вебхуки — магазин сам повідомляє вашу програму

Замість того щоб опитувати API, підпишіться на події: щойно в магазині з'явиться замовлення або зміниться його статус, ми надішлемо POST на вашу адресу.

МетодЩо робить
GET /webhooksсписок ваших підписок
POST /webhooksстворити: {"url":"https://ваш-сервер/hook","events":["order.created","order.status"]}
POST /webhooks/{id}?_method=DELETEвидалити підписку

Як перевірити, що виклик справді від нас

Кожен виклик підписаний. У заголовку X-HB-Signature — HMAC-SHA256 від тіла запиту з вашим секретом (він показується один раз при створенні підписки). Перевірка на PHP:

$body = file_get_contents('php://input');
$mine = hash_hmac('sha256', $body, $secret);
if (!hash_equals($mine, $_SERVER['HTTP_X_HB_SIGNATURE'] ?? '')) {
    http_response_code(403); exit;
}

Що приходить

{
  "event": "order.created",
  "sent_at": "2026-09-02T11:02:30+00:00",
  "data": {
    "order_id": 2, "status_id": 1, "status": "В очікуванні",
    "total": 185, "currency": "UAH",
    "customer": {"name":"…","email":"…","phone":"…"},
    "shipping": {"method":"Нова Пошта","city":"Київ","address":"…"},
    "payment":  {"method":"Накладений платіж"},
    "items": [{"product_id":101,"name":"…","quantity":1,"price":185,"total":185}]
  }
}

Відповідайте кодом 2xx. Якщо ваш сервер недоступний, ми повторимо: через 1 хв, 5 хв, 30 хв, 2 год і 6 год — усього до шести спроб.

Ліміти й помилки

За замовчуванням 120 запитів за хвилину на ключ. Поточний стан — у заголовках X-RateLimit-Limit і X-RateLimit-Remaining. При перевищенні приходить 429 і Retry-After: 60.

КодКоли
401немає заголовка з ключем або ключ не знайдено
403ключ вимкнено або він лише для читання
404невідомий метод або запис не знайдено
422неправильні дані — у відповіді вказано поле
429перевищено ліміт запитів
502магазин тимчасово не відповідає

Безпека

Питання — help.hosturm.com