Разделы и статьи

Как работать с API

Для работы с запросами необходимо авторизоваться на платформе публичных API TravelLine — Partner API.


Процесс авторизации

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

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

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

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

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

Для запроса ключа доступа необходимы параметры: Client ID и Client Secret.


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


TravelLine. Auth Server: https://partner.tlintegration.com/auth/token

TravelLine. Content API: https://partner.tlintegration.com/api/content/


Access Token

Лимиты на авторизацию: 3 в секунду, 15 в минуту, 300 в час по одному IP-адресу.

Время жизни токена: 15 минут.

Endpoint авторизации: PROD — https://partner.tlintegration.com/auth/token

Пример 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

https://identitymodel.readthedocs.io/en/latest/client/overview.html
Microsoft.Extensions.DependencyInjection


js

https://www.npmjs.com/package/oidc-client?activeTab=readme
https://github.com/IdentityModel/oidc-client-js/wiki


php

https://github.com/jumbojett/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 в Swagger

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

Спецификация и примеры доступны в Swagger.


Чтобы сделать запрос:

1. Выберите нужное API из выпадающего списка.


2. Авторизуйтесь с помощью Client ID и Client Secret.

3. Если вы переключаетесь между API, заново авторизуйтесь.

Работа с API происходит с помощью отправки GET или POST запросов.

При некорректных запросах или проблемах в работе API, возвращается информация об ошибках.


Как авторизоваться в Swagger

1. Нажмите Authorize.


2. Введите параметры Client ID и Client Secret, нажмите Authorize.


3. Затем нажмите Close.


Как сделать запрос к API в Swagger

Описанная ниже последовательность действий применяется для выполнения запроса любого из методов в описании API.

1. Выберите API:

  • Content API — описание и фотографии средств размещений, категорий номеров, тарифов и услуг;

  • Reservation API — информация о бронированиях средств размещений;

2. Выберите запрос, который доступен в выбранном API. Например, «Получить информацию о средствах размещения»:


3. Нажмите Try it out:


4. Введите свои данные:


5. Нажмите Execute:


Важно: перед тем, как выполнить запрос, обратите внимание на описание параметров.

Если запрос успешно выполнен, в ответ вы получите «Код 200» и детальное описание средств размещений.


Если произошла ошибка, вы получите код ошибки и ее описание. Например:

  • «Код 400» — неверный запрос.

Может произойти, если вы отправили неверные данные.


В этом примере было превышено допустимое число элементов, которое было введено в поле count.

  • «Код 401» — ошибка авторизации.

Может произойти, если вы отправили неверные данные авторизации.

Аналогично выполняются и все остальные запросы к API.

Чтобы просмотреть в методе все входящие и исходящие параметры, их типы и описание, нажмите на Schema.


Кейс: как привлечь гостей в отель и сделать их постоянными клиентами

В 2021 году в модуле бронирования TravelLine появилась программа лояльности. Отель «Вега Измайлово» первым тестировал эту фишку. В кейсе расскажем, как отель внедрил программу лояльности на сайте и каких результатов добился.
Узнать больше
Кейс: как привлечь гостей в отель и сделать их постоянными клиентами