Перейти к основному содержимому
API docs by Redocly

TravelLine Partner APIs (1.0.0)

Download OpenAPI specification:Download

Авторизация

Перед началом работы

Для работы с API необходим токен доступа (access_token). Токен выдается на основании учетных данных client_id и client_secret. Получить их можно одним из следующих способов.

Подключение через средство размещения

Отельер создает API-подключение в личном кабинете TravelLine и передает вам учетные данные client_id и client_secret. Подробнее см. в разделе Подключение через средство размещения.

Прямое подключение партнера

Если вы прямой партнер TravelLine, запросите доступ к тестовой среде и учетные данные client_id и client_secret у TravelLine. Подробнее см. в разделе Прямое подключение партнера.

После получения учетных данных отправьте запрос на конечную точку авторизации. В ответе вы получите токен доступа (access_token) для работы с API.

Передавайте значение access_token в каждом запросе к API в заголовке Authorization:

Authorization: Bearer <access_token>

Авторизация происходит через OAuth2.0.

OAuth 2.0 – это стандарт авторизации, который позволяет приложениям получать доступ к данным.

Для работы с API в запросах необходимо передавать ключ доступа в формате JSON Web Token (JWT).

JWT (JSON Web Token) — это специальный формат токена, который позволяет безопасно передавать данные между клиентом и сервером.

Получение JWT происходит через Client credentials flow, то есть авторизацию по секретному ключу доступа. Для запроса ключа доступа необходимы следующие параметры:

  • client_id,
  • client_secret.

Диаграмма взаимодействия

alt text

TravelLine. Сервер авторизации: https://partner.tlintegration.com/auth/token

Токен доступа

Лимиты на авторизацию

  • 3 запроса в секунду,
  • 15 запросов в минуту,
  • 300 запросов в час с одного IP-адреса.

Время жизни токена

Токен доступа действует 15 минут.

Обновление токена не поддерживается. После истечения срока действия запросите новый токен через конечную точку авторизации.

Конечная точка авторизации

Пример токена доступа:

eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI2OGZjOHRNUGFSUHRyRHYtVHV2WEpncUNGTE1CVGRheTBpQkdJSUE3amxvIn0.eyJleHAiOjE2OTg5MTYwMzYsImlhdCI6MTY5ODkxNTEzNiwianRpIjoiYTJjZGJhMGQtYzQwNy00OWRmLThiNGQtOTJhNTM1NWQxYTFmIiwiaXNzIjoiaHR0cHM6Ly9wYXJ0bmVyLnRsaW50ZWdyYXRpb24uY29tL2F1dGgvcmVhbG1zL1BhcnRuZXJBcGkiLCJhdWQiOiJUcmF2ZWxMaW5lLlBhcnRuZXJBUEkiLCJzdWIiOiI4NmE0YjZiZS0wYTc0LTRjYjktYjNhYi1iNDYyZWUwYmIyYmQiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJwYTMiLCJzY29wZSI6IiIsImFwaV9hY2Nlc3NlcyI6WyJjb250ZW50Il19.Nz6dyaHGyIN5IKv30oM-HrqdQBqaGdzEFrk7ACUWbfvsNCHNowg96iJrGwQbkOUSVPtQJF9Cwf1_jywP6c2UPHclzBIDp9HTsYdVM5QS_k9ecs0GCiI8ACBqld3yatY4dJz3MRkxnU_rp0NbJJQ-uBcmg_9UCSCIc3mKR7UAosr5XOXeb4ckrFd67DK5xfofT0ykE46Qkc6nvev3AGx11fPAVsFnmmPOSnlpQzJTI7XBWbD120q5fDdksVlaiq3YoBueDEeOPFH08Ia6xdTVjIf_zsyOEKt2N8_7BTyWG_3YPThBbgn-eAgybSdeop6_eCrWTfQvX5g8qtR2e9J32A

На сайте JWT.IO можно расшифровать токен доступа.

Пример расшифрованного токена

Содержимое запроса:

{
  "exp": 1698916036,
  "iat": 1698915136,
  "jti": "a2cdba0d-c407-49df-8b4d-92a5355d1a1f",
  "iss": "https://partner.tlintegration.com/auth/realms/PartnerApi",
  "aud": "TravelLine.PartnerAPI",
  "sub": "86a4b6be-0a74-4cb9-b3ab-b462ee0bb2bd",
  "typ": "Bearer",
  "azp": "pa3",
  "scope": "",
  "api_accesses": [
    "content"
  ]
}

Обратите внимание. Токен обновления не используется.

Рекомендации

  1. Кешируйте на стороне клиента токен доступа и используйте его повторно в своих запросах.

  2. Используйте библиотеки для OAuth2.0:

    • .NET:
      IdentityModel
      Microsoft.Extensions.DependencyInjection

    • JavaScript:
      oidc-client
      oidc-client-js Wiki

    • PHP:
      OpenID-Connect-PHP

    • cURL: 

      curl -L -X POST "https://partner.tlintegration.com/auth/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id=XXXXXXXXXXXX" \
-d "client_secret=XXXXXXXXXXXX"

Лимиты

Чтобы обеспечить стабильную работу сервиса, мы ввели ограничения на количество запросов к API со стороны пользователей. Если лимит превышен, API вернет ошибку 429 Too Many Requests, а запрос не будет обработан.

Если не указано иное, ограничения применяются отдельно к каждому клиенту API. Все запросы, выполняемые от имени одного клиента, учитываются в рамках общего лимита независимо от IP-адреса и количества используемых токенов доступа.

Лимиты определяют максимальное количество запросов, которое можно выполнить за секунду, минуту или час. При обработке каждого нового запроса учитывается количество запросов, выполненных за соответствующий период непосредственно перед его отправкой. Например, если установлен лимит 50 в секунду, то 51-й запрос, отправленный в течение той же секунды, будет отклонен. Выполнение запросов станет доступно снова, как только количество запросов за последнюю секунду окажется ниже установленного лимита. Аналогично работают ограничения за минуту и час.

API Описание Лимиты
API со стандартными лимитами Все методы API, для которых не заданы отдельные ограничения 50 запросов в секунду, 200 в минуту, 3000 в час
PMS Integration Storage API Все методы API 50 запросов в секунду, 1200 в минуту, 30000 в час
Public Reviews API Все методы API с одного IP-адреса 50 запросов в секунду, 1200 в минуту, 30000 в час
Read Reservation API Получение списка бронирований 3 запроса в секунду, 100 в минуту, 3000 в час
Read Reservation API Получение информации о бронировании 10 запросов в секунду, 200 в минуту, 4000 в час
Search API Поиск вариантов размещения по минимальной цене 3 запроса в секунду, 20 в минуту, 900 в час
Search API Получение вариантов размещения 50 запросов в секунду, 200 в минуту, 1000 в час
Search API Получение вариантов размещения с дополнительными услугами, ранним заездом или поздним выездом 10 запросов в секунду, 50 в минуту, 500 в час
Search API Получение дополнительных услуг, раннего заезда или позднего выезда 10 запросов в секунду, 100 в минуту, 1000 в час

Мониторинг лимитов через заголовки

В каждом ответе API возвращаются заголовки, которые помогут вам отслеживать оставшееся количество запросов:

  • x-ratelimit-remaining-hour - количество оставшихся запросов в течение часа с момента отправки.
  • x-ratelimit-remaining-minute - количество оставшихся запросов в течение минуты с момента отправки.
  • x-ratelimit-remaining-second - количество оставшихся запросов в течение секунды с момента отправки.
  • retry-after - этот заголовок возвращается при ошибке 429 Too Many Requests и указывает время (в секундах), через которое можно повторить запрос.

Коды ошибок

Код ошибки Сообщение Описание
400 Bad Request В содержании запроса есть ошибка — например, отсутствуют обязательные заголовки или значения параметров некорректны.
401 Unauthorized Ошибка может возникать по разным причинам: В запросе не указан OAuth-токен. Или указан, но не там. Закончился срок действия токена — в этом случае получите новый.
403 Forbidden У пользователя нет доступа к определенным методам API.
404 Not Found Запрашиваемый ресурс не существует или устарел. Проверьте адрес запроса.
429 Too Many Requests Превышен лимит запросов в секунду (RPS). Убедитесь, что не отправляете лишнего.
500 Internal Server Error Внутренняя ошибка сервера. Попробуйте зайти позже.
503 Service Unavailable Сервер перегружен. Попробуйте зайти позже.

CancellationRules

Swagger

Правила отмены бронирования устанавливаются средством размещения для определения срока, в течение которого возможна бесплатная отмена, а также штрафа за позднюю отмену. Эти правила применяются к выбранным тарифам через их свойство cancellationRuleId.

Правило может начать действовать с одного из следующих моментов времени:

  • ProviderArrivalTime: Стандартное время заезда. Например, если время заезда в средство размещения установлено на 14:00, бесплатная отмена будет доступна до 14:00 дня, предшествующего дню заезда.

  • ProviderDepartureTime: Стандартное время выезда. Отсчет начинается с момента выезда в день прибытия. Например, если время выезда в средстве размещения установлено на 12:00, бесплатная отмена будет доступна до 12:00 дня, предшествующего дню заезда.

  • GuestArrivalTime: Время заезда, которое указал гость во время бронирования. Например, если стандартное время заезда — 14:00, но гость выбрал заезд в 16:00, бесплатная отмена будет доступна до 16:00 дня, предшествующего дню заезда. Если гостю не разрешено выбирать время заезда, будет использовано стандартное время, которое принято в средстве размещения.

  • CustomArrivalTime: Выбранное время, с которого начинается отсчет для правила отмены. Время указывается в поле referencePointTime с использованием часового пояса средства размещения.

  • BookingCreationTime: Время (но не дата), когда гость сделал бронирование. Например, если время заезда установлено на 14:00, а гость забронировал номер в 9:00, бесплатная отмена будет доступна до 9:00 дня, предшествующего дню заезда.

