Создание и управление

Обновлено: 2026-06-25 00:15 MSK

Полный жизненный цикл брони: создание, список за период, чтение, изменение и отмена. Все эндпоинты — под Bearer-токеном (см. Аутентификация).

Базовый путь: /api/rsv/admin/restaurants/{restaurantId}/reservations.

Метод	Путь	Назначение
`POST`	`/reservations`	Создать бронь
`GET`	`/reservations`	Список броней за период
`GET`	`/reservations/{reservationId}`	Получить бронь по ID
`PUT`	`/reservations/{reservationId}`	Изменить бронь
`PUT`	`/reservations/{reservationId}/cancel`	Отменить бронь

`POST /reservations` — создать бронь

Создаёт новое бронирование. Поведение зависит от типа токена:

Hostme / Partner — бронь создаётся от имени текущего пользователя (хоста/менеджера).
Vendor — бронь создаётся от имени внешнего приложения (POS, CRM и т.п.).

Тело — CreateReservationContract. Ниже — наиболее используемые поля верхнего уровня.

Основные поля

Поле	Тип	Описание
`reservationTime`	date-time	Дата и время визита (локальное время ресторана)
`groupSize`	integer	Количество гостей
`customerName`	string	Имя гостя
`phone`	string	Телефон
`email`	string	Email
`tableNumber`	string	Желаемый/назначенный стол
`specialRequests`	string	Пожелания гостя
`internalNotes`	string	Внутренние заметки (не для гостя)
`aboutGuestNotes`	string	Заметки о госте
`amount`	number	Сумма (например, предоплата/чек)
`estimatedTurnOverTime`	integer	Ожидаемое время оборота стола, мин
`source`	string	Источник брони (маркировка вашего канала)
`state`	string	Состояние/статус
`deliveryType`	string	Тип обслуживания (зал/доставка/самовывоз)
`paymentType`	string	Тип оплаты
`depositToken`	string	Токен депозита (если используется предоплата)
`eventId`	integer	ID события, если бронь на событие
`externalUserId`	string	Внешний ID гостя на вашей стороне
`createdBy`	string	Кто создал

Вложенные объекты

Поле	Объект	Содержит
`customerProfile`	`ProfileData`	Профиль гостя: `allergy[]`, `vegetarian`, `vip`, `handicapAccessible`, `anniversary`, `birthdate`, `companyName`, адрес доставки
`additionals`	`Additionals`	Признаки/пожелания: `highChair`, `vip`, `booth`, `highTop`, `babyChair`, `stroller`, `allergy`, `vegetarian`, `contactless`, `dontDisturb`, `event`, `eventTypes[]`, `customs[]`
`order`	`OnlineOrder`	Прикреплённый заказ: `orderItems[]` (`productId`, `amount`, `modifiers[]`), `note`, `total`, `subTotal`, `taxes`, `tips`
`referral`	`ReferralInfoContract`	Реферал/пригласивший

Пример (минимальный)

curl -X POST https://api.hostmeapp.com/api/rsv/admin/restaurants/123/reservations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reservationTime": "2026-07-01T19:00:00",
    "groupSize": 2,
    "customerName": "Иван Петров",
    "phone": "+79991234567",
    "email": "ivan@example.com",
    "specialRequests": "Столик у окна",
    "source": "partner-widget"
  }'

Пример (с профилем гостя и пожеланиями)

curl -X POST https://api.hostmeapp.com/api/rsv/admin/restaurants/123/reservations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reservationTime": "2026-07-01T20:30:00",
    "groupSize": 4,
    "customerName": "Мария Иванова",
    "phone": "+79990000000",
    "additionals": { "highChair": true, "vip": true },
    "customerProfile": { "allergy": ["орехи"], "vegetarian": true },
    "internalNotes": "Постоянный гость",
    "source": "partner-crm"
  }'

Ответ. При успехе возвращается созданная бронь в виде BookingContract (см. ниже). Документированные ошибки: 400 Bad Request, 404 Not Found (тело — ProblemDetails).

`GET /reservations` — список за период

Возвращает брони ресторана за период. Для запросов от внешних приложений (scope App) автоматически проставляется VendorAppId, и обязателен диапазон дат не более 60 дней.

Параметры

Параметр	Где	Тип	Описание
`restaurantId` *	path	integer	Идентификатор ресторана
`from`	query	date-time	Начало периода
`to`	query	date-time	Конец периода
`businessDateFrom`	query	date	Начало по «бизнес-дате»
`businessDateTo`	query	date	Конец по «бизнес-дате»
`pending`	query	boolean	Только ожидающие
`unviewed`	query	boolean	Только непросмотренные
`includeEvents`	query	boolean	Включать брони на события
`kind`	query	string	Тип брони
`status`	query	string	Фильтр по статусу
`VendorAppId`	query	string	Фильтр по приложению-источнику (для внешних приложений проставляется автоматически)

Пример

curl -G https://api.hostmeapp.com/api/rsv/admin/restaurants/123/reservations \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "from=2026-07-01T00:00:00" \
  --data-urlencode "to=2026-07-07T23:59:59"

Для внешних приложений диапазон обязателен и ограничен 60 днями — разбивайте длинные периоды на части.

`GET /reservations/{reservationId}` — получить бронь

Возвращает бронь по идентификатору. Ответ — BookingContract.

Параметр	Где	Тип
`restaurantId` *	path	integer
`reservationId` *	path	string

Ключевые поля ответа (`BookingContract`)

Поле	Тип	Описание
`customerProfile`	object	Профиль гостя (`ProfileData`)
`additionals`	object	Признаки/пожелания (`Additionals`)
`details`	object	Доп. детали: `cancelOptionName`, `cancelNote`, `cancelSource`, `paymentError`, `paymentLinkUrl`
`waiters[]`	array	Назначенные официанты (`id`, `fullName`, …)

Полный объект BookingContract обширен (профиль, заказ, чек, платёж). Здесь перечислены ключевые блоки; полную структуру смотрите в Swagger UI.

`PUT /reservations/{reservationId}` — изменить бронь

Обновляет существующую бронь (время, размер компании, стол и т.п.). Изменение фиксируется с привязкой к текущему пользователю (для аудита).

Параметр	Где	Тип
`restaurantId` *	path	integer
`reservationId` *	path	string

Тело запроса — те же поля, что и при создании (CreateReservationContract): присылайте изменяемые поля (reservationTime, groupSize, tableNumber, specialRequests и др.).

curl -X PUT https://api.hostmeapp.com/api/rsv/admin/restaurants/123/reservations/RID \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reservationTime": "2026-07-01T20:00:00", "groupSize": 3 }'

`PUT /reservations/{reservationId}/cancel` — отменить бронь

Отменяет бронь от имени персонала ресторана. Тело — CancelReservationContract.

Поле	Тип	Описание
`note`	string	Комментарий к отмене
`cancelOptionName`	string	Название причины отмены
`updatedBy`	string	Кто отменил
`origin`	string	Источник отмены
`doNotChargeFee`	boolean	Не списывать штраф/плату за отмену

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

curl -X PUT https://api.hostmeapp.com/api/rsv/admin/restaurants/123/reservations/RID/cancel \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "cancelOptionName": "Гость отменил", "note": "Перенос на другой день", "doNotChargeFee": true }'

Нужна модерация броней из внешних каналов? Используйте Запросы на бронь — заявку подтверждает хост, прежде чем она станет полноценной бронью.

Создание и управление

POST /reservations — создать бронь