Skip to main content
API docs by Redocly

Travelline APIs (1.0.0)

Download OpenAPI specification:Download

Авторизация

Авторизация происходит через 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. Auth Server: https://partner.tlintegration.com/auth/token

Access Token

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

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

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

15 минут.

Endpoint авторизации

Пример Access Token:

eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI2OGZjOHRNUGFSUHRyRHYtVHV2WEpncUNGTE1CVGRheTBpQkdJSUE3amxvIn0.eyJleHAiOjE2OTg5MTYwMzYsImlhdCI6MTY5ODkxNTEzNiwianRpIjoiYTJjZGJhMGQtYzQwNy00OWRmLThiNGQtOTJhNTM1NWQxYTFmIiwiaXNzIjoiaHR0cHM6Ly9wYXJ0bmVyLnRsaW50ZWdyYXRpb24uY29tL2F1dGgvcmVhbG1zL1BhcnRuZXJBcGkiLCJhdWQiOiJUcmF2ZWxMaW5lLlBhcnRuZXJBUEkiLCJzdWIiOiI4NmE0YjZiZS0wYTc0LTRjYjktYjNhYi1iNDYyZWUwYmIyYmQiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJwYTMiLCJzY29wZSI6IiIsImFwaV9hY2Nlc3NlcyI6WyJjb250ZW50Il19.Nz6dyaHGyIN5IKv30oM-HrqdQBqaGdzEFrk7ACUWbfvsNCHNowg96iJrGwQbkOUSVPtQJF9Cwf1_jywP6c2UPHclzBIDp9HTsYdVM5QS_k9ecs0GCiI8ACBqld3yatY4dJz3MRkxnU_rp0NbJJQ-uBcmg_9UCSCIc3mKR7UAosr5XOXeb4ckrFd67DK5xfofT0ykE46Qkc6nvev3AGx11fPAVsFnmmPOSnlpQzJTI7XBWbD120q5fDdksVlaiq3YoBueDEeOPFH08Ia6xdTVjIf_zsyOEKt2N8_7BTyWG_3YPThBbgn-eAgybSdeop6_eCrWTfQvX5g8qtR2e9J32A

На сайте JWT.IO можно расшифровать Access Token.

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

PAYLOAD: 

{
  "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"
  ]
}

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

Best Practices

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

  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 со стороны пользователей. Если лимит превышен, ваши действия будут заблокированы. В этом случае вернется ошибка 429 Too Many Requests.

Ограничение Квота Разблокировка при превышении квоты
Количество запросов на авторизацию с одного IP-адреса 3 в секунду Когда число запросов к API, совершенных за последнюю секунду, станет меньше 3

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

В каждом ответе 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 Сервер перегружен. Попробуйте зайти позже.

ExtraStayRules

Swagger

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

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

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

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

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

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

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

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

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

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

Endpoint

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": [
    ]
}

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": null,
  • "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",
  • "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
[
  • {
    }
]

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.

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

Endpoint

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": [
    ]
}

Reservation

Swagger

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

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

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

  • Параметр 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.
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.
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 (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": {
    }
}

PropertyGuest

Swagger

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

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

roomId
string
Example: roomId=4503599627373585

Room/suite identifier

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 (PmsApi_PersonalDocumentType)
Enum: "Passport" "ForeignPassport" "InternationalPassportBiometric" "InternationalPassport" "TemporaryPassport" "BirthCertificate" "Diplomatic" "BirthCertificateForeign" "MilitaryPensioner" "MilitaryReserveOfficer" "MilitarySoldier" "MilitaryOfficer" "PassportSailor" "ForeignPassportForeign" "TemporaryPassportInsteadOfMilitary" "Another" "DiplomaticForeign" "TemporaryResidence" "Residence" "TemporaryRefuge" "Cis" "WorkPassport" "ResidenceStateless" "NationalPassport" "KazPassport" "ResidenceStatelessBiometric" "TemporaryResidenceStateless" "TemporaryResidenceStatelessBlank" "Patent"

Type of personal document New values can be added (enum is not frozen).

  • Passport: Passport
  • 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
  • MilitaryPensioner: Military pension certificate
  • MilitaryReserveOfficer: Reserve officer military identity card
  • MilitarySoldier: Military identity card of a soldier (sailor, sergeant, petty officer)
  • MilitaryOfficer: Officer ID card
  • PassportSailor: Sailor passport
  • ForeignPassportForeign: International passport issued outside the Russian Federation
  • TemporaryPassportInsteadOfMilitary: Temporary identity card issued instead of the military identity card
  • 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

Responses

Request samples

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

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: Web PMS.

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

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

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

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

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

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

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

  • Через ContentApi:

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

  • Через PMS Universal API > Rooms:

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

  • Через PMS Universal API > Guests:

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

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

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

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

  • 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 (PmsApi_PaymentActionKind)
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 identifier

object (PmsApi_Amount)

Amount with currency

comment
string or null

Payment comment

Responses

Request samples

Content type
{
  • "actionDateTime": "2024-07-11T14:00",
  • "pmsPaymentSystemId": "CASHLESS",
  • "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 identifier

object (PmsApi_Amount)

Amount with currency

comment
string or null

Payment comment

Responses

Request samples

Content type
{
  • "actionDateTime": "2024-07-11T14:00",
  • "pmsPaymentSystemId": "CASHLESS",
  • "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": [
    ]
}

Property

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: Web PMS в разделе "Справочник компаний".

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": [
    ]
}

PropertyRoom

Swagger

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

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": [
    ]
}

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-02-19",
  • "departureDate": "2026-02-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-02-19

Check-in date.
Format complies with ISO-8601 YYYY-MM-DD

departureDate
required
string
Example: departureDate=2026-02-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

includeExtraStays
boolean
Default: false

Includes extra stay options in search results for all available accommodations

includeExtraServices
boolean
Default: false

Includes extra services options in search results for all available accommodations

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": {
    }
}

Reviews

Swagger

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

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

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

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

Кеширование

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

Время жизни кеша: 10 минут

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

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

Пагинация

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

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

Авторизация

Все запросы требуют Bearer token в заголовке 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": [
    ]
}