Для работы с запросами необходимо авторизоваться на платформе публичных API Exely — Exely Connect.
Процесс авторизации
Авторизация происходит через OAuth2.0.
OAuth 2.0 – это стандарт авторизации, который позволяет приложениям получать доступ к данным.
Для работы с API в запросах необходимо передавать ключ доступа JSON Web Token (JWT).
JWT (JSON Web Token) — это специальный формат токена, который позволяет безопасно передавать данные между клиентом и сервером.
Получение JWT происходит через Client credentials flow, то есть авторизацию по секретному ключу доступа.
Для запроса ключа доступа необходимы параметры: Client ID и Client Secret.
Диаграмма взаимодействия
Exely. Auth Server: https://connect.hopenapi.com/auth/token
Exely. Content API: https://connect.hopenapi.com/api/content/
Access Token
Лимиты на авторизацию: 3 в секунду, 15 в минуту, 300 в час по одному IP-адресу.
Время жизни токена: 15 минут.
Endpoint авторизации: PROD — https://connect.hopenapi.com/auth/token
Пример Access Token:
eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhWF9SYVkxak01LVJzcTYyb3ZUbjd2QVE3MFBraWZHdXIwZW5mdU1XUGFnIn0.eyJleHAiOjE3Mzc2MjY2NjIsImlhdCI6MTczNzYyNTc2MiwianRpIjoiYjcxZTRhODctODM1Ny00NzJlLTg5YTUtNjhjMjA1ZGYwYTkyIiwiaXNzIjoiaHR0cHM6Ly9jb25uZWN0LmhvcGVuYXBpLmNvbS9hdXRoL3JlYWxtcy9Db25uZWN0QXBpIiwiYXVkIjoiRXhlbHkuQ29ubmVjdEFwaSIsInN1YiI6ImY0MjRkOWY4LWYzMWYtNDgxMy1hMjY5LWYyMmY4ZTgzZjlkNyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImRlbW9fcGFydG5lciIsInNjb3BlIjoiIiwiYXBpX2FjY2Vzc2VzIjpbImNvbnRlbnQiXX0.F4LxcnCZQ2HhdnXWfDa_lf0eqN3wq1Aq6DnOydnpElfa3QG5qkbU-ejdY6d4fpPJHQM57maxTkWs_rG6ZBi7qcAn8p1YdlXK0J7HT4e52MK3B-09ABO-DtzO4TxVN1z8iUr9mHoNSxIqSA2Nq9h0Z2cLqvvAJpSsaSsHBRCKC1WW6MMu7eSXNk4LKy6aq6h-hPXCzKG70WknukDp7Uiy7P0WVnVM4KMVD2WiS0tCOho4VVuVuLb68bSUqxgo9G5Zp3MiKyinixmgx1x9P5V_GVGDKBpNjuHde0FmlrnAMbrgF6azZUNmOBd19sp09MDnItQu5wDJFQObelTY1fkD9g
На сайте JWT.IO можно расшифровать Access Token.
Пример расшифрованного токена:
PAYLOAD:
{
"exp": 1737626662,
"iat": 1737625762,
"jti": "b71e4a87-8357-472e-89a5-68c205df0a92",
"iss": "https://connect.hopenapi.com/auth/realms/ConnectApi",
"aud": "Exely.ConnectApi",
"sub": "f424d9f8-f31f-4813-a269-f22f8e83f9d7",
"typ": "Bearer",
"azp": "demo_partner",
"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://connect.hopenapi.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 — описание и фотографии средств размещений, категорий номеров, тарифов и услуг;
Read Reservation API — информация о бронированиях средств размещений;
2. Выберите запрос, который доступен в выбранном API. Например, «Получить информацию о средствах размещения»:
3. Нажмите Try it out:
4. Введите свои данные:
5. Нажмите Execute:
Важно: перед тем, как выполнить запрос, обратите внимание на описание параметров.
Если запрос успешно выполнен, в ответ вы получите «Код 200» и детальное описание средств размещений.
Если произошла ошибка, вы получите код ошибки и ее описание. Например:
«Код 400» — неверный запрос.
Может произойти, если вы отправили неверные данные.
В этом примере было превышено допустимое число элементов, которое было введено в поле count.
«Код 401» — ошибка авторизации.
Может произойти, если вы отправили неверные данные авторизации.
Аналогично выполняются и все остальные запросы к API.
Чтобы просмотреть в методе все входящие и исходящие параметры, их типы и описание, нажмите на Schema.
