Для разработчиков · API v1

Подключите BloomHub к вашей системе

Читайте каталог, карточки букетов, остатки по точкам и сводку заказов через отдельный ключ с выбранными правами.

Доступ только при действующем Энтерпрайз

Каждый запрос проверяет текущий тариф и срок оплаты. После истечения или понижения запросы блокируются с 403; пробный доступ и льготный период CRM этого не обходят. Бессрочно выданный Энтерпрайз остаётся действующим. При продлении неотозванный ключ снова работает до своего срока. Отозванные ключи не восстанавливаются.

Быстрое подключение

Войдите владельцем: Настройки → API. Создайте подключение, выберите разделы, точку и срок 30, 90 или 365 дней.
Сохраните полный ключ: повторно увидеть его нельзя. В базе хранится хеш. До 20 действующих ключей и 100 записей истории на магазин.
Передавайте ключ только с вашего сервера в заголовке Authorization: Bearer. Сессия сотрудника не заменяет внешний ключ.
Проверьте /me, затем получите ID точек через /locations.

curl -H "Authorization: Bearer $BLOOMHUB_API_KEY" "https://bloomhub.ru/api/v1/me"

Базовый адрес: https://bloomhub.ru/api/v1. BLOOMHUB_API_KEY — переменная окружения вашего сервера, содержащая созданный ключ.

Методы чтения

GET /me

Проверка ключа, разрешения и валюта

Любой действующий ключ

GET /locations

Доступные точки магазина

Любой действующий ключ

GET /products

Активные товары и розничные цены

catalog:read

GET /recipes

Активные рецепты: карточки букетов и композиции

catalog:read

GET /stock

Физический остаток, резерв и свободное количество на точке

stock:read

GET /orders

Сводка заказов и состав

orders:read

GET /orders/{id}

Один заказ и состав по ID

orders:read

В v1 пока нет создания и изменения заказов, клиентов, оплаты, возвратов, фискализации или списания склада. /orders возвращает суммы, статусы и состав; телефоны, адреса, комментарии клиентов, банковские реквизиты и себестоимость не передаются.

Точки, остатки и цены

У /stock укажите locationId, если ключ не закреплён за точкой. physicalStock — весь физический остаток на точке; reservedStock — занято; freeStock = physicalStock − reservedStock. Резерв не добавляется к наличию. Отрицательные значения сохраняются. При trackStock=false это услуга или позиция без складского ограничения; количество не определяет её доступность.

Ключ одной точки не читает остатки и заказы другой. /products с ограничением точки отдаёт товары с учётной записью на этой точке. /recipes — общие активные карточки рецептов; их наличие, количество готовых букетов и возможность сборки здесь не рассчитываются. Для режимов «можем собрать», «готовая витрина», «оба» используйте соответствующий специализированный каталог интеграции.

Цены sellPrice, unitPrice и суммы заказов — в основных денежных единицах валюты магазина (например, рублях). Код currency доступен в /me. У товаров передаётся базовая розничная цена; индивидуальные цены вариантов и точек в этом контракте не представлены.

Пагинация и обновления

/products, /recipes, /stock и /orders принимают page (от 1 до 10000), limit (1–100, по умолчанию 50), locationId и updatedAfter в ISO 8601 с часовым поясом. Ответ: items и pagination с page, limit, hasMore. Продолжайте загрузку, пока hasMore=true; не считайте одну страницу полным каталогом. /locations возвращает items без пагинации.

Списки упорядочены по ID; данные могут меняться между запросами. updatedAfter включает границу, поэтому сохраняйте объекты по ID без дублей. Для удаления неактивных или архивных карточек выполняйте периодическую полную сверку: отдельной ленты удалений в v1 нет. Заказы содержат items со строками состава, /orders/ID возвращает объект order.

Ошибки и лимиты

60 запросов в минуту на ключ. При 429 соблюдайте Retry-After. Не запускайте частый опрос из каждой вкладки браузера.

400 — проверьте параметры и обязательный locationId для остатков.
401 — ключ неверен, истёк, отозван либо выдавший владелец отключён или сменил роль.
403 — тариф не действует, нет разрешения или запрошена чужая точка.
404 — объект недоступен в области этого ключа.
503 и сетевые ошибки — повторите позже с увеличением паузы.

Ошибки прикладного контракта: error.code и error.message; также может присутствовать message. Для диагностики сохраняйте HTTP-статус и тело ошибки без заголовка авторизации.

Ключи и уведомления

Не вставляйте ключ в URL, клиентский JavaScript или мобильное приложение. Для каждого сервиса создавайте отдельный ключ. При утечке отзовите его в настройках и создайте новый. Смена ключа не меняет остатки и заказы.

Вебхуки — отдельный модуль с выбором событий и журналом доставки. Внутренние JWT-маршруты CRM, партнёрские API и административная Swagger-документация не входят в этот контракт v1.

Обновлено 2026-10-21.