Штраф за определенный период

Штраф устанавливается с использованием временных рамок, которые включают в себя единицы времени и период до контрольной точки.

  • Единицы времени:

    • None: Не указано, используется только с периодом NoMatter.
    • Day: Дни.
    • Hour: Часы.

  • Период до контрольной точки:

    • NoMatter: Не зависит от конкретного времени.
    • AtLeast: Больше или равно значению beforeArrivalValue.
    • NoMoreThan: Меньше или равно значения beforeArrivalValue.
    • Between: В пределах интервала от beforeArrivalValue до beforeArrivalValueMax.

Режимы расчета штрафов

  • NoPenalty: Штраф не применяется.
  • FirstNightPercent: Штраф составляет указанный процент от стоимости первой ночи.
  • PrepaymentPercent: Штраф составляет указанный процент от суммы предоплаты.
  • FirstNights: Штраф равен полной стоимости первых N ночей.

Штраф для выбранного режима расчета указывается в виде числового значения и валюты.

Период действия правила можно установить, выбрав даты прибытия в часовом поясе гостиницы. Период включает в себя как начальную, так и конечную дату. Если дата окончания не указана, она может быть установлена как «Не ограничено», что соответствует isEndless = true.

Если в правиле нет условий отмены, отмена осуществляется бесплатно.

Конечная точка

GET /v1/properties/{propertyId}/cancellation-rules

Получение правил отмены бронирования.

Параметры:

  • propertyId (string, path): ID средства размещения.

Пример:

GET /v1/properties/7291/cancellation-rules

{
  "cancellationRules": [
    {
      "id": "556875",
      "propertyId": "7291",
      "referencePointKind": "CustomArrivalTime",
      "referencePointTime": "10:57",
      "cancellationTerms": [
        {
          "beforeArrivalMatching": "Between",
          "beforeArrivalUnit": "Day",
          "beforeArrivalValue": 1,
          "beforeArrivalValueMax": 3,
          "penaltyCalculationMethod": "PrepaymentPercent",
          "penaltyValue": 10,
          "penaltyValueCurrency": "EUR",
          "arrivalDates": [
            {
              "startDate": "2024-07-11",
              "endDate": "2024-07-11",
              "isEndless": true
            }
          ]
        },
        {
          "beforeArrivalMatching": "NoMoreThan",
          "beforeArrivalUnit": "Hour",
          "beforeArrivalValue": 24,
          "penaltyCalculationMethod": "PrepaymentPercent",
          "penaltyValue": 100,
          "penaltyValueCurrency": "EUR",
          "arrivalDates": [
            {
              "startDate": "2021-02-09",
              "endDate": "2021-02-09",
              "isEndless": true
            }
          ]
        }
      ]
    }
  ]
}

Receive cancellation rules

path Parameters
propertyId
required
string
Example: 1024

Property ID

Responses

Response samples

Content type
application/json
{
  • "cancellationRules": [
    ]
}

ContentApi

Swagger

Content API позволяет получить фотографии и описание средства размещения, категорий номеров, тарифов, услуг, удобств. Эта информация отображается в модуле бронирования TL: Booking Engine на официальном сайте средства размещения.

  1. Общие настройки, описание и фото средства размещения.
  2. services - все услуги, включая питание.
  3. ratePlans - тарифы.
  4. roomTypes - категории номеров.
  5. amenities - удобства.
  6. Отсутствуюшие в личном кабинете настройки:
    • currency - валюта, определяется страной.
    • timeZone - часовой пояс, определяется городом.
    • stayUnitKind - модель продажи номеров в модуле бронирования (NightRate или DailyRate), определяется типом средства размещения.
    • multiLocationProperty - позволяет иметь разные адреса для категорий номеров, можно включить по запросу в техподдержку TravelLine.

Кроме того, API предоставляет справочники вариантов выбора для настроек:

  1. meal-plans - типы питания, например:
    • код EnglishBreakfast имя Английский завтрак.
    • код FullBoard имя Полный пансион.
  2. room-type-categories - типы предложений, например:
    • код Apartments имя Апартаменты.
    • код PlaceInRoom имя Место в номере.
    • код SmallHouse имя Домик.
  3. room-amenity-categories - оснащение номеров, например:
    • группа Интернет/телефония код wifi_internet имя Wi-Fi-интернет.
    • группа Мебель код journal_table имя журнальный столик.

Услуги

Вид услуги можно определить по значению поля kind:

  • Common - любые услуги, кроме питания.
  • Meal - услуги питания.

Для услуг питания дополнительно заданы поля mealPlanCode и mealPlanName, заполненные значениями из справочника типов питания.

Тарифы

Тарифы связаны с другими подразделами API:

  • поле extraStayRuleId указывает на правило раннего заезда и позднего выезда (см. ExtraStayRules).
  • поле cancellationRuleId указывает на правило отмены бронирования (см. CancellationRules).

Категории номеров

Категории номеров связаны со справочниками:

  • поля categoryCode и categoryName - тип предложения.
  • элементы массива amenities (code и name) - оснащение номеров.

Удобства

Список доступных удобств средства размещения:

  • code - идентификатор.
  • displayName - название для отображения.
  • chargeType - тип оплаты:
    • free - бесплатная услуга.
    • сhargeable - платная услуга.
    • none - тип оплаты не применим (услуга не подразумевает оплаты, например: консьерж).

Удобства с идентификаторами swimming_pool и restaurant могут дублироваться поскольку их может быть несколько в рамках одного средства размещения.

Receive property entity

query Parameters
since
string
Example: since=UlUtNDE5NQ==

Key to continue viewing from the required spot

The number of accommodations in the response is limited, so you may not always be able to get them all within one request.

To continue from the spot you left off, use this option.

The value of this parameter can always be obtained from the response (‘next’ property).

If you do not specify this parameter, you will obtain accommodations from the very beginning of the list.

Analogue to pagination.

count
integer <int32>
Example: count=200

The number of elements in the response.

Maximum number of elements - 200 (default value)

include
string
Example: include=

Add additional information to the response

‘All’ value: information about the hotel, room types, rate plans and services

Empty value: ‘Id’ only

languageCode
string
Example: languageCode=

Language code. Allowed values: 'en' (English).

If you do not specify this parameter, you will obtain accommodations in the property’s language.

Responses

Response samples

Content type
application/json
{
  • "next": "string",
  • "properties": [
    ],
  • "warnings": [
    ]
}

Receive description of a property

path Parameters
propertyId
required
string
Example: 1024

Property ID

query Parameters
languageCode
string
Example: languageCode=

Language code. Allowed values: 'en' (English).

If you do not specify this parameter, you will obtain accommodations in the property’s language.

Responses

Response samples

Content type
application/json
{
  • "id": "1024",
  • "name": "Test hotel",
  • "description": "Hotel is located in a picturesque location. \n\nThere are 11 hotel rooms of \"Standard\" and \"Standard +\" categories, as well as 4 separate cottages of the \"Duplex\" type for accommodation of guests on the territory of the club.",
  • "currency": "GBP",
  • "images": [
    ],
  • "stars": 4,
  • "stayUnitKind": "NightRate",
  • "propertyKindId": 1,
  • "contactInfo": {
    },
  • "policy": {
    },
  • "timeZone": {
    },
  • "ratePlans": [
    ],
  • "roomTypes": [
    ],
  • "services": [
    ],
  • "multiLocationProperty": true,
  • "companyDetails": {
    },
  • "fsaCertifications": [],
  • "amenities": [
    ]
}

Receive entity of possible meal options

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Receive entity of possible room types

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Receive entity of possible room amenities

Responses

Response samples

Content type
application/json
[
  • {
    }
]

ExtraStayRules

Swagger

Правила позволяют устанавливать доплату за ранний заезд и поздний выезд. Эти правила применяются к выбранным тарифам через их свойство extraStayRuleId.

Настройка «Заезд и выезд» задает стандартное время заезда и выезда, которое не требует дополнительной платы.

Эти правила дают возможность назначать доплату за определенные временные промежутки между временем раннего заезда или позднего выезда и стандартным временем заезда/выезда.

Способы расчета доплаты

  • Free: без дополнительной платы.
  • Fixed: установленная сумма.
  • Percent: процент от стоимости за ночь.
  • HourlyRate: фиксированная ставка за час.
  • HourlyRateAutoCalculated: цена за час рассчитывается автоматически.
  • Forbidden: ранний заезд/поздний выезд не допускается.

Fixed и HourlyRate позволяют устанавливать несколько тарифов (rates) в разных валютах.

Percent позволяет задать процент доплаты и дополнительные параметры:

  • extraPlacementEnabled: 'true', если взимается доплата за дополнительного гостя; 'false', если доплата не взимается.
  • extraServiceOption: дополнительные услуги, за которые взимается доплата [None, All, MealOnly].

Свойство OccupyQuota указывает, гарантирована ли доступность номера для дополнительного пребывания.

  • true: доступность номера гарантирована.
  • false: доступность номера не гарантируется, даже если дополнительное пребывание оплачено заранее.

