Разделы документации

API v1 · Справочник

Методы, параметры и ответы

Семь методов чтения. Схемы полей и примеры ответов согласованы с OpenAPI. Запросы выполняются вашим сервером; эта страница не принимает и не отправляет ваши ключи.

GET

/api/v1/me

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

Возвращает владельца области ключа, его права и валюту. Не принимает JWT сессии CRM. Разрешение: Любой действующий ключ.

Разрешение: Любой действующий ключ

Параметры запроса

Параметры не требуются.

Запрос

curl --fail-with-body --get 'https://bloomhub.ru/api/v1/me' \
  --header "Authorization: Bearer $BLOOMHUB_API_KEY" \
  --header 'Accept: application/json'

Успешный ответ · 200 OK

Ответ /me

{
  "apiVersion": 1,
  "tenantId": "00000000-0000-4000-8000-000000000001",
  "scopes": [
    "catalog:read",
    "stock:read",
    "orders:read"
  ],
  "locationId": null,
  "currency": "RUB"
}

Учебный пример. ID, суммы и названия показаны для иллюстрации.

Поля ответа

Поле	Тип	Описание
apiVersion	integer	Версия внешнего контракта; сейчас 1.
tenantId	string · uuid	ID магазина, которому принадлежит ключ.
scopes	string[]	Разрешения, выданные этому ключу.
locationId	string · uuid \| null	ID точки. null означает отсутствие ограничения/привязки, где это допускает объект.
currency	string	Код валюты магазина, например RUB. Денежные поля передаются в её основных единицах.

Ошибки:400 401 403 404 429 500 503

GET

/api/v1/locations

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

Возвращает все доступные активные точки без пагинации. Ключ одной точки видит только её. Разрешение: Любой действующий ключ.

Разрешение: Любой действующий ключ

Параметры запроса

Параметры не требуются.

Запрос

curl --fail-with-body --get 'https://bloomhub.ru/api/v1/locations' \
  --header "Authorization: Bearer $BLOOMHUB_API_KEY" \
  --header 'Accept: application/json'

Успешный ответ · 200 OK

Ответ /locations

{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000003",
      "name": "Учебный салон",
      "city": "Абакан",
      "address": null,
      "timezone": "Asia/Krasnoyarsk"
    }
  ]
}

Учебный пример. ID, суммы и названия показаны для иллюстрации.

Поля items[]

Поле	Тип	Описание
id	string · uuid	Устойчивый ID объекта. Сохраняйте его как строку; названия и короткие номера не заменяют ID.
name	string	Название объекта.
city	string \| null	Город либо null.
address	string \| null	Адрес салона либо null. Это адрес точки, не адрес клиента.
timezone	string	Часовой пояс точки, например Asia/Krasnoyarsk.

Ошибки:400 401 403 404 429 500 503

GET

/api/v1/products

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

Активные неархивные товары и базовые розничные цены. Наличие берите отдельно из /stock; варианты и цены по точкам не входят в этот DTO. Разрешение: catalog:read.

Разрешение: catalog:read

Параметры запроса

Параметр	Тип и значение	Правило
`page` query	`integer` По умолчанию: 1	Номер страницы. По умолчанию 1; предел 10000.
`limit` query	`integer` По умолчанию: 50	Объектов на странице: 1–100, по умолчанию 50.
`updatedAfter` query	`string · date-time`	Изменения с указанного момента ВКЛЮЧИТЕЛЬНО. ISO 8601 с часовым поясом; знак + кодируйте как %2B.
`locationId` query	`string · uuid`	ID активной точки. Если ключ закреплён за точкой, нельзя выбрать другую. Для /stock нужен, если у ключа нет своей точки. В /recipes не означает наличие на точке.

Запрос

curl --fail-with-body --get 'https://bloomhub.ru/api/v1/products?page=1&limit=50&locationId=00000000-0000-4000-8000-000000000003' \
  --header "Authorization: Bearer $BLOOMHUB_API_KEY" \
  --header 'Accept: application/json'

