Бронирования: полное руководство

Бронь — центральная сущность. К ней привязаны гость, даты, деньги и все чаты. Разберём создание, редактирование, оплаты, скрытие и типичные ошибки.

1. Список и выбор броней

• Слева — объекты, сверху — лента броней выбранного объекта (GET /api/bookings?property_id=…&show_hidden=0/1).
• Кнопка-календарь 📅 — прыжок к сегодняшней или ближайшей будущей брони.
• Чекбокс «показать скрытые» (иконка-календарь с крестом на мобильном) — включает отменённые/тестовые.
• Карточка в ленте: гость, даты, источник (avito/sutochno/yandex/ostrovok/manual/telegram…), бейдж оплаты.

2. Поля карточки брони

guest_name / phone / email

Контакты гостя. Телефон кликабелен: позвонить, СМС, MAX, Telegram, WhatsApp, скопировать. С Avito/Суточно телефон появляется только после раскрытия площадкой

guest_count, special_requests

Число гостей и пожелания (поздний заезд, дети, цель поездки — часть подтягивается из системных сообщений Суточно/Яндекса)

check_in / check_out

Даты в формате ГГГГ-ММ-ДД. Пересечение по объекту запрещено — сервер вернёт 409

external_ref

Служебный ID источника: yandex-order-…, sutochno-order-…, avito-str-…, manual-…. По нему идёт дедупликация — повторная синхронизация не создаёт дубль

base_price / prepay_price

Полная стоимость и предоплата. Доплата = base − prepay (используется в шаблонах как {Сумма_Доплаты})

payment_status

unpaid, partial, paid, fully_paid, payment_required, deposit_required, cancelled

deposit_received / extra_paid / deposit_returned

Ручные флаги 0/1: залог получен, доплата получена, залог возвращён

chats[]

Привязанные чаты: платформа + external_chat_id + is_active. Кнопка ⚙️ «Управление каналами связи» — список, отвязка, ручная привязка Avito, запрос истории MAX-юзербота

3. Создание вручную

4. Оплаты: статусы и флаги

• Панель «💳 Оплаты»: смена payment_status (PATCH /api/booking/{id}/payment-status). Список допустимых значений валидируется.
• Чекбоксы залога/доплаты (PATCH /api/booking/{id}/flags): deposit_received, extra_paid, deposit_returned (последний виден после получения залога).
• Автоматика площадок: Суточно ставит partial/paid/unpaid из payed/precost/cost и cancelled из state=cancel или системного «бронь аннулирована»; Avito — из SafeDeposit. Но после ручных paid/payment_required/deposit_required/fully_paid/cancelled автоматика статус не перезаписывает — ваше решение главнее.
• Редактирование сумм/дат: PUT /api/booking/{id} (тоже с проверкой пересечений).

5. Скрытие броней

PATCH /api/booking/{id}/hidden {"hidden": true/false}. Скрытые исключаются из автосообщений, планировщика и опроса Суточно (экономия API-запросов). Удаление — DELETE /api/booking/{id} (безвозвратно, вместе с чатами).

6. API для интеграций

• GET /api/booking/{id} — карточка с чатами; GET /api/booking/{id}/messages — история; GET /api/booking/{id}/deeplinks — ссылки ботов.
• GET /api/v1/bookings/{id}/view — агрегат для экрана: бронь + объект + профиль + deeplinks + сообщения с разбором вложений + флаг contact_restricted.
• POST /api/booking/{id}/render-template — предпросмотр шаблона под бронь.