Конечная точка

GET /v1/properties/{propertyId}/extra-stay-rules

Получение правил раннего заезда и позднего выезда.

Параметры:

  • propertyId (string, path): ID средства размещения.

Пример:

GET /v1/properties/7291/extra-stay-rules

{
  "extraStayRules": [
    {
      "id": "519845",
      "propertyId": "7291",
      "checkInTime": "13:00",
      "overridesPropertyCheckInTime": false,
      "earlyCheckInPeriods": [
        {
          "startTime": "00:00",
          "endTime": "09:00",
          "chargeType": "Forbidden",
          "rates": [],
          "occupyQuota": false
        },
        {
          "startTime": "09:00",
          "endTime": "13:00",
          "chargeType": "Percent",
          "rates": [],
          "percentOptions": {
            "percentage": 0,
            "extraPlacementEnabled": false,
            "extraServiceOption": "MealOnly"
          },
          "occupyQuota": false
        }
      ],
      "checkOutTime": "12:00",
      "overridesPropertyCheckOutTime": true,
      "lateCheckOutPeriods": [
        {
          "startTime": "12:00",
          "endTime": "16:00",
          "chargeType": "Fixed",
          "rates": [
            {
              "currency": "EUR",
              "rate": 20
            }
          ],
          "occupyQuota": false
        },
        {
          "startTime": "16:00",
          "endTime": "24:00",
          "chargeType": "Forbidden",
          "rates": [],
          "occupyQuota": false
        }
      ]
    }
  ]
}

Receive early check-in and late check-out rules

path Parameters
propertyId
required
string
Example: 1024

Property ID

Responses

Response samples

Content type
application/json
{
  • "extraStayRules": [
    ]
}

Reservation

Swagger

Read Reservation API позволяет получить информацию о бронированиях средств размещения из компонентов TL: Booking Engine, TL: Channel Manager и TL: WebPMS.

Получение краткой информации по бронированиям

Метод возвращает постраничный список с краткой информацией по каждому бронированию.

  • Параметр lastModification позволяет начать получение списка бронирований, сделанных или измененных после указанной даты/времени в часовой зоне UTC. Параметр можно не указывать, чтобы начать полную синхронизацию.

  • Параметр continueToken позволяет продолжить получение списка. Его значение берется из результатов предыдущего запроса. Срок службы токена не ограничен. Запрос может вернуть полученное ранее, но уже изменившееся бронирование.

  • Признак hasMoreData = false информирует о достижении конца списка. Даже после этого запросы продолжения будут возвращать новые данные, появившиеся с момента предыдущего запроса.

Если произойдет потеря continueToken, рекомендуется выполнить новый запрос с использованием параметра lastModification для получения нового continueToken.

Значение для lastModification рекомендуется определить следующим образом: укажите дату последнего изменения бронирования lastModification минус два дня. Этот подход поможет избежать пропуска бронирований при последующем запросе данных.

Получение информации по бронированию

Метод возвращает детальную информацию по одному бронированию.

В ответе есть настройки, доступные через ContentApi:

  • booking.roomStays[].ratePlans[] - тарифы.
  • booking.roomStays[].dailyRates[].RatePlanId - тарифы.
  • booking.roomStays[].roomType - категория номеров.
  • booking.roomStays[].services[] - услуги.
  • booking.services[] - услуги с темпом начислением цены «За бронь».

Receive booking summaries

path Parameters
propertyId
required
string
Example: 1024

Property ID

query Parameters
continueToken
string
Example: continueToken=V2Ugd2lzaCB5b3UgcHJvZHVjdGl2ZSBpbnRlcmFjdGlvbiE=

Use the token from the previous response to continue receiving booking summaries including new and updated ones.
The token must not request bookings modified earlier than 2009-01-01T00:00:00Z.
For the first request, the parameter must be empty.

count
integer <int32>
Example: count=1000

Maximum mumber of booking summaries in response.
The maximum allowed value is 1000 (default).

lastModification
string <date-time>
Example: lastModification=2023-06-20T10:41:04Z

Enumerate booking summaries based on the last modification datetime, starting from the specified datetime in UTC.
Bookings can be requested starting from 2009-01-01T00:00:00Z.
For subsequent requests, the parameter must be empty.
Specifying both continueToken and lastModification results in an error.
If neither continueToken nor lastModification is specified, a search for all bookings starting from 2009-01-01T00:00:00Z (a full sync) is initiated.

Responses

Response samples

Content type
application/json
{
  • "continueToken": "Qm9va2luZ0NvbnRpbnVhdGlvblRva2Vu",
  • "hasMoreData": false,
  • "bookingSummaries": [
    ]
}

Receive booking details

path Parameters
propertyId
required
string
Example: 7291

Property ID

number
required
string
Example: 20240303-7291-14573801

Booking number

Responses

Response samples

Content type
application/json
{
  • "booking": {
    }
}

SearchRoomStays

Swagger

Важно: Обязательным условием предоставления Search API является использование результатов поиска для создания бронирований в TravelLine: Platform. В случае нарушения условия предоставления, API может быть отключено правообладателем в одностороннем порядке. Для возобновления доступа к API напишите support@travelline.ru

Search API предоставляет поиск вариантов размещения с минимальной ценой по всем доступным средствам размещения (до 200) и выборки предложений для конкретного средства размещения.

В поиске предоставляются данные на год вперед от текущей даты. Максимально количество дней между параметрами arrivalDate и departureDate — 100. Максимальное количество дней между датой arrivalDate и текущей датой — 365.

Доступны два отдельных метода, которые возвращают сведения о раннем заезде/ позднем выезде и о дополнительных услугах для конкретного размещения. Обе группы данных могут быть получены одним запросом:
GET /api/search/v1/properties/{propertyId}/room-stays при указании includeExtraStays=true и includeExtraServices=true.

Фильтры в агрегационном поиске

В методе /api/search/v1/properties/room-stays/search можно указать фильтры:

По наличию питания — поле mealPreference.mealType. В запросе можно передать следующие значения:

All — отображение минимального по стоимости варианта проживания по каждому средству размещения.

MealOnly — отображение минимального по стоимости варианта проживания с включенным в стоимость тарифа питанием по каждому средству размещения. Если отсутствует такой вариант проживания, средство размещения не выводится.

По типу питания — поле mealPreference.mealsIncluded. В запросе можно передать значения возможных вариантов питания, которые доступны в ответе метода content/v1/meal-plans, а также в ответе методов content/v1/properties — отображение всей информации о доступных средствах размещения и content/v1/properties{propertyId} — отображение информации по конкретному средству размещения.

Результат поиска показывает минимальные по стоимости варианты проживания с включенными в стоимость тарифа конкретными типами питания по каждому средству размещения. Например, если в запросе указать только значения BreakFast, в ответе можно получить минимальные по стоимости варианты проживания с включенным в стоимость тарифа типом питания BreakFast. При этом, в ответе будут отсутствовать варианты AllInсlusive или HalfBoard.

Фильтр по типу питания можно использовать только при наличии типа питания MealOnly.

По минимальной и максимальной стоимости проживания — поля pricePreference.minPrice и pricePreference.maxPrice.

Эти поля являются необязательными. Если передать значения полей в API, результат поиска покажет варианты проживания с минимальной ценой по всем доступным средствам размещения по выбранным фильтрам.

Search for the lowest priced accommodation options across all available accommodations. The maximum number of accommodation to be searched - 200.

Request Body schema:

Search parameters

propertyIds
Array of strings or null

Accommodations IDs

Maximum number of IDs - 200

adults
required
integer <int32>

Number of adults

childAges
Array of integers or null <int32>

Child age range

include
string or null

Add additional information about room types and rate plans to the response

empty by default, but values can be accepted as follows:

roomTypeShortContent - content by room types only

ratePlanShortContent - content by rate plans only

roomTypeShortContent|ratePlanShortContent - content by both rate plans and room types

arrivalDate
required
string <date-time>

Check-in date.

Date format complies with ISO-8601 YYYY-MM-DD

departureDate
required
string <date-time>

Check-out date.

Date format complies with ISO-8601 YYYY-MM-DD

object (SearchApi_MealPreference)

Meal filters

object (SearchApi_PricePreference)

Price filters

corporateIds
Array of strings or null

Corporate clients identifiers to identify corporate clients

Rate plans for requested corporate clients to be included in the search results

Responses

Request samples

Content type
{
  • "propertyIds": [
    ],
  • "adults": 1,
  • "childAges": [
    ],
  • "include": "",
  • "arrivalDate": "2026-07-19",
  • "departureDate": "2026-07-20",
  • "mealPreference": {
    },
  • "pricePreference": {
    },
  • "corporateIds": [
    ]
}

Response samples

Content type
application/json
{
  • "roomStays": [
    ],
  • "warnings": [
    ]
}

Search for accommodation options by specific accommodation

path Parameters
propertyId
required
string
Example: 1024

Accommodation ID

query Parameters
arrivalDate
required
string
Example: arrivalDate=2026-07-19

Check-in date.

Format complies with ISO-8601 YYYY-MM-DD

departureDate
required
string
Example: departureDate=2026-07-20

Check-out date.

Format complies with ISO-8601 YYYY-MM-DD

adults
required
integer <int32>
Example: adults=1

Number of adults

childAges
Array of integers <int32> [ items <int32 > ]

Child age range

corporateIds
Array of strings

