Загрузка броней TravelLine в заказ-наряды 1С:УНФ расширением конфигурации

Постановка задачи

Нужен односторонний обмен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;

Расширение является стартом для доработок - и предоставляется "как есть". Посмотрим на спрос - возможно будем адаптировать.