Успешный ответ · 200 OK

Ответ /products

{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000005",
      "name": "Учебная роза",
      "sku": "ROSE-001",
      "barcode": null,
      "sellPrice": 100,
      "unit": "шт",
      "image": null,
      "categoryId": "00000000-0000-4000-8000-000000000007",
      "trackStock": true,
      "updatedAt": "2026-10-21T03:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "hasMore": false
  }
}

Учебный пример. ID, суммы и названия показаны для иллюстрации.

Поля items[]

Поле	Тип	Описание
id	string · uuid	Устойчивый ID объекта. Сохраняйте его как строку; названия и короткие номера не заменяют ID.
name	string	Название объекта.
sku	string \| null	Артикул. Может отсутствовать.
barcode	string \| null	Штрихкод. Может отсутствовать.
sellPrice	number	Базовая розничная цена в основных единицах валюты магазина, например рублях.
unit	string	Единица измерения; количество может быть дробным.
image	string \| null	Ссылка на основное изображение либо null. Относительную ссылку разрешайте от https://bloomhub.ru.
categoryId	string · uuid \| null	ID категории товара либо null. Справочник категорий отдельным методом v1 не предоставляется.
trackStock	boolean	Ведётся ли количественный учёт. false означает, что остаток не определяет доступность услуги/позиции.
updatedAt	string · date-time	Момент последнего изменения объекта в ISO 8601 с часовым поясом.

pagination.page — текущая страница; limit — размер; hasMore — есть следующая. Продолжайте выгрузку, пока hasMore равно true. Алгоритм синхронизации

Ошибки:400 401 403 404 429 500 503

GET

/api/v1/recipes

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

Общие активные карточки букетов и композиций. Это каталог, а не расчёт наличия, готовой витрины или возможности сборки. Разрешение: catalog:read.

Разрешение: catalog:read

Параметры запроса

Параметр	Тип и значение	Правило
`page` query	`integer` По умолчанию: 1	Номер страницы. По умолчанию 1; предел 10000.
`limit` query	`integer` По умолчанию: 50	Объектов на странице: 1–100, по умолчанию 50.
`updatedAfter` query	`string · date-time`	Изменения с указанного момента ВКЛЮЧИТЕЛЬНО. ISO 8601 с часовым поясом; знак + кодируйте как %2B.
`locationId` query	`string · uuid`	ID активной точки. Если ключ закреплён за точкой, нельзя выбрать другую. Для /stock нужен, если у ключа нет своей точки. В /recipes не означает наличие на точке.

Запрос

curl --fail-with-body --get 'https://bloomhub.ru/api/v1/recipes?page=1&limit=50' \
  --header "Authorization: Bearer $BLOOMHUB_API_KEY" \
  --header 'Accept: application/json'

Успешный ответ · 200 OK

Ответ /recipes

{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000008",
      "name": "Учебный букет",
      "description": "Букет для примера интеграции",
      "sku": "BOUQUET-001",
      "sellPrice": 1200,
      "image": null,
      "photos": [],
      "video": null,
      "sectionId": null,
      "updatedAt": "2026-10-21T03:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "hasMore": false
  }
}

Учебный пример. ID, суммы и названия показаны для иллюстрации.

Поля items[]

Поле	Тип	Описание
id	string · uuid	Устойчивый ID объекта. Сохраняйте его как строку; названия и короткие номера не заменяют ID.
name	string	Название объекта.
description	string \| null	Публичное описание карточки рецепта.
sku	string \| null	Артикул. Может отсутствовать.
sellPrice	number	Базовая розничная цена в основных единицах валюты магазина, например рублях.
image	string \| null	Ссылка на основное изображение либо null. Относительную ссылку разрешайте от https://bloomhub.ru.
photos	string[]	Ссылки на дополнительные фотографии. Массив может быть пустым.
video	string \| null	Ссылка на видео карточки либо null.
sectionId	string · uuid \| null	ID раздела рецептов либо null. Справочник разделов не входит в v1.
updatedAt	string · date-time	Момент последнего изменения объекта в ISO 8601 с часовым поясом.