Corporate clients identifiers to identify corporate clients

        Rate plans for requested corporate clients to be included in the search results

Responses

Response samples

Content type
application/json
{
  • "roomStays": [
    ],
  • "warnings": [
    ]
}

Search for extra services by accommodation conditions

path Parameters
propertyId
required
string
Example: 1024

Accommodation ID

Request Body schema:
required

Search parameters

required
object (SearchApi_StayDates)

Period of stay

required
object (SearchApi_RoomTypeRq)
required
object (SearchApi_RatePlan)

Rate plan entity

required
object (SearchApi_GuestCount)

Number of guests entity

Responses

Request samples

Content type
{
  • "stayDates": {
    },
  • "roomType": {
    },
  • "ratePlan": {
    },
  • "guestCount": {
    }
}

Response samples

Content type
application/json
{
  • "roomStayExtraServices": [
    ]
}

Search for extra stays by accommodation conditions

path Parameters
propertyId
required
string
Example: 1024

Accommodation ID

Request Body schema:
required

Search parameters

object (SearchApi_StayDates)

Period of stay

object (SearchApi_RoomTypeRq)
object (SearchApi_RatePlan)

Rate plan entity

object (SearchApi_GuestCount)

Number of guests entity

Responses

Request samples

Content type
{
  • "stayDates": {
    },
  • "roomType": {
    },
  • "ratePlan": {
    },
  • "guestCount": {
    }
}

Response samples

Content type
application/json
{
  • "extraStays": {
    }
}

Property

Swagger

Retrieves the accommodation inventory for a property.

path Parameters
propertyId
required
string
Example: 5431

Property Identifier

Responses

Response samples

Content type
application/json
{
  • "warnings": [
    ],
  • "errors": [
    ],
  • "accommodationInventory": {
    }
}

PropertyCompany

Swagger

Методы позволяют искать и извлекать информацию о компаниях, содержащихся в справочнике компаний средства размещения. Эта информация отображается в модуле TL: WebPMS в разделе "Справочник компаний".

Retrieves the list of companies for a property.

path Parameters
propertyId
required
string
Example: 5431

Property Identifier

query Parameters
maxPageSize
integer <int32>
Example: maxPageSize=100

Maximum number of items to return (<=100)

pageToken
string
Example: pageToken=V2Ugd2lzaCB5b3UgcHJvZHVjdGl2ZSBpbnRlcmFjdGlvbiE=

Pagination token for next page.

Token is in the response if the number of items exceeds the limit.

Send it back to get the next set of items.

If the request contains the token, other parameters passed in the query are ignored.

Responses

Response samples

Content type
application/json
{
  • "warnings": [
    ],
  • "errors": [
    ],
  • "nextPageToken": "b24aRNO0Q0WD2CLexb8G6EnqlYqQTWUdGdkrh9DqjLYBthewTbDErm55sLvB+41A5p8aoDpkA6CG1QCGz63jBOqWcPrwZoHwDLUnPp6HZx4FKcRzBSrItBLY2QpAOWxYZnAF57I8dPg7/fgj/xgWEWT/M9qwM8MNihVJX1twL2jABZ3pG49qjbMJMUpXAHdnFtMNjV1ILwg+WhOXnnHjr+4BdmSTiQMAvo3inEewRRg=",
  • "hasNextPage": true,
  • "companies": [
    ]
}

PropertyGuest

Swagger

Методы поиска, извлечения и обновления профилей гостей и связанных с ними данных (карты лояльности, бронирования, документы) средства размещения. Эта информация отображается в модуле TL: WebPMS в разделе "Профили гостей".

Searches guest profiles by name, phone or room number.

path Parameters
propertyId
required
string
Example: 5431

Property Identifier

query Parameters
phone
string
Example: phone=91390

Partial phone number to match

roomName
string
Example: roomName=111

Room/suite display name.

name
string
Example: name=Jo

Partial first or last name to match

languageCode
string
Example: languageCode=en

ISO 639-1 language code. Supported: en, ru, bg, cs, fr, id, ka, km, ko, pl, th, tr, uk, uz, vi.

maxPageSize
integer <int32>
Example: maxPageSize=100

Maximum number of items to return (<=100)

pageToken
string
Example: pageToken=V2Ugd2lzaCB5b3UgcHJvZHVjdGl2ZSBpbnRlcmFjdGlvbiE=

Pagination token for next page.

Token is in the response if the number of items exceeds the limit.

Send it back to get the next set of items.

If the request contains the token, other parameters passed in the query are ignored.

Responses

Response samples

Content type
application/json
{
  • "warnings": [
    ],
  • "errors": [
    ],
  • "nextPageToken": "b24aRNO0Q0WD2CLexb8G6EnqlYqQTWUdGdkrh9DqjLYBthewTbDErm55sLvB+41A5p8aoDpkA6CG1QCGz63jBOqWcPrwZoHwDLUnPp6HZx4FKcRzBSrItBLY2QpAOWxYZnAF57I8dPg7/fgj/xgWEWT/M9qwM8MNihVJX1twL2jABZ3pG49qjbMJMUpXAHdnFtMNjV1ILwg+WhOXnnHjr+4BdmSTiQMAvo3inEewRRg=",
  • "hasNextPage": true,
  • "guests": [
    ]
}

Retrieves basic loyalty card details for a guest.

path Parameters
propertyId
required
string
Example: 5431

Property Identifier

pmsPersonId
required
string
Example: 4503599627465719

Guest identifier in PMS

query Parameters
maxPageSize
integer <int32>
Example: maxPageSize=100

Maximum number of items to return (<=100)

pageToken
string
Example: pageToken=V2Ugd2lzaCB5b3UgcHJvZHVjdGl2ZSBpbnRlcmFjdGlvbiE=

Pagination token for next page.

Token is in the response if the number of items exceeds the limit.

Send it back to get the next set of items.

If the request contains the token, other parameters passed in the query are ignored.

Responses

Response samples

Content type
application/json
{
  • "warnings": [
    ],
  • "errors": [
    ],
  • "nextPageToken": "b24aRNO0Q0WD2CLexb8G6EnqlYqQTWUdGdkrh9DqjLYBthewTbDErm55sLvB+41A5p8aoDpkA6CG1QCGz63jBOqWcPrwZoHwDLUnPp6HZx4FKcRzBSrItBLY2QpAOWxYZnAF57I8dPg7/fgj/xgWEWT/M9qwM8MNihVJX1twL2jABZ3pG49qjbMJMUpXAHdnFtMNjV1ILwg+WhOXnnHjr+4BdmSTiQMAvo3inEewRRg=",
  • "hasNextPage": true,
  • "loyaltyCards": [
    ]
}

Retrieves a guest profile by its PMS identifier.

path Parameters
propertyId
required
string
Example: 5431

Property Identifier

pmsPersonId
required
string
Example: 4503599627465719

Guest identifier in PMS

query Parameters
languageCode
string
Example: languageCode=en

ISO 639-1 language code. Supported: en, ru, bg, cs, fr, id, ka, km, ko, pl, th, tr, uk, uz, vi.

Responses

Response samples

Content type
application/json
{
  • "warnings": [
    ],
  • "errors": [
    ],
  • "guest": {
    }
}

Retrieves the list of stays for a given guest.

path Parameters
propertyId
required
string
Example: 5431

Property Identifier

pmsPersonId
required
string
Example: 4503599627465719

Guest identifier in PMS

query Parameters
maxPageSize
integer <int32>
Example: maxPageSize=100

Maximum number of items to return (<=100)

pageToken
string
Example: pageToken=V2Ugd2lzaCB5b3UgcHJvZHVjdGl2ZSBpbnRlcmFjdGlvbiE=

Pagination token for next page.

Token is in the response if the number of items exceeds the limit.

Send it back to get the next set of items.

If the request contains the token, other parameters passed in the query are ignored.

Responses

Response samples

Content type
application/json
{
  • "warnings": [
    ],
  • "errors": [
    ],
  • "nextPageToken": "b24aRNO0Q0WD2CLexb8G6EnqlYqQTWUdGdkrh9DqjLYBthewTbDErm55sLvB+41A5p8aoDpkA6CG1QCGz63jBOqWcPrwZoHwDLUnPp6HZx4FKcRzBSrItBLY2QpAOWxYZnAF57I8dPg7/fgj/xgWEWT/M9qwM8MNihVJX1twL2jABZ3pG49qjbMJMUpXAHdnFtMNjV1ILwg+WhOXnnHjr+4BdmSTiQMAvo3inEewRRg=",
  • "hasNextPage": true,
  • "roomStays": [
    ]
}

Updates guest’s identity document details.

path Parameters
propertyId
required
string
Example: 5431

Property Identifier

pmsPersonId
required
string
Example: 4503599627465719

Guest identifier in PMS

Request Body schema:

request

series
string or null

Document series (1–64 alphanumeric)

number
string or null

Document number (1–64 alphanumeric)

effectiveDate
string or null

Issue date in ISO-8601 YYYY-MM-DD format

expiryDate
string or null

Expiry date in ISO-8601 YYYY-MM-DD format

departmentCode
string or null

Issuing authority subdivision code (max 16 chars)

issueAuthority
string or null

Full issuing authority name (max 2048 chars)

