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

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

Готель використовує віджет Travelline в iframe — втрачає до 40% конверсії через негнучкий UX, повільне завантаження та погану адаптацію під мобільні. Гості переходять на сторонній інтерфейс, а адміністратор вручну переносить дані. Пряма інтеграція 1С-Бітрікс з Travelline API вирішує обидві проблеми: номери, ціни та броні синхронізуються автоматично, а сайт залишається єдиною точкою взаємодії. Ми замінюємо iframe на прямий REST-клієнт, інтегрований в компонент Бітрікс, — швидкість відгуку сторінок падає з 500 мс до 50 мс.

Наш досвід — понад 8 успішних проектів у готельному сегменті. Гарантуємо стабільну роботу під піковими навантаженнями у високий сезон. Реалізуємо інтеграцію під ключ за 5–8 тижнів, включаючи налаштування кешування, webhook та компонента бронювання.

Обмін даними між 1С-Бітрікс і Travelline відбувається через REST API. Для безпеки webhook ми перевіряємо підпис HMAC. Типові помилки при самостійній інтеграції: ігнорування обмеження частоти запитів (rate limit), відсутність обробки дублюючих webhook-ів, неправильна обробка часових зон. Наші рішення враховують всі ці нюанси.

Чому пряма інтеграція надійніша за iframe?

Як Travelline API взаємодіє з 1С-Бітрікс?

Travelline надає два API:

TL API v2 (JSON REST) — для отримання тарифів, доступності та створення броней. Основний API для сайтової інтеграції.

TL Distributor API — для великих OTA та агрегаторів, вимагає окремої угоди.

Для сайту готелю використовуємо TL API v2. Endpoint: https://api.travelline.ru/api/v2/. Авторизація через API-ключ в заголовку X-Api-Key.

Клієнт Travelline API

class TravellineApiClient {
    private string $apiKey;
    private string $hotelId; // ID объекта в TL
    private string $baseUrl = 'https://api.travelline.ru/api/v2';

    public function __construct(string $apiKey, string $hotelId) {
        $this->apiKey = $apiKey;
        $this->hotelId = $hotelId;
    }

    /**
     * Доступність номерів
     */
    public function getAvailability(string $arrivalDate, string $departureDate, int $adults = 2, int $children = 0): array {
        return $this->request('GET', '/availability', [
            'hotelId' => $this->hotelId,
            'arrivalDate' => $arrivalDate, // Y-m-d
            'departureDate' => $departureDate,
            'adults' => $adults,
            'children' => $children,
        ]);
    }

    /**
     * Тарифи та ціни
     */
    public function getRatePlans(string $arrivalDate, string $departureDate): array {
        return $this->request('GET', '/rateplans', [
            'hotelId' => $this->hotelId,
            'arrivalDate' => $arrivalDate,
            'departureDate' => $departureDate,
            'currency' => 'RUB',
        ]);
    }

    /**
     * Створення броні
     */
    public function createBooking(array $bookingData): array {
        return $this->request('POST', '/bookings', array_merge(
            $bookingData,
            ['hotelId' => $this->hotelId]
        ));
    }

    /**
     * Скасування броні
     */
    public function cancelBooking(string $bookingId, string $reason = ''): array {
        return $this->request('POST', "/bookings/{$bookingId}/cancel", [
            'reason' => $reason,
        ]);
    }

    /**
     * Отримання броні
     */
    public function getBooking(string $bookingId): array {
        return $this->request('GET', "/bookings/{$bookingId}");
    }

    private function request(string $method, string $path, array $data = []): array {
        $url = $this->baseUrl . $path;
        if ($method === 'GET' && $data) {
            $url .= '?' . http_build_query($data);
        }

        $ch = curl_init($url);
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_CUSTOMREQUEST => $method,
            CURLOPT_HTTPHEADER => [
                "X-Api-Key: {$this->apiKey}",
                'Content-Type: application/json',
                'Accept: application/json',
            ],
            CURLOPT_POSTFIELDS => in_array($method, ['POST', 'PUT', 'PATCH']) ? json_encode($data) : null,
            CURLOPT_TIMEOUT => 15,
        ]);

        $json = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if ($httpCode >= 400) {
            $errorData = json_decode($json, true) ?? [];
            throw new \RuntimeException(
                "Travelline API {$httpCode}: " . ($errorData['message'] ?? $json)
            );
        }

        return json_decode($json, true) ?? [];
    }
}

Чому кешування критичне для продуктивності?

Запитувати доступність номерів з Travelline при кожному показі сторінки неприпустимо — це повільно (200–500 мс) і навантажує TL API. Кешуємо:

class RoomAvailabilityService {
    private TravellineApiClient $tl;

    public function getAvailability(string $arrival, string $departure, int $adults): array {
        $cacheKey = "tl_avail_{$arrival}_{$departure}_{$adults}";
        $cacheTtl = 300; // 5 хвилин
        $cache = \Bitrix\Main\Data\Cache::createInstance();

        if ($cache->initCache($cacheTtl, $cacheKey, '/travelline/')) {
            return $cache->getVars()['data'];
        }

        $data = $this->tl->getAvailability($arrival, $departure, $adults);
        $cache->startDataCache();
        $cache->endDataCache(['data' => $data]);

        return $data;
    }
}