Ошибки:400 401 403 404 429 500 503

GET

/api/v1/stock

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

Физический остаток, резерв и свободное количество читаются отдельно для точки. Передайте locationId, если ключ не закреплён за точкой. Разрешение: stock:read.

Разрешение: stock:read

Параметры запроса

Параметр	Тип и значение	Правило
`page` query	`integer` По умолчанию: 1	Номер страницы. По умолчанию 1; предел 10000.
`limit` query	`integer` По умолчанию: 50	Объектов на странице: 1–100, по умолчанию 50.
`updatedAfter` query	`string · date-time`	Изменения с указанного момента ВКЛЮЧИТЕЛЬНО. ISO 8601 с часовым поясом; знак + кодируйте как %2B.
`locationId` query	`string · uuid`	ID активной точки. Если ключ закреплён за точкой, нельзя выбрать другую. Для /stock нужен, если у ключа нет своей точки. В /recipes не означает наличие на точке.

Запрос

curl --fail-with-body --get 'https://bloomhub.ru/api/v1/stock?page=1&limit=50&locationId=00000000-0000-4000-8000-000000000003' \
  --header "Authorization: Bearer $BLOOMHUB_API_KEY" \
  --header 'Accept: application/json'

Успешный ответ · 200 OK

Ответ /stock

