Общая информация
Что такое API
API — это инструмент, который позволяет разным программам обмениваться данными. С его помощью можно автоматически передавать информацию из bnovo в другие системы (и наоборот) без ручного копирования.
Какие версии API доступны
В bnovo есть две версии публичного API.
Кому доступен API
Доступ к API зависит от типа аккаунта и тарифа.
Как получить доступ к API
Подробнее о подключении для API v1 (Старт) и API v2 (Профессионал)
Шаг 1. Чтобы подключить API, перейдите на страницу доступа
Путь: Меню → Bnovo Octopus → API-доступ.
Шаг 2. Выберите версию API
На странице выберите нужную версию:
- API v1 (Старт) — только для получение данных;
- API v2 (Профессионал) — полная двухсторонняя синхронизация.
Шаг 3. Заполните анкету
После выбора версии заполните анкету с вопросами о целях использования API.
- Для аккаунтов с типом «Полный продукт» анкета появляется при первом подключении API и будет показываться до тех пор, пока вы не отправите и не нажмёте кнопку «Сгенерировать ключ».
- Для отельеров с тарифом «Максимум» анкета появляется при первом переходе на страницу «API-доступ» и будет показываться до отправки.
Шаг 4. Генерируем API-ключ
После отправки анкеты нажмите «Сгенерировать ключ».
- Полный продукт (старая и новая версия)
- Максимум
Шаг 5. После генерации ключа подключается API v1 (Старт) и становятся доступны:
- почта отеля;
- ID аккаунта (логин);
- API-ключ (пароль);
- ссылка на техническую документацию API.
- Для пользователей с тарифом «Максимум» после генерации ключа сразу подключается API v2. Поэтому пропускаем шаги 5 и 6.
- Для аккаунтов с типом «Полный продукт» по умолчанию подключается API v1.
Шаг 6. Подключение API v2 (Профессионал)
Если выбирали API v2 для аккаунта с типом «Полный продукт», после генерации ключа:
- появляется статус «Ожидает оплаты»;
- в Личном кабинете выставляется счёт.
После оплаты:
- API v2 подключается автоматически;
- статус меняется на «Подключен»;
- отображается срок окончания подписки.
- После смены версии API ключ не меняется.
- При подключении API v2 (Профессионал) система автоматически активирует базовый доступ API v1 (Старт).
- Полный функционал API v2 (Профессионал) становится доступен сразу после оплаты счёта.
Если API уже был подключён ранее
Если у вас уже есть API-доступ, при переходе на страницу:
- отображается существующий API-ключ;
- доступна возможность перейти с бесплатной версии API v1 на платную API v2.
Дополнительно: страница «API-доступ»
На странице «API-доступ» можно:
- скопировать API-ключ;
- обновить API-ключ после первой авторизации;
- Обновите ключ
- Подтвердите обновление
- или обратиться в нашу поддержку.
Работа с API
Все запросы к API требуют токен.
Мы разберём всё по шагам: как получить токен через авторизацию, какие методы доступны в бесплатной и платной версиях, как их использовать и какие есть ограничения.
Первое подключение
Шаг 1.
Для запросов требуется JWT-токен (JSON Web Token).
JWT-токен (JSON Web Token) — это специальный формат токена, который позволяет безопасно передавать данные между клиентом и сервером.
Шаг 2. Чтобы получить JWT, авторизуйтесь по ID аккаунту и паролю, который сгенерирован в интерфейсе. Укажите такие данные:
- id — ID аккаунта
- password — пароль
Шаг 3. В документации можно выбрать шаг авторизации. Из него сразу перейти в клиент для отправки/получения запроса.
Шаг 4. Укажите персональный id и password.
Шаг 5. Нажмите кнопку Send, чтобы отправить запрос.
В ответ система пришлёт bearer access_token — он используется для методов Bnovo PMS.
Доступные методы: для бесплатной версии API v1 (Старт)
В бесплатной версии API v1 доступно два метода из PMS:
- /bookings — список бронирований за выбранный период на шахматке. В ответе будут все статусы.
- /bookings/{id} — данные по конкретному бронированию.
В документации есть примеры ответов для этих методов. Чтобы воспользоваться этими методами, вставьте полученный bearer access_token.
Доступно сохранение токена bearer access_token в общем блоке «Bearer Token» — он будет автоматически подставляться при каждом запросе.
Доступные методы: для версии API v2 (Профессиональный)
Более подробное описание всех параметров, примеры запросов и коды ошибок находятся в полной документации API
Для версии API v2 доступны методы:
- GET
- Получение бронирований в указанный промежуток или по id (доступно и в API v1, и в API v2)
- Получения гостя по id
- Получение информации из бронирования
- Получение информации об отчетах
- Получение списка платежей по бронированию или платежа по id
- Получение цен
- Справочные GET-методы
- PUT
- Обновление статуса бронирования
- Обновления гостя в бронировании
- POST
- Создание нового гостя в бронировании
- Создание счета в бронировании
- Создание платежа в бронировании
- Вебхуки
Уведомления об изменении:- бронирования;
- цен в тарифе.
Пример использования метода
Допустим, нужно получить бронирования за период с 25.06 по 30.06 с помощью метода /bookings.
- Укажите bearer access_token, который выдала система.
- Заполните параметры:
- date_from — начальная дата (в нашем случае 25.06),
- date_to — конечная дата (30.06).
На скрине видно, как это выглядит в интерфейсе.
После этого нажмите «Send» — система вернёт список бронирований из PMS за указанный период.
Ограничения
Коды обработки:
- 200 — Успешно. Данные по бронированию получены.
- 401 — Ошибка авторизации. Токен не передан или недействителен.
- 404 — Метод API, либо какая-то сущность, необходимая для обработки запроса не найдена.
- 406 — Ошибка валидации. В теле ответа — список полей, которые не прошли проверку, с указанием типа ошибки и пояснением. Отправленные параметры тоже возвращаются.
- 500 — Запрос не может быть выполнен по причине внутренней ошибки в API.
Ограничения по количеству запросов:
Для запроса аутентификации /api/v1/auth и обновления API-ключа через интерфейс:
- не более 10 запросов в минуту.
Для всех остальных методов:
- 30 запросов за 10 секунд.
- 300 запросов за 5 минут.
- 1000 запросов в час.
- 10 000 запросов в сутки.
Если лимит превышен — система вернёт ошибку 429 Too Many Requests.
Loading...