Постановка задачи
Нужен односторонний обменTravelLine → УНФ без доработки типовых объектов.
Какое было выбрано соответствие свойств
Количество в строке работы — 1 (проживание), кратность — число ночей. Период ресурса совпадает с заездом и выездом. Отменённая бронь переводит заказ-наряд в завершённое отменённое состояние.
Почему расширение, а не изменение УНФ
Гостиничный учёт в УНФ хорошо ложится на заказ-наряд: работа — проживание в категории, ресурс — конкретный номер на интервал дат. Менять типовые модули ради этого не нужно. Расширение с префиксом Расш1_ добавляет свои справочники, регистры и обработку и не подписывается на события типовых документов.
• обновления УНФ ставятся штатно;
• права и подсистема изолированы;
• соответствия «идентификатор TravelLine → ссылка УНФ» лежат в своём регистре, повторная загрузка обновляет тот же заказ-наряд;
• протокол обмена пишется в журнал и сразу виден в обработке.
Состав расширения
В подключении хранятся адреса авторизации и API (по умолчанию partner.tlintegration.com), propertyId отеля, continueToken для инкрементальной выборки и дата последней синхронизации. Токен клиента — реквизит с режимом пароля.
Какие API TravelLine реально нужны
В кабинете TravelLine раздел «Подключения API» выглядит как набор галочек. Для этой задачи важны не все.
PMS API на тарифах вроде «Мини отель» часто стоит в статусе «Остановлено» и отвечает 403 You cannot consume this service. Это не значит, что брони читать нельзя: Read Reservation — отдельный продукт. Без PMS API расширение создаёт ресурсы по категориям и подставляет конкретный номер, только если он пришёл в самой брони.
Отдельная путаница — календарь «Блок доступности». Колонки «Продаётся онлайн» и «Закрыть / Открыть» — это квоты канала, а не документы бронирования. Read Reservation отдаёт только брони с номером вида ГГГГММДД-propertyId-… из раздела «Бронирования» (ручная бронь, сайт, OTA).
Авторизация и разбор JSON
Токен получают POST-запросом на /auth/token с grant_type=client_credentials. Дальше все вызовы идут с заголовком Authorization: Bearer.
Тело = "grant_type=client_credentials"
+ "&client_id=" + КодироватьURL(ИдентификаторКлиента)
+ "&client_secret=" + КодироватьURL(Токен);
Ответ = ВыполнитьHTTP(ХостАвторизации, "POST", "/auth/token", Тело, "application/x-www-form-urlencoded", "");
Если читать JSON в Структуру, ответ авторизации падает на полях вроде not-before-policy: дефис не является допустимым именем свойства. Читать нужно в Соответствие.
ЧтениеJSON = Новый ЧтениеJSON;
ЧтениеJSON.УстановитьСтроку(СтрокаJSON);
Данные = ПрочитатьJSON(ЧтениеJSON, Истина); // Соответствие
ЧтениеJSON.Закрыть();
Ниже перечень методов/свойств
1. Content API: GET /api/content/v1/properties — список отелей. Если код отеля в подключении пуст, записывается первый найденный propertyId.
2. GET /api/content/v1/properties/{propertyId} — массив roomTypes. На каждую категорию создаётся или находится номенклатура с типом «Работа».
3. PMS API: /api/pms/v2/properties/{id}/rooms. При 403 или 404 физические номера пропускаются без аварийного завершения, в протокол пишется причина.
4. Fallback: ресурс на категорию с техническим идентификатором roomType-{id}. В заказ-наряде он занимает место номера, пока в брони нет конкретного roomId.
Соответствия пишутся в регистр, поэтому повторная синхронизация не плодит дубли номенклатуры и ресурсов.
Как устроена загрузка броней
Read Reservation отдаёт постраничный список bookingSummaries.
• lastModification — старт выборки в UTC. Без него API инициирует полную синхронизацию с 2009-01-01, и HTTP-запрос легко упирается в таймаут;
• continueToken — продолжение с прошлого ответа; нельзя передавать вместе с lastModification;
• hasMoreData = false означает конец текущей порции, но следующие вызовы с тем же токеном уже вернут новые и изменённые брони.
В обработке с формы запускается загрузка за последние 24 месяца — так пользователь не зависит от застрявшего continueToken. Регламентное задание может идти инкрементально по сохранённому токену.
На каждую сводку запрашиваются детали GET .../bookings/{number}. Из roomStays берутся категория, даты, сумма, гости.
1. Найти заказ-наряд по регистру соответствий. Если нет — создать документ с видом операции «Заказ-наряд».
2. Контрагент — по ФИО гостя (создаётся при включённом флаге). Пока упрощенный вариант - в дальнейшем можно привязаться к телефону или электронной почте.
3. ТЧ «Работы» очищается и заполняется заново: номенклатура категории, количество 1, кратность = число ночей, сумма из priceAfterTax.
4. ТЧ «Ресурсы предприятия»: конкретный номер, если он есть в брони, иначе ресурс категории; Старт / Финиш = заезд / выезд.
5. Дополнительные услуги брони добавляются отдельными строками работ.
6. Документ записывается. Проведение — отдельный флаг: если оно падает на заполненности типовых реквизитов, остаётся запись.
Установка
1. В конфигураторе загрузить расширение из каталога выгрузки (префикс Расш1_, назначение «Дополнение»).
2. Проверить, что расширение активно, безопасный режим выключен: нужны HTTP-соединения и запись документов.
3. Обновить конфигурацию базы данных.
4. Назначить пользователям роль Расш1_ОсновнаяРоль.
5. В пользовательском режиме открыть раздел TravelLine — Синхронизация TravelLine.
Настройка подключения
В справочнике заполняются идентификатор и токен из кабинета TravelLine.
Код отеля можно не указывать: его подставит Content API при первой проверке. Организация — та, от которой будут заказ-наряды.
Рекомендуемый порядок кнопок:
«Проверить подключение» — токен и список отелей;
«Справочники» — категории и номера;
«Загрузить брони» — заказ-наряды. В протоколе должны появиться HTTP-код 200 и комментарии по логам.
Регламентное задание включено по умолчанию с периодом 900 секунд. На копии базы его лучше выключить.
Настройка кабинета TravelLine
В карточке API-подключения должны стоять как минимум Content API и Read Reservation API. Условия оферты TravelLine нужно принять в кабинете: без этого токен может выдаваться, а прикладные методы отвечать 403.
Чтобы в УНФ появились именно «Номер 101», а не ресурс «Стандарт», нужен PMS API и тариф, где он разрешён (Стандарт, Премиум или платная опция к «Мини отелю»). PMS Integration API для этой цели не подходит: он про доступность и блоки квот, а не про карточки физических номеров WebPMS.
Что сознательно не сделано (пока?)
• выгрузка броней и цен обратно в TravelLine;
• вебхуки — контур рассчитан на периодический обмен;
• сопоставления уже существующих номенклатуры и ресурсов: первое создание идёт автоматически по наименованию категории.
Это можно нарастить тем же расширением: регистр соответствий и журнал уже есть, менять типовую УНФ по-прежнему не потребуется.
Идеи для следующей версии
Можно будет добавить отправку броней непосредственно из 1С. Поменять интерфейс Планирования ресурсов с адаптацией к гостиницам
Заключение
Заказ-наряд УНФ удачно совпадает с гостиничной бронью: работа — категория, ресурс — номер на даты, контрагент — гость. По крайней мере другого решения в лоб с минимальными доработками я не увидел. TravelLine Partner API это покрывает связкой Content + Read Reservation;
Расширение является стартом для доработок - и предоставляется "как есть". Посмотрим на спрос - возможно будем адаптировать.
Проверено на следующих конфигурациях и релизах:
- Управление нашей фирмой, редакция 3.0, релизы 3.0.14.143
Вступайте в нашу телеграмм-группу Инфостарт