type
string
Enum: "ForeignPassport" "InternationalPassportBiometric" "InternationalPassport" "TemporaryPassport" "BirthCertificate" "Diplomatic" "BirthCertificateForeign" "MilitaryOfficer" "ForeignPassportForeign" "Another" "DiplomaticForeign" "TemporaryResidence" "Residence" "TemporaryRefuge" "Cis" "WorkPassport" "ResidenceStateless" "NationalPassport" "KazPassport" "ResidenceStatelessBiometric" "TemporaryResidenceStateless" "TemporaryResidenceStatelessBlank" "Patent" "DriverLicense" "PersonalCard" "Passport"

Document type (required parameter) New values can be added (enum is not frozen).

  • ForeignPassport: International passport
  • InternationalPassportBiometric: International passport with biometrics
  • InternationalPassport: International passport of a Russian Federation citizen
  • TemporaryPassport: Temporary passport
  • BirthCertificate: Birth certificate
  • Diplomatic: Diplomatic passport of a Russian Federation citizen
  • BirthCertificateForeign: Foreign birth certificate
  • MilitaryOfficer: Officer ID card
  • ForeignPassportForeign: International passport issued outside the Russian Federation
  • Another: Another identity document
  • DiplomaticForeign: Diplomatic passport of a foreign citizen
  • TemporaryResidence: Temporary residence permit for a foreign citizen
  • Residence: Residence permit of a foreign citizen
  • TemporaryRefuge: Certificate of temporary refuge on the territory of the Russian Federation
  • Cis: Identity card of a citizen of CIS member states
  • WorkPassport: Service passport
  • ResidenceStateless: Residence permit of a stateless person
  • NationalPassport: National foreign passport
  • KazPassport: Identity card of a citizen of the Republic of Kazakhstan
  • ResidenceStatelessBiometric: Residence permit of a stateless person with biometrics
  • TemporaryResidenceStateless: Temporary residence permit of a stateless person (stamp)
  • TemporaryResidenceStatelessBlank: Temporary residence permit of a stateless person (blank)
  • Patent: Patent
  • DriverLicense: Driver license
  • PersonalCard: Identity card
  • Passport: Passport

Responses

Request samples

Content type
{
  • "series": "5000",
  • "number": "999999",
  • "effectiveDate": "2020-11-11",
  • "expiryDate": "2040-12-22",
  • "departmentCode": "1234",
  • "issueAuthority": "Some authority",
  • "type": "ForeignPassport"
}

Response samples

Content type
application/json
{
  • "warnings": [
    ],
  • "errors": [
    ]
}

Updates guest's place of birth details.

path Parameters
propertyId
required
string
Example: 5431

Property Identifier

pmsPersonId
required
string
Example: 4503599627465719

Guest identifier in PMS

Request Body schema:

request

countryCode
string or null

ISO 3166-1 alpha-3 code of birth country

Responses

Request samples

Content type
{
  • "countryCode": "ARG"
}

Response samples

Content type
application/json
{
  • "warnings": [
    ],
  • "errors": [
    ]
}

Uploads guest’s identity document scan files.

path Parameters
propertyId
required
string
Example: 5431

Property Identifier

pmsPersonId
required
string
Example: 4503599627465719

Guest identifier in PMS

Request Body schema:

request

Array of objects or null (PmsApi_FileInfo)

Details of files to upload

Array
content
string or null

File contents in Base64 (max 2 MB)

name
string or null

File name with extension.

Supported file extensions: ".pdf", ".jpg", ".jpeg", ".png", ".gif".

Responses

Request samples

Content type
{
  • "files": [
    ]
}

Response samples

Content type
application/json
{
  • "warnings": [
    ],
  • "errors": [
    ]
}

PropertyReservation

Swagger

Read Reservation API позволяет получить информацию о бронированиях средств размещения из модуля TL: WebPMS.

Получение краткой информации по бронированиям

Метод возвращает постраничный список с краткой информацией по каждому бронированию.

  • Параметр pageToken позволяет продолжить получение списка. Его значение берется из результатов предыдущего запроса. Срок службы токена не ограничен. Запрос может вернуть полученное ранее, но уже изменившееся бронирование.
  • Признак hasNextPage = false информирует о достижении конца списка. Даже после этого запросы продолжения будут возвращать новые данные, появившиеся с момента предыдущего запроса.

Если произойдет потеря pageToken, рекомендуется выполнить новый запрос для получения нового pageToken.

Получение деталей бронирования

Метод возвращает детальную информацию по одному бронированию.

В ответе есть идентификаторы, которые позволяют получить информацию:

  • Через ContentApi:

    • reservation.roomStays[].roomType - категория номеров.
    • reservation.roomStays[].options[] - услуги.

  • Через PMS API > PropertyRoom:

    • reservation.roomStays[].room - комнаты.

  • Через PMS API > PropertyGuest:

    • reservation.roomStays[].guestIds - гости.

Сохранение платежа в проживание

Метод позволяет сложить платёж в проживание по идентификатору проживания pmsRoomStayId, который можно получить в деталях бронирования через PMS API > PropertyReservation.

Входящие данные:

  • pmsPaymentSystemId - Способ оплаты. Необходимо указать один из доступных способов, которые можно получить через GET /v2/properties/{propertyId}/reservations/{number}/room-stays/{pmsRoomStayId}/find-available-payment-systems

Retrieves reservation details by reservation number.

path Parameters
propertyId
required
string
Example: 5431

Property Identifier

number
required
string
Example: 22200222-111-99999999

Reservation number

query Parameters
languageCode
string
Example: languageCode=en

ISO 639-1 language code. Supported: en, ru, bg, cs, fr, id, ka, km, ko, pl, th, tr, uk, uz, vi.

Responses

Response samples

Content type
application/json
{
  • "warnings": [
    ],
  • "errors": [
    ],
  • "reservation": {
    }
}

Searches reservations by parameters; at least one time period must be specified.

path Parameters
propertyId
required
string
Example: 5431

Property Identifier

query Parameters
roomId
string
Example: roomId=4503599627373585

Room/suite identifier

state
required
string
Example: state=Active

Reservation status filter ("Active" or "Cancelled")

startModifyDateTime
string
Example: startModifyDateTime=2024-09-09T11:11

Last modification of the reservation is on or after the specified datetime in ISO-8601 yyyy-MM-ddTHH:mm format, local time.

Limit for "Modify" range is 365 days.

endModifyDateTime
string
Example: endModifyDateTime=2025-09-09T11:11

Last modification of the reservation is on or before the specified datetime in ISO-8601 yyyy-MM-ddTHH:mm format, local time.

Limit for "Modify" range is 365 days.

startAffectPeriodDateTime
string
Example: startAffectPeriodDateTime=2024-09-09T11:11

Stay or part of stay is after the specified datetime in ISO-8601 yyyy-MM-ddTHH:mm format, local time.

Limit for "AffectPeriod" range is 365 days

endAffectPeriodDateTime
string
Example: endAffectPeriodDateTime=2025-09-09T11:11

Stay or part of stay is before the specified datetime in ISO-8601 yyyy-MM-ddTHH:mm format, local time.

Limit for "AffectPeriod" range is 365 days

maxPageSize
integer <int32>
Example: maxPageSize=100

Maximum number of items to return (<=100)

pageToken
string
Example: pageToken=V2Ugd2lzaCB5b3UgcHJvZHVjdGl2ZSBpbnRlcmFjdGlvbiE=

Pagination token for next page.

Token is in the response if the number of items exceeds the limit.

Send it back to get the next set of items.

If the request contains the token, other parameters passed in the query are ignored.

Responses

Response samples

Content type
application/json
{
  • "warnings": [
    ],
  • "errors": [
    ],
  • "nextPageToken": "b24aRNO0Q0WD2CLexb8G6EnqlYqQTWUdGdkrh9DqjLYBthewTbDErm55sLvB+41A5p8aoDpkA6CG1QCGz63jBOqWcPrwZoHwDLUnPp6HZx4FKcRzBSrItBLY2QpAOWxYZnAF57I8dPg7/fgj/xgWEWT/M9qwM8MNihVJX1twL2jABZ3pG49qjbMJMUpXAHdnFtMNjV1ILwg+WhOXnnHjr+4BdmSTiQMAvo3inEewRRg=",
  • "hasNextPage": true,
  • "reservations": [
    ]
}

Searches available rooms for each stay in the reservation.

path Parameters
propertyId
required
string
Example: 5431

Property Identifier

number
required
string
Example: 22200222-111-99999999

Reservation number

query Parameters
maxPageSize
integer <int32>
Example: maxPageSize=100

Maximum number of items to return (<=100)

pageToken
string
Example: pageToken=V2Ugd2lzaCB5b3UgcHJvZHVjdGl2ZSBpbnRlcmFjdGlvbiE=

Pagination token for next page.

Token is in the response if the number of items exceeds the limit.

Send it back to get the next set of items.

If the request contains the token, other parameters passed in the query are ignored.

Responses

Response samples

Content type
application/json
{
  • "warnings": [
    ],
  • "errors": [
    ],
  • "nextPageToken": "b24aRNO0Q0WD2CLexb8G6EnqlYqQTWUdGdkrh9DqjLYBthewTbDErm55sLvB+41A5p8aoDpkA6CG1QCGz63jBOqWcPrwZoHwDLUnPp6HZx4FKcRzBSrItBLY2QpAOWxYZnAF57I8dPg7/fgj/xgWEWT/M9qwM8MNihVJX1twL2jABZ3pG49qjbMJMUpXAHdnFtMNjV1ILwg+WhOXnnHjr+4BdmSTiQMAvo3inEewRRg=",
  • "hasNextPage": true,
  • "availableRoomForRoomStays": [
    ]
}

Assigns room/suite for each stay in the reservation.

path Parameters
propertyId
required
string
Example: 5431

Property Identifier

number
required
string
Example: 22200222-111-99999999

Reservation number

Request Body schema:

request

Array
pmsRoomStayId
string or null

Stay identifier in PMS

roomId
string or null

Room or suite identifier

Responses

Request samples

Content type
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "warnings": [
    ],
  • "errors": [
    ]
}

Assigns the actual check-in time for a stay.

path Parameters
propertyId
required
string
Example: 5431

Property Identifier

number
required
string
Example: 22200222-111-99999999

Reservation number

pmsRoomStayId
required
string
Example: 4503599628227391

Room stay identifier in PMS

Request Body schema:

request

actualCheckInDateTime
string or null

Actual check-in date and time in ISO-8601 YYYY-MM-DDThh:mm format, local time

Responses

Request samples

Content type
{
  • "actualCheckInDateTime": "2024-07-11T14:00"
}

Response samples

Content type
application/json
{
  • "warnings": [
    ],
  • "errors": [
    ]
}

Assigns the actual check-out time for a stay.

path Parameters
propertyId
required
string
Example: 5431

Property Identifier

number
required
string
Example: 22200222-111-99999999

Reservation number

pmsRoomStayId
required
string
Example: 4503599628227391

Room stay identifier in PMS

Request Body schema:

request

actualCheckOutDateTime
string or null

Actual check-out date and time in ISO-8601 YYYY-MM-DDThh:mm format, Local time

Responses

Request samples

Content type
{
  • "actualCheckOutDateTime": "2024-07-11T14:00"
}

Response samples

Content type
application/json
{
  • "warnings": [
    ],
  • "errors": [
    ]
}

Retrieves available payment methods for a stay.

path Parameters
propertyId
required
string
Example: 5431

Property Identifier

number
required
string
Example: 22200222-111-99999999

Reservation number

pmsRoomStayId
required
string
Example: 4503599628227391

Room stay identifier in PMS

query Parameters
action
string
Enum: "Payment" "Refund"
Example: action=Payment

Transaction type ("Payment" or "Refund")

languageCode
string
Example: languageCode=en

ISO 639-1 language code. Supported: en, ru, bg, cs, fr, id, ka, km, ko, pl, th, tr, uk, uz, vi.

maxPageSize
integer <int32>
Example: maxPageSize=100

Maximum number of items to return (<=100)

pageToken
string
Example: pageToken=V2Ugd2lzaCB5b3UgcHJvZHVjdGl2ZSBpbnRlcmFjdGlvbiE=

Pagination token for next page.

Token is in the response if the number of items exceeds the limit.

Send it back to get the next set of items.

If the request contains the token, other parameters passed in the query are ignored.

Responses

Response samples

Content type
application/json
{
  • "warnings": [
    ],
  • "errors": [
    ],
  • "nextPageToken": "b24aRNO0Q0WD2CLexb8G6EnqlYqQTWUdGdkrh9DqjLYBthewTbDErm55sLvB+41A5p8aoDpkA6CG1QCGz63jBOqWcPrwZoHwDLUnPp6HZx4FKcRzBSrItBLY2QpAOWxYZnAF57I8dPg7/fgj/xgWEWT/M9qwM8MNihVJX1twL2jABZ3pG49qjbMJMUpXAHdnFtMNjV1ILwg+WhOXnnHjr+4BdmSTiQMAvo3inEewRRg=",
  • "hasNextPage": true,
  • "paymentSystems": [
    ]
}

Processes a payment for a stay.

path Parameters
propertyId
required
string
Example: 5431

Property Identifier

number
required
string
Example: 22200222-111-99999999

Reservation number

pmsRoomStayId
required
string
Example: 4503599628227391

Room stay identifier in PMS

Request Body schema:

request

actionDateTime
string or null

Action date and time in ISO-8601 YYYY-MM-DDThh:mm format, local time

pmsPaymentSystemId
string or null

Payment system ID in PMS

object or null

Total amount

comment
string or null

Payment comment

Responses

Request samples

Content type
{
  • "actionDateTime": "2024-07-11T14:00",
  • "pmsPaymentSystemId": "0oHjfSIZS0ng==",
  • "total": {
    },
  • "comment": "Payment for something"
}

Response samples

Content type
application/json
{
  • "warnings": [
    ],
  • "errors": [
    ]
}

Processes a refund for a stay.

path Parameters
propertyId
required
string
Example: 5431

Property Identifier

number
required
string
Example: 22200222-111-99999999

Reservation number

pmsRoomStayId
required
string
Example: 4503599628227391

Room stay identifier in PMS

Request Body schema:

request

actionDateTime
string or null

Action date and time in ISO-8601 YYYY-MM-DDThh:mm format, local time

pmsPaymentSystemId
string or null

Payment system ID in PMS

object or null

Total amount

comment
string or null

Payment comment

Responses

Request samples

Content type
{
  • "actionDateTime": "2024-07-11T14:00",
  • "pmsPaymentSystemId": "0oHjfSIZS0ng==",
  • "total": {
    },
  • "comment": "Payment for something"
}

Response samples

Content type
application/json
{
  • "warnings": [
    ],
  • "errors": [
    ]
}

Assigns a room for a stay.

path Parameters
propertyId
required
string
Example: 5431

Property Identifier

number
required
string
Example: 22200222-111-99999999

Reservation number

pmsRoomStayId
required
string
Example: 4503599628227391

Room stay identifier in PMS

Request Body schema:

request

roomId
string or null

Room or suite identifier

Responses

Request samples

Content type
{
  • "roomId": "4503599627373585"
}

Response samples

Content type
application/json
{
  • "warnings": [
    ],
  • "errors": [
    ]
}

Retrieves all invoices related to a reservation.

path Parameters
propertyId
required
string
Example: 5431

Property Identifier

number
required
string
Example: 22200222-111-99999999

Reservation number

query Parameters
languageCode
string
Example: languageCode=en

ISO 639-1 language code. Supported: en, ru, bg, cs, fr, id, ka, km, ko, pl, th, tr, uk, uz, vi.

maxPageSize
integer <int32>
Example: maxPageSize=100

Maximum number of items to return (<=100)

pageToken
string
Example: pageToken=V2Ugd2lzaCB5b3UgcHJvZHVjdGl2ZSBpbnRlcmFjdGlvbiE=

Pagination token for next page.

Token is in the response if the number of items exceeds the limit.

Send it back to get the next set of items.

If the request contains the token, other parameters passed in the query are ignored.

Responses

Response samples

Content type
application/json
{
  • "warnings": [
    ],
  • "errors": [
    ],
  • "nextPageToken": "b24aRNO0Q0WD2CLexb8G6EnqlYqQTWUdGdkrh9DqjLYBthewTbDErm55sLvB+41A5p8aoDpkA6CG1QCGz63jBOqWcPrwZoHwDLUnPp6HZx4FKcRzBSrItBLY2QpAOWxYZnAF57I8dPg7/fgj/xgWEWT/M9qwM8MNihVJX1twL2jABZ3pG49qjbMJMUpXAHdnFtMNjV1ILwg+WhOXnnHjr+4BdmSTiQMAvo3inEewRRg=",
  • "hasNextPage": true,
  • "invoices": [
    ]
}

PropertyRoom

Swagger

Методы позволяют искать и извлекать информацию о номерах, содержащихся в номерном фонде средства размещения. Эта информация отображается в модуле TL: WebPMS в разделе "Номерной фонд".

Retrieves the list of rooms/suites for a property.

path Parameters
propertyId
required
string
Example: 5431

Property Identifier

query Parameters
roomTypeId
string
Example: roomTypeId=315367

Room type identifier

maxPageSize
integer <int32>
Example: maxPageSize=100

Maximum number of items to return (<=100)

pageToken
string
Example: pageToken=V2Ugd2lzaCB5b3UgcHJvZHVjdGl2ZSBpbnRlcmFjdGlvbiE=

Pagination token for next page.

Token is in the response if the number of items exceeds the limit.

Send it back to get the next set of items.

If the request contains the token, other parameters passed in the query are ignored.

Responses

Response samples

Content type
application/json
{
  • "warnings": [
    ],
  • "errors": [
    ],
  • "nextPageToken": "b24aRNO0Q0WD2CLexb8G6EnqlYqQTWUdGdkrh9DqjLYBthewTbDErm55sLvB+41A5p8aoDpkA6CG1QCGz63jBOqWcPrwZoHwDLUnPp6HZx4FKcRzBSrItBLY2QpAOWxYZnAF57I8dPg7/fgj/xgWEWT/M9qwM8MNihVJX1twL2jABZ3pG49qjbMJMUpXAHdnFtMNjV1ILwg+WhOXnnHjr+4BdmSTiQMAvo3inEewRRg=",
  • "hasNextPage": true,
  • "rooms": [
    ]
}

PropertyAnalytics

Swagger

PMS Analytics API позволяет получать ежедневную статистику из модуля TL: WebPMS.

Получение ежедневной статистики заполняемости

Метод возвращает ежедневную статистику по указанному периоду для средства размещения.

  • Диапазон дат ограничен 31 днём. Параметры startStayDate и endStayDate обязательны и задаются в формате ISO-8601 (YYYY-MM-DD).
  • Опциональный параметр otbDate позволяет отфильтровать историческую статистику только по бронированиям, созданным на указанную дату (OTB — On-the-Books).

