-
Как работать с запросами к API
Swagger — это набор инструментов, которые помогают описывать API. Чтобы было проще разобраться в работе Partner API, мы разместили спецификацию и примеры в Swagger.
Как сделать запрос к API в Swagger
1. Спецификация доступна по ссылке: https://partner.qatl.ru/docs/booking-process/.
2. Пользовательский веб-интерфейс:
3. Чтобы выбрать нужное API из раскрывающегося списка, нажмите на стрелочку в верхнем правом углу:
4. Чтобы начать выполнять запросы, авторизуйтесь с помощью учетных данных для JWT авторизации. Вы их получите на email.
Авторизация происходит через OAuth2.0 (https://oauth.net/2/).
Для работы с API в запросах необходимо передавать JSON Web Token (JWT) — ключ доступа.
Получение JWT происходит через Client credentials flow — авторизацию по секретному ключу приложения.
Для отправки запросов используйте Client ID и Client Secret.
Endpoint авторизации для формирования токена:
- STAGE — https://partner.qatl.ru/auth/token.
- PROD — будут выданы после прохождения сертификации на тестовой среде.
Декодировать токен вы может с помощью: https://jwt.io/
С нашей стороны применяются следующие лимиты на авторизацию: 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. Выполняйте запросы с помощью кодов объектов размещения для тестирования propertyId: 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 — поиска средств размещений по городу/региону/стране.
2. Выберите запрос, который доступен в выбранном API. Например, «Получить информацию о средствах размещения»:
3. Нажмите кнопку «Try it out»:
4. Введите свои данные:
5. Нажмите кнопку «Execute»:
Важно! Перед тем, как выполнить запрос, обратите внимание на описание к параметрам.
6. Если запрос успешно выполнен, то в ответ вы получите код 200 и детальное описание средств размещений:
7. Если произошла ошибка, то вы получите код ошибки и ее описание.
Примеры ошибок:
Код 400 — сервер считает, что вы сделали неверный запрос. Это может произойти, если вы отправили неверные данные:
В этом примере было превышено допустимое число элементов, которое было введено в поле «count».
Код 401 — сервер считает, что произошла ошибка авторизации. Это может произойти, если вы отправили неверные данные:
В этом примере не был введен APIKey.
8. Аналогично выполняются и все остальные запросы к API.
9. Чтобы просмотреть в методе все входящие и исходящие параметры, их типы и описание, нажмите на кнопку Schema:
