Как работать с запросами к API

Swagger — это набор инструментов, которые помогают описывать API на основе его кода. API — прикладной программный интерфейс (далее — API). Чтобы было проще разобраться в работе TL: Partner API — инструмент для безопасного обмена данными между компанией и её официальными партнерами, мы разместили спецификацию и примеры в Swagger.

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

1. Спецификация доступна по ссылке: https://partner.qatl.ru/docs/booking-process/.

2. Пользовательский веб-интерфейс:

3. Чтобы выбрать нужное API из раскрывающегося списка, нажмите на стрелочку в верхнем правом углу:

4. Чтобы начать выполнять запросы, авторизуйтесь с помощью учетных данных. Вы их получите на электронную почту.

Авторизация происходит через OAuth2.0 — открытый протокол авторизации (далее — OAuth2.0).

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

Получение JWT происходит через авторизацию по секретному ключу приложения.

Для отправки запросов используйте логин (Client ID) и пароль (Client Secret).

Конечная точка (endpoint) авторизации для формирования токена:

Тестовая среда (Stage).
Рабочая среда (prod) — будут выданы после прохождения сертификации на тестовой среде.

Декодировать токен вы может с помощью сервиса JSON Web Token (JWT) Debugger.

Со стороны TravelLine применяются следующие лимиты на авторизацию: 3 в секунду, 15 в минуту, 300 в час по IP-адресу (идентификатор устройства в интернете).

Для применяя данного типа авторизации необходимо:

кешировать на стороне канала токен доступа (Access Token) и переиспользовать его в запросах;
использовать библиотеки для OAuth2.0.

5. Если вы переключаетесь между API в Swagger, введите учетные данные заново. Если выполняете запросы на своей стороне, то необходимо кешировать на стороне канала токен доступа (Access Token) и переиспользовать его в запросах.

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

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

1. Нажмите кнопку Authorize:

2. Введите полученные учетные данные в блок oAuth2 (OAuth2, clientCredentials):

в поле client_id введите ваш ClientId;
в поле client_secret введите ваш ClientPassword (clientSecret).

3. Нажмите кнопку Authorize.

4. Нажмите кнопку Close, чтобы закрыть окно авторизации.

5. Выполняйте запросы с помощью уникальных идентификаторов средств размещения для тестирования: 7291, 8155, 8156, 8613, 8614, 8615, 8616, 8617, 8618, 8619, 8726, 8745, 8746.

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

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

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

Content API — информация о средствах размещения;
Search API — поиск вариантов размещений;
Reservation API — работа с бронированиями;
Geo API — поиск средств размещений по городу/региону/стране;
ReferenceData API — информация о справочниках.

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

3. Нажмите кнопку Try it out:

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

5. Нажмите кнопку Execute:

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

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

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

Примеры ошибок:

Код 400 — сервер считает, что вы сделали неверный запрос. Это может произойти, если вы отправили неверные данные:

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

Код 403 — сервер считает, что у вас нет доступа к данной гостинице. Это может произойти, если средство размещения остановило работу канала в личном кабинете в разделе «Менеджер каналов».

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

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