Поля ответа:

  • currencyCode — код валюты (ISO-4217)
  • propertyRoomCount — общее количество номеров, существующих в отеле согласно паспорту средства размещения
  • dailyOccupancies — ежедневная статистика:
    • date — дата
    • occupancyRate — коэффициент загрузки отеля (0.0–1.0, где 1.0 = 100%)
    • closedRoomCount — номера не в эксплуатации (ремонт, консервация)
    • occupancyRoomCount — занятые номера (включает только платные, номера с нулевой стомостью не включает)
    • complimentaryOccupancyRoomCount — занятые номера с нулевой стоимостью
    • roomRevenue — чистая выручка по номерам (без НДС, комиссий, доп. услуг)
    • revenue — валовая выручка отеля за день
    • mealRevenue — выручка по питанию
    • arrivalCount — количество заездов за дату
    • guestCount — количество гостей (взрослые + дети)

Retrieves daily occupancy statistics for a property.

path Parameters
propertyId
required
string
Example: 5431

Property Identifier

query Parameters
startStayDate
required
string <date>
Example: startStayDate=2026-01-01

Start date of the stay period for reported statistics (ISO-8601 format YYYY-MM-DD). Limit for date range is 31 days

endStayDate
required
string <date>
Example: endStayDate=2026-01-25

End date of the stay period for reported statistics. (ISO-8601 format YYYY-MM-DD). Limit for date range is 31 days

otbDate
string <date>
Example: otbDate=2025-01-15

Optional OTB (On-the-Books) snapshot date. If specified, the historical statistics will be filtered based solely on the booking creation date

Responses

Response samples

Content type
application/json
{
  • "warnings": [
    ],
  • "errors": [
    ],
  • "currencyCode": "RUB",
  • "propertyRoomCount": 90,
  • "dailyOccupancies": [
    ]
}

Bookings

Swagger

Раздел Bookings предоставляет данные о бронированиях, синхронизированных из внешней АСУ средства размещения. PMS Integration Storage API выступает зеркалом данных АСУ: он хранит снимки броней и уведомляет интегратора об их изменениях.

При создании или изменении брони во внешней АСУ публикуется событие pms_integration_storage:booking_changed с идентификаторами propertyId и reservationId. Получив событие, интегратор запрашивает детали брони по конечной точке ниже, передавая значение reservationId как bookingId в пути запроса.

Статусы бронирования

Статус брони указан в поле status:

  • Confirmed: подтверждена.
  • Waitlisted: в листе ожидания.
  • InHouse: гость заселён.
  • CheckedOut: гость выехал.
  • Cancelled: отменена.
  • Unknown: статус не определён.

Набор значений открытый — в новых версиях возможны дополнительные статусы.

Структура брони

Бронирование (Booking) содержит одно или несколько проживаний (roomStays). Каждое проживание описывает:

  • roomTypes — категории номеров, применимые к проживанию.
  • ratePlans — применимые тарифы.
  • inventoryBlocks — блоки квот, если проживание относится к выделенному блоку.
  • roomRates — суточная разбивка цены. Каждая запись ссылается на элементы roomTypes, ratePlans и inventoryBlocks по полю index.
  • services — дополнительные услуги (питание, трансфер и т. п.).
  • guestCounts — количество гостей с разбивкой по возрастным категориям (AdultBed, ChildBandBed).
  • stayDates — даты заезда и выезда, а также фактическое время заезда и выезда, если они уже произошли.

Денежные суммы (total, roomRevenues) указаны в одной валюте (currencyCode по ISO-4217); поле amountAfterTax содержит сумму после налогов.

Идентификаторы брони во внешних системах перечислены в uniqueIds. Поле idContext позволяет различать источник идентификатора (Pms, Internal, External).

Конечная точка

GET /v1/properties/{propertyId}/bookings/{bookingId}

Получение деталей бронирования. Значение bookingId поступает в payload события pms_integration_storage:booking_changed в поле reservationId.

Параметры:

  • propertyId (string, path): ID средства размещения.
  • bookingId (string, path): ID брони в PMS Integration Storage API.

Пример:

GET /v1/properties/2490/bookings/606541

{
  "booking": {
    "id": "606541",
    "status": "Confirmed",
    "propertyId": "2490",
    "uniqueIds": [
      { "id": "RES-12345", "idContext": "Pms" }
    ],
    "bookingChannels": [
      {
        "code": "TA001",
        "codeType": "Pms",
        "name": "Booking.com",
        "bookingChannelType": "TravelAgent"
      }
    ],
    "roomStays": [
      {
        "index": 1,
        "sourceOfBusiness": "WEB",
        "marketCode": "LEISURE",
        "roomTypes": [
          { "index": 0, "pmsSideCode": "STD" }
        ],
        "ratePlans": [
          { "index": 0, "pmsSideCode": "BAR" }
        ],
        "inventoryBlocks": [],
        "roomRates": [
          {
            "stayDate": "2024-03-27",
            "roomTypeIndex": 0,
            "ratePlanIndex": 0,
            "inventoryBlockIndex": null,
            "total": { "amountAfterTax": 5000, "currencyCode": "RUB" }
          }
        ],
        "services": [
          {
            "quantity": 1,
            "pmsSideCode": "BRKF",
            "name": "Breakfast",
            "startDate": "2024-03-27",
            "durationStayUnits": 3,
            "total": { "amountAfterTax": 30, "currencyCode": "RUB" },
            "inclusive": true
          }
        ],
        "guestCounts": [
          { "ageQualifyingCode": "AdultBed", "count": 2, "age": null }
        ],
        "stayDates": {
          "arrivalDateTime": "2024-03-27T14:00:00",
          "departureDateTime": "2024-03-30T12:00:00",
          "actualCheckInDateTime": null,
          "actualCheckOutDateTime": null
        }
      }
    ],
    "total": { "amountAfterTax": 15000, "currencyCode": "RUB" },
    "guaranteeInfo": { "guaranteeCode": "CC" },
    "pmsSideCreateDateTime": "2024-03-20T10:30:00",
    "pmsSideUpdateDateTime": "2024-03-27T16:45:00",
    "updateDateTime": "2024-03-27T13:45:00Z",
    "cancellationInfo": null,
    "roomRevenues": [
      {
        "stayDate": "2024-03-27",
        "amount": { "amountAfterTax": 5000, "currencyCode": "RUB" }
      }
    ]
  }
}

Retrieves booking details. The bookingId is obtained from a pms_integration_storage:booking_changed webhook event.

path Parameters
propertyId
required
string
Example: 2490

Property ID

bookingId
required
string
Example: 606541

Booking id

Responses

Response samples

Content type
application/json
{
  • "booking": {
    }
}

Inventory

Swagger

Раздел Inventory предоставляет данные о доступности номеров и блоках квот, синхронизированных из внешней АСУ средства размещения. Платформа TravelLine публикует событие об изменениях, а интегратор по этим событиям запрашивает актуальные данные через REST.

Две сущности

Раздел оперирует двумя независимыми сущностями:

  • Ежедневный инвентарь (DailyRoomTypeInventory) — фактическая доступность номеров по категориям на конкретную дату:

    • physicalRoomCount — общее число физических номеров категории.
    • availableRoomCount — число номеров, доступных для продажи.
    • outOfOrderRoomCount — число номеров, выведенных из продажи (ремонт, профилактика и т. п.).

    Изменения публикуются событием pms_integration_storage:inventory_changed с диапазоном дат и кодами категорий, для которых нужно перечитать данные.

  • Блок инвентаря (InventoryBlock) — выделенная квота с привязкой к набору тарифов (ratePlanCodes), суточной разбивкой (dailyItems) и опциональным ценообразованием (pricing). Используется для групповых бронирований, корпоративных квот и обмена с каналами продаж.

    Изменения публикуются событием pms_integration_storage:inventory_block_changed.

Статусы блока

Статус блока (blockStatus) принимает одно из значений:

  • Inquiry: предварительный запрос — блок зарезервирован, но не подтверждён.
  • Active: активный, доступен для реализации.
  • Cancelled: отменён.
  • Unknown: статус не определён.

Набор значений открытый — в новых версиях возможны дополнительные статусы.

Конечная точка: поиск инвентаря

POST /v1/properties/{propertyId}/inventories/search

Возвращает ежедневный инвентарь по заданным категориям номеров и диапазону дат.

Параметры:

  • propertyId (string, path): ID средства размещения.

Тело запроса (SearchInventoryRequest):

Параметр Тип Обязательный Описание
roomTypeCodes string[] Да Коды категорий номеров на стороне PMS.
startDate string (date) Да Начало периода (включительно) в формате ISO-8601 yyyy-MM-dd.
endDate string (date) Да Конец периода (включительно) в формате ISO-8601 yyyy-MM-dd.

Максимальная длина периода — 2 года.

Пример:

POST /v1/properties/2490/inventories/search

{
  "roomTypeCodes": ["DBL", "SGL"],
  "startDate": "2026-03-15",
  "endDate": "2026-03-17"
}

Ответ:

