Столы и залы

Эта группа эндпоинтов описывает физическую структуру ресторана: залы (floors), зоны (areas), столы (tables) и их текущее состояние в зале (свободен/занят/бронь). Партнёру это нужно, чтобы прочитать карту посадки, узнать вместимость и статусы столов в реальном времени, а также построить план зала.

Все эндпоинты — под Bearer-токеном (см. Аутентификация). Базовый путь управления столами: /api/tm/admin/restaurants/{restaurantId}.

Важно про термины. В Hostme «зал» (floor) — это отдельная карта посадки, у него есть floorId, имя и опциональная фоновая карта. «Зона» (area) — текстовая группировка столов внутри зала (например «Терраса», «У окна»). У стола поля area и привязка к залу.

GET /tables — список столов

Возвращает все столы ресторана с их вместимостью, зоной, тегами и правилами доступности (для брони и для листа ожидания). Это основной справочник столов для партнёрской интеграции.

Ключевые поля стола (TableContract)

Объект доступности (TableAvailabilityContract)

Одинаковая структура у reservability и waitability:

Каждый элемент hours содержит weekDay (число дня недели) и массив интервалов time с полями open / close (формат date-span, время от полуночи) и опциональным name.

Пример

curl -G https://api.hostmeapp.com/api/tm/admin/restaurants/123/tables \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "includeEvents=false"

GET /floorareas — сводка по зонам

Возвращает агрегированную статистику по каждой зоне (area) внутри каждого зала: сколько столов и мест всего, и сколько из них доступно онлайн. Удобно для дашбордов вместимости.

Поля ответа (FloorAreaContract)

curl https://api.hostmeapp.com/api/tm/admin/restaurants/123/floorareas \
  -H "Authorization: Bearer $TOKEN"

GET /floors — список залов

Возвращает залы ресторана с агрегатами по столам и местам. Параметры includeOffline и includeEvents управляют включением выключенных залов и залов событий.

Поля ответа (FloorInfoContract)

curl -G https://api.hostmeapp.com/api/tm/admin/restaurants/123/floors \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "includeOffline=false"

GET /floors/{floorId} — один зал

Возвращает данные конкретного зала по floorId (имя, карта/план, флаг offline). Используйте для подгрузки фоновой схемы зала.

Точная схема успешного ответа (200) в спецификации не зафиксирована. По структуре зала ориентируйтесь на FloorContract (см. раздел «Управление залами» ниже): floorId, name, map, floorUrl, isOffline.

GET /tables/monitors — состояние столов в реальном времени

Возвращает «снимок» зала: открыт ли ресторан и текущее состояние каждого стола (свободен, занят, бронь и т.п.), включая привязанного гостя, официантов и тайминги посадки. Это основной эндпоинт для отображения живой карты зала.

Структура ответа (RestaurantState)

Поля стола-монитора (TableMonitorContract)

Статусы стола (TableStatus)

Поле status — целочисленный enum со значениями 0…4. Точные подписи к числам в спецификации не зафиксированы; ориентируйтесь на текстовое поле state как на человекочитаемое состояние, а status используйте как стабильный машинный код. Не зашивайте смысл чисел жёстко — сверяйтесь с state.

curl -G https://api.hostmeapp.com/api/tm/admin/restaurants/123/tables/monitors \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "Time=2026-07-01T19:00:00" \
  --data-urlencode "WithNextSlot=true"

GET /tables/timeline — таймлайн занятости

Возвращает снимки состояния зала по ходу дня — для построения временной шкалы загрузки столов. Помимо состояния каждого стола включает агрегаты по гостям (посажено, ожидает, забронировано) и прогресс-бары оборота.

Структура ответа (FloorStateTimeline)

Каждый FloorTablesSnapshot содержит время (dateTime, timestamp, shiftDate), агрегаты (tablesCount, busyTablesCount, groupTotalMembers, seatedMembersCount, reservationMembersCount, waitingMembersCount) и массив monitors (TableTimelineContract) с тем же набором статусов/таймингов, что и в /tables/monitors, плюс прогресс-бары стола (tableProgressBar) и карточки (cardProgressBar).

curl -G https://api.hostmeapp.com/api/tm/admin/restaurants/123/tables/timeline \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "Date=2026-07-01"

Пересчёт таймлайна можно инициировать вручную: POST /tables/timeline/recalculate (без тела).

GET /tables/settings — настройки столов

Возвращает правила комбинирования и блокировок столов. Эти настройки влияют на то, как система подбирает столы под бронь. Чтение — GET, изменение — PUT с телом TablesSettingsContract.

Поля настроек (TablesSettingsContract, для PUT)

curl https://api.hostmeapp.com/api/tm/admin/restaurants/123/tables/settings \
  -H "Authorization: Bearer $TOKEN"

PUT /tables/state — сменить состояние стола

Меняет состояние брони/посадки за столом (например, перевести гостя в «занят», «завершён» и т.п.). Тело — ChangeTableStateContract.

Ответ — обновлённая бронь (BookingContract) с актуальными статусом и таймингами.

curl -X PUT https://api.hostmeapp.com/api/tm/admin/restaurants/123/tables/state \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "bookingId": "ABC_ID", "state": "Seated" }'

Освобождение стола. Отдельно есть PUT /tables/{bookingId}/release (освободить стол по брони) и POST /tables/release (массовое освобождение). Посадка/назначение стола брони — через PUT /seat/{registrationId} (тело RegisterAtTableContract). Эти операции относятся к работе хоста в зале; см. также Бронирования.

Управление залами (CRUD) — обзор

Создание, изменение и удаление залов. Партнёру эти операции нужны редко (структуру обычно ведёт персонал ресторана), поэтому ниже — кратко.

Тело создания/изменения — FloorContract:

curl -X POST https://api.hostmeapp.com/api/tm/admin/restaurants/123/floors \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Терраса", "isOffline": false }'

Также доступен GET /merge?ids=... — служебная операция объединения столов; для типовой партнёрской интеграции не требуется.

POST /floor-plan/image — план зала по фотографии

Принимает фотографию плана зала (уменьшенный JPEG, ≤1024px по длинной стороне, в Base64) и возвращает сгенерированный план в формате PlanDSL (JSON). Распознавание выполняет двухпроходная vision-модель Gemini 2.5 Flash с автоматическим запасным провайдером (OpenRouter) при исчерпании квоты. Путь: /api/restaurants/{restaurantId}/floor-plan/image.

Тело запроса (FloorPlanFromImageRequest)

Ответ (FloorPlanFromImageResponse)

curl -X POST https://api.hostmeapp.com/api/restaurants/123/floor-plan/image \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "imageBase64": "/9j/4AAQSkZJRg...", "contentType": "image/jpeg" }'

Клиент сам уменьшает изображение до ≤1024px перед отправкой. Полученный planDSL можно сохранить в поле map зала (FloorContract).

Общие правила (заголовки, формат ошибок ProblemDetails, коды ответов) — в разделах Соглашения и Ошибки. Жизненный цикл броней за столами — в Бронированиях.