Бронирования через API

Создание, получение и отмена бронирований. Верификация телефона, статусы и ограничения

API GuestMe позволяет создавать бронирования от имени гостей, отслеживать их статус и отменять при необходимости. Перед созданием бронирования может потребоваться верификация телефонного номера.

Верификация телефона

Если у ресторана включена верификация (свойство phoneConfirmationEnabled = true), перед созданием бронирования необходимо подтвердить номер телефона гостя.

Шаг 1: Запрос кода

POST /api/v1/external/restaurant/{id}/confirmation/code/request

Отправьте номер телефона в формате +79998887766. В ответ придёт timeLeft — количество секунд до возможности повторного запроса.

Шаг 2: Проверка кода

POST /api/v1/external/restaurant/confirmation/code/verify

Отправьте номер телефона и полученный код. При успехе — статус 200.

Формат телефона

Используйте международный формат с кодом страны. Рекомендуется валидировать номер с помощью библиотеки Google libphonenumber перед отправкой.

Создание бронирования

POST /api/v1/external/restaurant/{id}/booking — создание нового бронирования.

Обязательные поля

Поле	Тип	Пример	Описание
`firstName`	`string`	`"Иван"`	Имя гостя
`phone`	`string`	`"+79994656464"`	Телефон гостя
`date`	`date-time`	`"2025-06-15T19:00:00Z"`	Дата и время бронирования
`persons`	`int32`	`2`	Количество гостей

Необязательные поля

Поле	Тип	Описание
`lastName`	`string`	Фамилия гостя
`comment`	`string`	Комментарий к бронированию
`meta.promo`	`string`	Промокод

Получение бронирования

GET /api/v1/external/booking/{id} — получение информации о бронировании по его ID.

Отмена бронирования

DELETE /api/v1/external/booking/{id} — отмена бронирования.

Ограничение отмены

Отменить можно только бронирования в статусе CREATED или SENT. Попытка отменить бронирование в другом статусе вернёт ошибку booking_incompatible_state.

Статусы бронирования

Бронирование проходит через несколько статусов в процессе обработки:

Статус	Описание
`CREATED`	Бронирование создано, ожидает отправки в ресторан
`SENT`	Отправлено в POS-систему ресторана
`ACCEPTED`	Подтверждено рестораном
`DECLINED`	Отклонено рестораном
`IN_PROGRESS`	Гость находится в ресторане
`CLOSED`	Визит завершён
`CANCELING`	Запрос на отмену отправлен
`CANCELED`	Бронирование отменено
`PATCHING`	Обновление данных в процессе
`ERROR`	Ошибка обработки

Ограничения

Дата бронирования должна быть в будущем и в пределах расписания ресторана
На один номер телефона допускается только одно активное бронирование в одном ресторане
Ресторан должен иметь guestAcquisitionChannelEnabled = true
Бронирование возможно только в рабочие часы приёма бронирований (тип расписания BOOKING)

Дублирование бронирований

При попытке создать второе активное бронирование на тот же номер телефона в том же ресторане API вернёт ошибку guest_have_not_closed_booking.