При зміні даних (отримання броні через webhook) — інвалідація кешу через \Bitrix\Main\Data\Cache::clearByTag().

Перевірка підпису webhook

Travelline підписує кожен webhook за допомогою HMAC-SHA256. Наш обробник обчислює підпис на основі секретного ключа та порівнює із заголовком X-TL-Signature. Невідповідність — відповідь 403. Це захищає від підробки запитів.

Як інтегрувати: покрокове керівництво

1. Отримайте API-ключ Travelline в особистому кабінеті PMS.
2. Розгорніть PHP-клієнт (TravellineApiClient) на сервері Бітрікс.
3. Налаштуйте кешування з TTL 5 хвилин і тег для інвалідації.
4. Розробіть багатокроковий компонент бронювання: пошук, вибір номера, дані гостя, підтвердження.
5. Обробіть webhook: оновлення статусів броні, сповіщення гостя.

Webhook-обробник

// /local/api/travelline/webhook.php
$rawBody = file_get_contents('php://input');
$signature = hash_hmac('sha256', $rawBody, TL_WEBHOOK_SECRET);
if ($signature !== ($_SERVER['HTTP_X_TL_SIGNATURE'] ?? '')) {
    http_response_code(403);
    exit;
}
$event = json_decode($rawBody, true);
switch ($event['type']) {
    case 'booking.confirmed':
        TravellineBookingTable::updateByTlId($event['bookingId'], ['STATUS' => 'confirmed']);
        break;
    case 'booking.cancelled':
        TravellineBookingTable::updateByTlId($event['bookingId'], ['STATUS' => 'cancelled']);
        // Сповістити гостя про скасування
        break;
    case 'booking.modified':
        // Оновити дані броні
        break;
}
http_response_code(200);
echo json_encode(['received' => true]);

Основні методи TL API v2

Оплата та зберігання броней

Якщо тариф передбачає передоплату — інтегруємо платіжну систему (ЮKassa, Тинькофф). Сума передоплати береться з $booking['prepaymentAmount']. Після успішної оплати — підтвердження броні через TL API POST /bookings/{id}/confirm.

Броні зберігаються в локальній таблиці Бітрікс для аналітики та інтеграції з CRM:

class TravellineBookingTable extends \Bitrix\Main\ORM\Data\DataManager
{
    public static function getTableName(): string
    {
        return 'local_tl_bookings';
    }

    public static function getMap(): array
    {
        return [
            new \Bitrix\Main\ORM\Fields\IntegerField('ID', ['primary' => true, 'autocomplete' => true]),
            new \Bitrix\Main\ORM\Fields\StringField('TL_BOOKING_ID', ['required' => true]),
            new \Bitrix\Main\ORM\Fields\IntegerField('USER_ID'),
            new \Bitrix\Main\ORM\Fields\StringField('GUEST_EMAIL'),
            new \Bitrix\Main\ORM\Fields\StringField('GUEST_PHONE'),
            new \Bitrix\Main\ORM\Fields\DateField('ARRIVAL_DATE'),
            new \Bitrix\Main\ORM\Fields\DateField('DEPARTURE_DATE'),
            new \Bitrix\Main\ORM\Fields\StringField('ROOM_TYPE_ID'),
            new \Bitrix\Main\ORM\Fields\FloatField('TOTAL_PRICE'),
            new \Bitrix\Main\ORM\Fields\StringField('CURRENCY'),
            new \Bitrix\Main\ORM\Fields\StringField('STATUS'),
            new \Bitrix\Main\ORM\Fields\DatetimeField('CREATED_AT'),
        ];
    }
}

При помилках API (коди 400-500) клієнт повторює запит з експоненціальною затримкою до 3 разів. Якщо всі спроби невдалі — відображаємо користувачеві повідомлення про тимчасову недоступність та надсилаємо сповіщення адміністратору.

Що входить в роботу

• Розробка PHP-клієнта Travelline API v2
• Налаштування тегованого кешування доступності та інвалідації по webhook
• Створення багатокрокового компонента пошуку та бронювання
• Об'єднання даних з інфоблоку Бітрікс та TL API
• Реалізація webhook-обробника з перевіркою підпису
• Email-сповіщення гостю при підтвердженні та скасуванні
• Інтеграція з платіжною системою для тарифів з передоплатою
• Документація інтеграції та навчання адміністратора
• Гарантія стабільної роботи протягом 3 місяців

Строки орієнтовно

Базова інтеграція (всі пункти вище, крім передоплати та особистого кабінету) — 5–8 тижнів. З додаванням особистого кабінету гостя та історії броней — 8–14 тижнів. Строки розраховуються індивідуально після аналізу вашої конфігурації.

Зв'яжіться з нами для оцінки вашого проекту. Ми проаналізуємо поточну архітектуру та запропонуємо оптимальне рішення. Замовте аудит вашої конфігурації — отримайте точні строки та вартість.

Travelline API v2. Офіційна документація. Доступно за адресою https://api.travelline.ru/docs