Інтеграція 1С-Бітрікс із системою бронювання Shelter

Інтеграція 1С-Бітрікс з системою бронювання Shelter

Shelter — вітчизняна PMS для хостелів, міні-готелів і апарт-комплексів. Аудиторія — невеликі об'єкти, яким дорого впроваджувати важкі PMS, але потрібна нормальна автоматизація. Стандартна проблема: сайт на 1С-Бітрікс працює сам по собі, 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 і створюємо відповідні елементи інфоблоку в 1С-Бітрікс. Маппінг зберігається в таблиці 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, а на сайті показувати дані через стандартний інфоблок 1С-Бітрікс.

Отримання доступності

Агент запитує 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__ . '();';
}

Створення та скасування броней

При підтвердженні оплати в 1С-Бітрікс відправляємо бронь до Shelter. Shelter повертає booking_id, який зберігаємо в UF-полі замовлення UF_SHELTER_BOOKING_ID.

При скасуванні замовлення в 1С-Бітрікс (подія OnSaleOrderCanceled або зміна статусу через обробник) надсилаємо запит PUT /bookings/{id} з полем status: cancelled. Якщо Shelter API недоступний в момент скасування — ставимо завдання в чергу агента з повторними спробами.

Webhooks зі Shelter

Shelter надсилає сповіщення при зміні статусу броні в PMS (наприклад, менеджер скасував бронь прямо в Shelter, минаючи сайт). Налаштування webhook — у розділі «Налаштування → Інтеграції» Shelter.

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

Передача гостьової інформації

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

Терміни