{
  "items": [
    {
      "inventoryItemId": "00000000-0000-4000-8000-000000000004",
      "productId": "00000000-0000-4000-8000-000000000005",
      "variantId": null,
      "name": "Учебная роза",
      "unit": "шт",
      "locationId": "00000000-0000-4000-8000-000000000003",
      "physicalStock": 10,
      "reservedStock": 3,
      "freeStock": 7,
      "trackStock": true,
      "updatedAt": "2026-10-21T03:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "hasMore": false
  }
}

Учебный пример. ID, суммы и названия показаны для иллюстрации.

Поля items[]

Поле	Тип	Описание
inventoryItemId	string · uuid	ID учётной позиции склада; отличается от ID товара.
productId	string · uuid \| null	ID товара для связи с /products. Может отсутствовать у учётной позиции.
variantId	string · uuid \| null	ID варианта либо null. Отдельный справочник вариантов не входит в v1.
name	string	Название объекта.
unit	string	Единица измерения; количество может быть дробным.
locationId	string · uuid	ID точки. null означает отсутствие ограничения/привязки, где это допускает объект.
physicalStock	number	Весь физический остаток на точке. Резерв сюда повторно не прибавляется; значение может быть отрицательным.
reservedStock	number	Количество, занятое резервами на точке.
freeStock	number	physicalStock − reservedStock. Отрицательное значение не обнуляется: это дефицит относительно резервов.
trackStock	boolean	Ведётся ли количественный учёт. false означает, что остаток не определяет доступность услуги/позиции.
updatedAt	string · date-time	Момент последнего изменения объекта в ISO 8601 с часовым поясом.

Ошибки:400 401 403 404 429 500 503

GET

/api/v1/orders

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

Возвращает сводки обычных заказов и мгновенных кассовых продаж со строками состава. Персональные данные клиентов, история платежей и чеки не входят в ответ. Разрешение: orders:read.

Разрешение: orders:read

Параметры запроса

Параметр	Тип и значение	Правило
`page` query	`integer` По умолчанию: 1	Номер страницы. По умолчанию 1; предел 10000.
`limit` query	`integer` По умолчанию: 50	Объектов на странице: 1–100, по умолчанию 50.
`updatedAfter` query	`string · date-time`	Изменения с указанного момента ВКЛЮЧИТЕЛЬНО. ISO 8601 с часовым поясом; знак + кодируйте как %2B.
`locationId` query	`string · uuid`	ID активной точки. Если ключ закреплён за точкой, нельзя выбрать другую. Для /stock нужен, если у ключа нет своей точки. В /recipes не означает наличие на точке.

Запрос

curl --fail-with-body --get 'https://bloomhub.ru/api/v1/orders?page=1&limit=50&locationId=00000000-0000-4000-8000-000000000003' \
  --header "Authorization: Bearer $BLOOMHUB_API_KEY" \
  --header 'Accept: application/json'

Успешный ответ · 200 OK

Ответ /orders

{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000009",
      "orderNumber": "0042-A",
      "status": "NEW",
      "totalAmount": 1500,
      "paidAmount": 500,
      "isPosSale": false,
      "locationId": "00000000-0000-4000-8000-000000000003",
      "deliveryDate": "2026-10-22T05:00:00Z",
      "createdAt": "2026-10-21T03:00:00Z",
      "updatedAt": "2026-10-21T03:00:00Z",
      "items": [
        {
          "id": "00000000-0000-4000-8000-000000000013",
          "productId": "00000000-0000-4000-8000-000000000005",
          "recipeId": null,
          "variantId": null,
          "name": "Учебная роза",
          "quantity": 3,
          "unitPrice": 100,
          "total": 300
        },
        {
          "id": "00000000-0000-4000-8000-000000000014",
          "productId": null,
          "recipeId": "00000000-0000-4000-8000-000000000008",
          "variantId": null,
          "name": "Учебный букет",
          "quantity": 1,
          "unitPrice": 1200,
          "total": 1200
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "hasMore": false
  }
}

Учебный пример. ID, суммы и названия показаны для иллюстрации.

Поля items[]

Поле	Тип	Описание
id	string · uuid	Устойчивый ID объекта. Сохраняйте его как строку; названия и короткие номера не заменяют ID.
orderNumber	string \| null	Короткий номер для человека. Может отсутствовать или повторяться со временем; ключом интеграции служит id.
status	string	Текущее состояние заказа. Значение — строка; обрабатывайте также незнакомые состояния. Оно не подтверждает фискализацию.
totalAmount	number	Итоговая сумма заказа в валюте магазина. Используйте её, а не самостоятельную сумму строк: итог может учитывать скидки и доставку.
paidAmount	number	Записанная в CRM сумма оплат. Это не подтверждение печати чека или статуса ОФД.
isPosSale	boolean	true — мгновенная продажа через кассу; false — заказ на исполнение.
locationId	string · uuid \| null	ID точки. null означает отсутствие ограничения/привязки, где это допускает объект.
deliveryDate	string · date-time \| null	Время получения/доставки с часовым поясом либо null.
createdAt	string · date-time	Момент создания в ISO 8601.
updatedAt	string · date-time	Момент последнего изменения объекта в ISO 8601 с часовым поясом.
items	OrderItem[]	Строки состава заказа. Не включают персональные контакты, банковские реквизиты и себестоимость.

Поля строк состава · items[] внутри заказа

Поле	Тип	Описание
id	string · uuid	Устойчивый ID объекта. Сохраняйте его как строку; названия и короткие номера не заменяют ID.
productId	string · uuid \| null	ID товара для связи с /products. Может отсутствовать у учётной позиции.
recipeId	string · uuid \| null	ID рецепта для связи с /recipes либо null.
variantId	string · uuid \| null	ID варианта либо null. Отдельный справочник вариантов не входит в v1.
name	string	Название объекта.
quantity	number	Количество позиции. Возможно дробное значение.
unitPrice	number	Цена единицы в основных единицах валюты магазина.
total	number	Сумма строки в основных единицах валюты магазина.

Ошибки:400 401 403 404 429 500 503

GET

/api/v1/orders/{id}

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

Возвращает заказ по устойчивому UUID в области ключа. Короткий orderNumber не является идентификатором этого метода. Разрешение: orders:read.

Разрешение: orders:read

Параметры запроса

Параметр	Тип и значение	Правило
`id` path · обязателен	`string · uuid`	Устойчивый UUID заказа, не короткий номер.
`locationId` query	`string · uuid`	ID активной точки. Если ключ закреплён за точкой, нельзя выбрать другую. Для /stock нужен, если у ключа нет своей точки. В /recipes не означает наличие на точке.

Запрос

curl --fail-with-body --get 'https://bloomhub.ru/api/v1/orders/00000000-0000-4000-8000-000000000009' \
  --header "Authorization: Bearer $BLOOMHUB_API_KEY" \
  --header 'Accept: application/json'

Успешный ответ · 200 OK

Ответ /orders/{id}

{
  "order": {
    "id": "00000000-0000-4000-8000-000000000009",
    "orderNumber": "0042-A",
    "status": "NEW",
    "totalAmount": 1500,
    "paidAmount": 500,
    "isPosSale": false,
    "locationId": "00000000-0000-4000-8000-000000000003",
    "deliveryDate": "2026-10-22T05:00:00Z",
    "createdAt": "2026-10-21T03:00:00Z",
    "updatedAt": "2026-10-21T03:00:00Z",
    "items": [
      {
        "id": "00000000-0000-4000-8000-000000000013",
        "productId": "00000000-0000-4000-8000-000000000005",
        "recipeId": null,
        "variantId": null,
        "name": "Учебная роза",
        "quantity": 3,
        "unitPrice": 100,
        "total": 300
      },
      {
        "id": "00000000-0000-4000-8000-000000000014",
        "productId": null,
        "recipeId": "00000000-0000-4000-8000-000000000008",
        "variantId": null,
        "name": "Учебный букет",
        "quantity": 1,
        "unitPrice": 1200,
        "total": 1200
      }
    ]
  }
}

Учебный пример. ID, суммы и названия показаны для иллюстрации.

Поля order

Поле	Тип	Описание
id	string · uuid	Устойчивый ID объекта. Сохраняйте его как строку; названия и короткие номера не заменяют ID.
orderNumber	string \| null	Короткий номер для человека. Может отсутствовать или повторяться со временем; ключом интеграции служит id.
status	string	Текущее состояние заказа. Значение — строка; обрабатывайте также незнакомые состояния. Оно не подтверждает фискализацию.
totalAmount	number	Итоговая сумма заказа в валюте магазина. Используйте её, а не самостоятельную сумму строк: итог может учитывать скидки и доставку.
paidAmount	number	Записанная в CRM сумма оплат. Это не подтверждение печати чека или статуса ОФД.
isPosSale	boolean	true — мгновенная продажа через кассу; false — заказ на исполнение.
locationId	string · uuid \| null	ID точки. null означает отсутствие ограничения/привязки, где это допускает объект.
deliveryDate	string · date-time \| null	Время получения/доставки с часовым поясом либо null.
createdAt	string · date-time	Момент создания в ISO 8601.
updatedAt	string · date-time	Момент последнего изменения объекта в ISO 8601 с часовым поясом.
items	OrderItem[]	Строки состава заказа. Не включают персональные контакты, банковские реквизиты и себестоимость.

Поля строк состава · items[] внутри заказа

Поле	Тип	Описание
id	string · uuid	Устойчивый ID объекта. Сохраняйте его как строку; названия и короткие номера не заменяют ID.
productId	string · uuid \| null	ID товара для связи с /products. Может отсутствовать у учётной позиции.
recipeId	string · uuid \| null	ID рецепта для связи с /recipes либо null.
variantId	string · uuid \| null	ID варианта либо null. Отдельный справочник вариантов не входит в v1.
name	string	Название объекта.
quantity	number	Количество позиции. Возможно дробное значение.
unitPrice	number	Цена единицы в основных единицах валюты магазина.
total	number	Сумма строки в основных единицах валюты магазина.

Ошибки:400 401 403 404 429 500 503