Интеграция 1С-Битрикс с системой бронирования Shelter

Интеграция 1С-Битрикс с системой бронирования Shelter

Shelter — отечественная PMS для хостелов, мини-отелей и апарт-комплексов. Аудитория — небольшие объекты, которым дорого внедрять тяжёлые PMS, но нужна нормальная автоматизация. Стандартная проблема: сайт на Битрикс работает сам по себе, Shelter — сам по себе. Менеджер дважды вводит данные гостя, не видит сводной загрузки по каналам и узнаёт об отмене из Shelter только когда случайно открывает вкладку.

API Shelter

Shelter предоставляет REST API. Базовый URL: https://api.shelter-pms.ru/v2/. Авторизация — Bearer-токен в заголовке. Ключевые эндпоинты:

• GET /rooms — список номеров с типами
• GET /availability — доступность по диапазону дат
• GET /tariffs — тарифные планы
• POST /bookings — создание брони
• PUT /bookings/{id} — изменение брони
• GET /bookings/{id} — статус брони

Лимит запросов: 120 в минуту. При синхронизации крупного объекта (50+ номеров) это нужно учитывать — пакетные запросы предпочтительнее одиночных.

Синхронизация номерного фонда

При первом запуске (или по требованию) загружаем полный справочник номеров из Shelter и создаём соответствующие элементы инфоблока в Битрикс. Маппинг хранится в таблице bl_shelter_room_map:

CREATE TABLE bl_shelter_room_map (
    bitrix_element_id INT NOT NULL,
    shelter_room_id   VARCHAR(64) NOT NULL,
    room_type         VARCHAR(64),
    synced_at         TIMESTAMP DEFAULT NOW(),
    PRIMARY KEY (bitrix_element_id)
);

Это позволяет при синхронизации доступности обращаться к Shelter по shelter_room_id, а на сайте показывать данные через стандартный инфоблок Битрикс.

Получение доступности

Агент запрашивает GET /availability?date_from=YYYY-MM-DD&date_to=YYYY-MM-DD раз в 15 минут. Ответ — матрица «дата × тип номера × количество свободных мест».

function SyncShelterAvailability(): string
{
    $client = new ShelterApiClient(SHELTER_TOKEN);
    $dateFrom = (new DateTime())->format('Y-m-d');
    $dateTo = (new DateTime('+90 days'))->format('Y-m-d');

    $data = $client->get('/availability', [
        'date_from' => $dateFrom,
        'date_to'   => $dateTo,
    ]);

    foreach ($data['availability'] as $row) {
        \Bitrix\Main\Application::getConnection()->queryExecute(
            "INSERT INTO bl_shelter_availability (room_type_id, date, qty)
             VALUES (?, ?, ?)
             ON CONFLICT (room_type_id, date) DO UPDATE SET qty = EXCLUDED.qty, synced_at = NOW()",
            [$row['room_type_id'], $row['date'], $row['available']]
        );
    }

    return __FUNCTION__ . '();';
}

Создание и отмена броней

При подтверждении оплаты в Битрикс отправляем бронь в Shelter. Shelter возвращает booking_id, который сохраняем в UF-поле заказа UF_SHELTER_BOOKING_ID.

При отмене заказа в Битрикс (событие OnSaleOrderCanceled или смена статуса через обработчик) делаем запрос PUT /bookings/{id} с полем status: cancelled. Если Shelter API недоступен в момент отмены — ставим задачу в очередь агента с повторными попытками.

Webhooks из Shelter

Shelter отправляет уведомления при изменении статуса брони в PMS (например, менеджер отменил бронь прямо в Shelter, минуя сайт). Настройка webhook — в разделе «Настройки → Интеграции» Shelter.

Обработчик верифицирует подпись (X-Shelter-Signature), определяет тип события и обновляет заказ в Битрикс. Критичное событие — booking.cancelled: нужно освободить дату в локальном кэше и уведомить гостя по email через \Bitrix\Main\Mail\Event::send.

Передача гостевой информации

Shelter хранит профили гостей. При создании брони через сайт проверяем, есть ли гость с таким email в Shelter (GET /guests?email=...). Если есть — передаём guest_id. Если нет — Shelter создаёт профиль автоматически. Это упрощает работу ресепшн при повторных визитах: вся история гостя видна прямо в PMS.

Сроки