{
  "inventory": {
    "propertyId": "2490",
    "inventories": [
      {
        "roomTypeCode": "DBL",
        "date": "2026-03-15",
        "physicalRoomCount": 50,
        "availableRoomCount": 25,
        "outOfOrderRoomCount": 2,
        "updateDateTime": "2026-03-15T14:30:00Z"
      },
      {
        "roomTypeCode": "DBL",
        "date": "2026-03-16",
        "physicalRoomCount": 50,
        "availableRoomCount": 18,
        "outOfOrderRoomCount": 2,
        "updateDateTime": "2026-03-15T14:30:00Z"
      },
      {
        "roomTypeCode": "SGL",
        "date": "2026-03-15",
        "physicalRoomCount": 20,
        "availableRoomCount": 12,
        "outOfOrderRoomCount": 0,
        "updateDateTime": "2026-03-15T14:30:00Z"
      }
    ]
  }
}

Конечная точка: блок инвентаря

GET /v1/properties/{propertyId}/inventories/blocks/{inventoryBlockId}

Получение деталей блока квот. Значение inventoryBlockId поступает в payload события pms_integration_storage:inventory_block_changed.

Параметры:

  • propertyId (string, path): ID средства размещения.
  • inventoryBlockId (string, path): ID блока в PMS Integration Storage API.

Пример:

GET /v1/properties/2490/inventories/blocks/12345

{
  "inventoryBlock": {
    "id": "12345",
    "propertyId": "2490",
    "pmsSideId": "BLK-001",
    "pmsSideCode": "QUOTA-2024",
    "blockStatus": "Active",
    "ratePlanCodes": ["BAR", "GROUP"],
    "pmsSideCreateDateTime": "2026-02-15T10:00:00",
    "pmsSideCancelDateTime": null,
    "updateDateTime": "2026-03-15T14:30:00Z",
    "dailyItems": [
      {
        "date": "2026-03-15",
        "roomTypeCode": "DBL",
        "blockedCount": 10,
        "realizedCount": 3,
        "cutoffDate": "2026-03-10",
        "pricing": {
          "oneAdultPrice": 5500,
          "servicesPrice": 1200,
          "currencyCode": "RUB"
        }
      },
      {
        "date": "2026-03-16",
        "roomTypeCode": "DBL",
        "blockedCount": 10,
        "realizedCount": 2,
        "cutoffDate": "2026-03-10",
        "pricing": {
          "oneAdultPrice": 5500,
          "servicesPrice": 1200,
          "currencyCode": "RUB"
        }
      }
    ]
  }
}

Returns PMS inventory filtered by room type codes and date range.

path Parameters
propertyId
required
string
Example: 2490

Property ID

Request Body schema:
required

Search filters: room type codes and date range

roomTypeCodes
required
Array of strings

Room type codes to filter by (PMS codes).

startDate
required
string <date>

Start date of the search range (inclusive) in ISO-8601 yyyy-MM-dd format, property local time. Maximum date range is 2 years.

endDate
required
string <date>

End date of the search range (inclusive) in ISO-8601 yyyy-MM-dd format, property local time. Maximum date range is 2 years.

Responses

Request samples

Content type
{
  • "roomTypeCodes": [
    ],
  • "startDate": "2026-01-01",
  • "endDate": "2026-12-31"
}

Response samples

Content type
application/json
{
  • "inventory": {
    }
}

Retrieves inventory block details. The inventoryBlockId is obtained from a pms_integration_storage:inventory_block_changed webhook event.

path Parameters
propertyId
required
string
Example: 2490

Property ID

inventoryBlockId
required
string
Example: 12345

Inventory block id

Responses

Response samples

Content type
application/json
{
  • "inventoryBlock": {
    }
}

Statistics

Swagger

Раздел Statistics предоставляет агрегированные показатели по бронированиям, синхронизированным из внешней АСУ. Используется для аналитики загрузки и эффективности тарифов.

В отличие от Bookings и Inventory, методы раздела вызываются по требованию и не связаны с вебхук-уведомлениями.

Единицы проживания

Единица проживания — это минимальная учётная единица, по которой АСУ рассчитывает стоимость и загрузку. В зависимости от настроек АСУ единицей может быть ночь или день. Значение возвращается как целое число в поле stayUnits.

Конечная точка

GET /v1/properties/{propertyId}/calculate-stay-units

Возвращает суммарное количество забронированных единиц проживания для заданного тарифа и периода. В расчёт попадают брони со статусом Confirmed, InHouse и CheckedOut, у которых даты проживания пересекаются с указанным диапазоном.

Параметры:

Параметр Тип Обязательный Описание
propertyId string (path) Да ID средства размещения.
firstStayDate string (query, date) Да Начало периода (включительно) в формате ISO-8601 yyyy-MM-dd, локальное время средства размещения.
lastStayDate string (query, date) Да Конец периода (включительно) в формате ISO-8601 yyyy-MM-dd, локальное время средства размещения.
pmsSideRatePlanCode string (query) Да Код тарифа на стороне PMS. Чувствителен к регистру.

Пример:

GET /v1/properties/2490/calculate-stay-units?firstStayDate=2025-05-15&lastStayDate=2025-08-15&pmsSideRatePlanCode=BAR1

{
  "stayUnits": 92
}

Calculates the number of booked stay units (days or nights) for a given period and rate plan.

path Parameters
propertyId
required
string
Example: 2490

Property ID

query Parameters
firstStayDate
required
string <date>
Example: firstStayDate=2025-05-15

First date of the period for calculation (inclusive) in ISO-8601 yyyy-MM-dd format, property local time

lastStayDate
required
string <date>
Example: lastStayDate=2025-08-15

Last date of the period for calculation (inclusive) in ISO-8601 yyyy-MM-dd format, property local time

pmsSideRatePlanCode
required
string
Example: pmsSideRatePlanCode=BAR1

Rate plan code from PMS (case-sensitive). Specified rate plan is used to filter bookings for calculation

Responses

Response samples

Content type
application/json
{
  • "stayUnits": 0
}

Reviews

Swagger

Public Reviews API позволяет получить отзывы средств размещения и статистику рейтингов из различных источников (Яндекс, Google, Booking, TripAdvisor и др.).

Эта информация используется для отображения репутации отеля на сайтах партнеров и в системах управления репутацией.

Основные возможности

  1. Получение списка отзывов - постраничный список отзывов с возможностью сортировки по дате или рейтингу
  2. Статистика отзывов - средняя оценка и общее количество отзывов
  3. Справочники - источники отзывов и шкала рейтингов
  4. Переводы - автоматический перевод отзывов на запрашиваемый язык

Кеширование

⚠️ Важно: Метод получения списка отзывов использует серверное кеширование для оптимизации производительности.

Время жизни кеша: 30 секунд

Это означает:

  • Повторные запросы в течение 30 секунд вернут идентичные данные
  • Новые отзывы появятся с задержкой до 30 секунд
  • Изменения существующих отзывов отобразятся с той же задержкой

Пагинация

API использует курсорную пагинацию для эффективной работы с большими объемами данных:

  • Используйте maxPageSize для контроля объема данных за один запрос (максимум 100)
  • Обрабатывайте nextPageToken для получения всех отзывов
  • Проверяйте hasNextPage перед следующим запросом

Авторизация

Все запросы требуют Bearer токен в заголовке Authorization. Токен должен быть действительным и иметь права доступа к указанному средству размещения.

Источники отзывов

API агрегирует отзывы из различных источников:

  • Яндекс.Карты
  • Google Maps
  • Booking.com
  • TripAdvisor
  • Другие платформы

Каждый отзыв содержит информацию об источнике в поле sourceId.

Рейтинговая шкала

Отзывы оцениваются по 10-балльной шкале с категориями:

  • Отлично (8-10) - высокая оценка
  • Очень хорошо (6-8) - оценка выше среднего
  • Хорошо (4-6) - средняя оценка
  • Неплохо (2-4) - оценка ниже среднего
  • Плохо (0-2) - низкая оценка

Переводы

API поддерживает автоматический перевод отзывов на различные языки. Для получения перевода используйте параметр languageCode (IETF BCP-47 формат, например: en, de, fr).

Если перевод доступен, он будет возвращен в поле translatedText.

Returns a paginated list of hotel reviews sorted by date or rating.

path Parameters
propertyId
required
string

Property id

query Parameters
pageToken
string

Opaque token for pagination continuation (optional).

maxPageSize
integer <int32>

Maximum number of reviews to return (optional, default 10, max 100).

sortBy
string

Sort by field: "date" or "rate" (optional, default "date"). Ignore if pageToken contains a non-zero value

sortOrder
string

Sort order: "asc" or "desc" (optional, default "desc"). Ignore if pageToken contains a non-zero value

languageCode
string

Language code (IETF BCP-47, optional). If the review is translated into the provided language, the translation will be returned in the review body.

header Parameters
Authorization
string

Bearer token

Responses

Response samples

Content type
application/json
{
  • "reviews": [
    ],
  • "nextPageToken": "eyJwYWdlIjoyfQ==",
  • "hasNextPage": true
}

Returns stats rating and total reviews count for the hotel.

path Parameters
propertyId
required
string

Property id

header Parameters
Authorization
string

Bearer token

Responses

Response samples

Content type
application/json
{
  • "averageRating": 9.2,
  • "reviewsCount": 3985
}

Returns the list of review sources.

header Parameters
Authorization
string

Bearer token

Responses

Response samples

Content type
application/json
{
  • "sources": [
    ]
}

Reference list of available rating categories and their score boundaries (e.g. excellent, good, poor). Category rating in (MinScore; MaxScore], except for the lowest rating, which can be 0.

header Parameters
Authorization
string

Bearer token

Responses

Response samples

Content type
application/json
{
  • "ratingScale": [
    ]
}