ЭДЕЛЬВЕЙС API


Описание и список модулей Веб-клиент

Описание

Модуль веб-клиент это интеграционный модуль который позволяет взаимодействовать с АСУ «Эдельвейс» через программный API или посредством готовых модулей из браузера.

Модули для работников гостиницы

Модули из данного раздела предоставляют возможность работы с некоторыми возможностями АСУ Эдельвейс с удаленного рабочего места и мобильных устройств через современный браузерный интерфейс.

  1. Веб-отчеты - модуль для просмотра отчетов.
  2. Аналитика - модуль для просмотра интерактивных аналитических дашбордов.
  3. Заявки - модуль для работы с заявками для сотрудников из браузера и мобильного телефона.

Модули для разработчиков и интеграторов

Модули из данного раздела предназначены для разработчиков и интеграторов и предоставляют возможность разрабатывать интеграции с АСУ Эдельвейс через программный интерфейс (API) .

  1. API веб бронирований (документация) - REST API для создание бронирований, добавление услуг к бронированию и выполнение оплаты и выполнения других операций.

Описание клиентских модулей

Описание модулей с которыми можно работать из браузера через локальную сеть и сеть интернет.

Описание клиентских модулей

Веб-клиент - модуль Аналитика

Описание

Пользователи АСУ, в том числе и руководители, сталкиваются с потребностью получать актуальную информацию о состоянии дел в отеле, при этом нередко находясь за пределами гостиницы без возможности запуска АСУ.
Система просмотра отчетов АСУ Эдельвейс через веб-интерфейс решает вопрос доступа из любого места, где есть сеть Интернет. 

Работа с модулем аналитика

На следующей странице откроется список аналитических дашбордов.

{9B4E6F93-3624-4C6F-A0D9-667287BD73F0}.png

После нажатия на карточку с названием и описанием аналитического дашборда откроется страница с возможностью посмотреть основные показатели работы отеля.

{A6AF6D4D-AE62-4AA9-994B-EEC774A6B776}.png

Отчет по целевой аудитории показывает сведения о количестве гостей, доходе на гостя, распределение по возрасту и полу, а также другую статистику.

image.png

Описание клиентских модулей

Веб-клиент - модуль Веб-отчеты

Описание

Пользователи АСУ, в том числе и руководители, сталкиваются с потребностью получать актуальную информацию о состоянии дел в отеле, при этом нередко находясь за пределами гостиницы без возможности запуска АСУ.
Система просмотра отчетов АСУ Эдельвейс через веб-интерфейс решает вопрос доступа из любого места, где есть сеть Интернет. 

Особенности

•    Работает через веб-интерфейс (веб-браузер).
•    Используются те же отчетные формы, что и в АСУ.
•    Данные формируются в режиме реального времени.
•    Отчеты сохраняются в истории.
•    Используется та же аутентификация и регламентация доступа, что и в АСУ.
•    Возможность экспорта в форматы PDF, WORD, EXCEL.

Работа с модулем веб-отчеты

Для начала работы с отчетами требуется нажать на пункт меню «Отчеты».

image.png

После нажатия на пункт меню откроется страница с историей сформированных отчетов. В истории можно увидеть все готовые отчеты.

image.png

Для формирования отчета требуется открыть раздел «Все отчеты» со списком отчетов – наименования разделов такие же как в модуле отчеты АСУ «Эдельвейс».

image.png

Отчеты в пределах раздела можно искать по названию или по коду отчета (указан под наименованием).

image.png

Для создания отчета требуется нажать кнопку «Создать» - после чего откроется диалог ввода параметров отчета адаптированный под устройство.

9.jpg

image.png

В процессе создания будет отображаться индикатор загрузки. Можно либо дождаться завершения, либо продолжить работу и посмотреть отчет когда он будет готов.

{A48D3494-BE8A-4576-9F70-772A3E36924D}.png

После готовности отчет отобразиться пользователю.

{D2FDBD95-1F99-4B18-95FA-CB80A0ECA77F}.png

Отчет можно вывести на печать или загрузить в формате PDF.

{0209B412-3665-4A45-AF10-9A3191A6AF8A}.png

{204B6B07-2785-46E6-95CA-7A9D5DCF824A}.png

В процессе формирования отчеты имеют индикатор загрузки, а после завершения индикатор примет вид зеленой галочки который говорит об успешном формировании отчета.

image.png

Отчеты в формате EXCEL и WORD посмотреть нельзя, их потребуется скачать и открыть офисными программами.

image.png

Описание клиентских модулей

Веб-клиент - модуль Заявки

Описание

Пользователи  часто сталкиваются с необходимостью оперативного создания или контроля задач и заявок, при этом нередко находясь за пределами рабочего места без возможности запуска АСУ Эдельвейс. Веб-модуль работы с заявками решает эту задачу, обеспечивая доступ к системе из любой точки, где есть интернет.

Работа с модулем заявки

Для начала работы требуется перейти в раздел меню «Заявки».

{020D8E74-3E77-4DBC-8595-FA32DA113AE3}.png

После открытия модуля отобразится список всех доступных пользователю заявок. Список фильтруется автоматически и зависит от группы, к которой принадлежит пользователь.

{80ECF5E8-1898-46CB-8DC1-C4B9F62CC7CD}.png

Нажав кнопку «Создать» откроется диалог создания заявки. В данном диалоге можно задать название и описание заявки, выбрать её приоритет и срок выполнения.

{7ACC25EF-999F-4052-80CD-E1EAE927D343}.png

Созданную заявку можно будет увидеть в АСУ Эдельвейс в разделе заявок.

image.png

Модуль позволяет редактировать заявки и отмечать их выполнение как через АСУ так и через браузер.

{CE162EFF-446B-4A92-970E-93FF8C83044B}.png

Также можно создать заявку для конкретного бронирование в карточке.

{F02EA122-8C06-47CE-94EF-C66DAC75AA16}.png

Для таких заявок указывается комната, номер бронирования и период проживания.

{2E30FC23-9CBE-4B36-9F8B-8E0937FAEB30}.png

После выполнения задачи можно проставить отметку о исполнении.

{52B11F76-860B-4E32-B024-1A5386766BFB}.png

Отметка также отобразится в АСУ в карточке бронирования.

{313B5F21-B6C3-4EE3-BFD8-F126B0F43B3A}.png

 

Работа с мобильного телефона

Интерфейс модуля адаптирован для корректного отображения на мобильных устройствах. Для навигации используйте кнопку «Меню», расположенную в правом нижнем углу экрана. При нажатии на эту кнопку открывается боковая панель с основными разделами модуля.

{F62C936F-930C-4E49-A63D-1766017E0B3C}.png

Создание новой заявки осуществляется через стандартное диалоговое окно. Для редактирования существующей заявки нажмите на иконку «Карандаш» напротив нужной записи в общем списке.

{410A907C-BCA9-424A-A8B9-C6DEAC64DAA6}.png

Интеграционный модуль API для веб-бронирования


Интеграционный модуль API для веб-бронирования

Настройка каналов для API

Переход в конфигуратор модуля

Для перехода в раздел конфигурирования 

image.png

Если у отеля нет пользовательских модулей - войти можно кнопкой «Перейти в конфигуратор».

image.png

Если у пользователя есть доступные модули - нажмите на иконку «Профиль» в правом верхнем углу, а затем нажмите далее «Перейти в конфигуратор» (требуются права системного администратора).

image.png

Настройка каналов

Перейдите в раздел «Интеграции - Каналы для API».

{52AC6765-A143-4EE3-95EA-85900FB0B606}.png

Чтобы приступить к созданию тарифа или типа номера доступного в API - нажмите «Создать» и выполните настройку.

{B6E007D8-BDAD-4D0A-8ACB-8B42F59C0B25}.png

Настройка параметров выполняется аналогично настройка каналов для TravelLine и других систем бронирования.

Инструкция по настройке каналов: https://help.edelink.ru/books/faq/page/vygruzka-kvot-v-kanaly-bronirovanii

Интеграционный модуль API для веб-бронирования

Коды ошибок API работы с веб-бронированием номеров

Бронирование

POST /v1/wb/reservations

Код ошибки Причина
-1 Нет свободной комнаты запрашиваемого типа
-2 В Эдельвейсе нет категории с запрашиваемым именем
-3 Максимально кол-во взрослых, которые могут проживать в одной комнате, меньше, чем запрашиваемое кол-во взрослых
-4 Максимально кол-во детей, которые могут проживать в одной комнате, меньше, чем запрашиваемое кол-во детей
-5 Не удалось создать резервирование (процедура Create_Reserv вернула ошибку.)
-6 Дата заезда меньше даты выезда
-7 Дата заезда меньше текущей
-8 Интерфейс временно выключен!
-97 Настроено несколько типов комнат с данным идентификатором. Требуется правильно настроить каналы для API.
-98 Тип номера не найден. Требуется правильно настроить каналы для API (указать категории на которые в API возможно создавать бронирования).
-99 Сбой при вызове SQL процедуры.

PUT /v1/wb/reservations/{resnum}

Код ошибки Причина
-1 Нет свободной комнаты запрашиваемого типа
-2 В Эдельвейсе нет категории с запрашиваемым именем
-3 Максимально кол-во взрослых, которые могут проживать в одной комнате, меньше, чем запрашиваемое кол-во взрослых
-4 Максимально кол-во детей, которые могут проживать в одной комнате, меньше, чем запрашиваемое кол-во детей
-5 Не найдено резервирование для модификации
-6 Дата заезда меньше даты выезда
-7 Дата заезда меньше текущей
-8 Интерфейс временно выключен!
-9 Гость проживает. Невозможно продлить в том же номере.
-10 Запрет на модификацию брони!
-97 Настроено несколько типов комнат с данным идентификатором. Требуется правильно настроить каналы для API.
-98 Тип номера не найден.
-99 Сбой при вызове SQL процедуры.

Авторизация и режимы работы с API

Авторизация из локальной сети отеля

Авторизация выполняется от лица пользователя admin – метод авторизации basic.

Документация: http://localhost:5001/api/docs/index.html

Работа выполняется через локальный сервер отеля – задача по администрированию должна решатся системным администратором отеля.

Стандартный путь для обращения к API в локальной сети:

<АДРЕС СЕРВЕРА>/api/<ВЕРСИЯ>/<ЗАПРОС>

Авторизация через облачный интеграционный шлюз

Авторизация выполняется через передачу токена доступа через HTTP заголовок X-Api-Key.

Документация: https://webhub.edelink.ru/integrations/api-docs

Взаимодействие с API выполняется через сеть интернет через облачный сервер по HTTPS.

Предоставление токенов авторизации и подключение отелей выполняется по запросу. Один токен позволяет работать как с одним так и с несколькими отелями.

Стандартный путь для обращения к API через интеграционный шлюз:

 <АДРЕС СЕРВЕРА>/api/gw/{agentId}/<ВЕРСИЯ>/<ЗАПРОС>

Способ возврата ошибок

Для возврата ошибок используется Problem Details – RFC 7807: https://datatracker.ietf.org/doc/html/rfc7807

Человеко-читаемое сообщение об ошибке можно получить из поля detail.

Часть методов может возвращать дополнительные сведения (например, поле appStatusCode которое позволяет получить машино-читаемый код ошибки).

Способ проверки работоспособности сервера

При работе через облачный шлюз проверить работоспособность сервера можно методом ping (GET или POST)

Пример ответа на запрос, когда сервер доступен:

image.png


Системные требования и режимы доступа

Системные требования 

Минимальная допустимая ОС для windows службы: 

Доступ к модулю

Локальная сеть

По умолчанию служба устанавливается с настройкой доступа через порт 5001. 

Доступ к документации API для локального доступа можно получить по ссылке: http://localhost:5001/api/docs/index.html

Облачный доступ

Для обеспечения доступа через облачный шлюз требуется установить службу и связаться со службой технической поддержки.

Ознакомится с документацией к API для облачного доступа можно получить по ссылке: https://webhub.edelink.ru/integrations/api-docs

Настройка доступа к модулю Веб-клиент

1. Предоставление доступа пользователю

После установки модуля он появится в списке модулей в разрешениях пользователя в Конфигураторе.
Требуется выбрать пользователя и предоставить ему доступ к модулю «Веб-клиент».
По умолчанию доступ всех пользователей запрещен.

Обязательно используйте сложный пароль для пользователей, у которых будет доступ к модулю.

image.png

2. Настройка доступа из локальной сети

Этот вариант настройки можно использовать в одном из случаев:

  1. У отеля настроен доступ через VPN и на устройстве руководителя настроен VPN-клиент.
  2. Планируется работа из локальной сети (например, с ноутбука или планшета руководителя) через Wi-Fi отеля. 

В таком случае системному администратору требуется:

  1. Открыть на сервере порт (по умолчанию 5001) для доступа к службе.
  2. Указать в файле appsettings.json (см. пункт 3.2) Url c адресом сервера.
  3. Указать в config.js в папке wwwroot - baseUrl с адресом сервера.

Не рекомендуется предоставлять доступ к порту из сети Интернет.

После этого можно:

  1. Открыть страницу: http://<адрес_сервера>:<порт>.
  2. Ввести имя пользователя, пароль и начать работу через веб-интерфейс.

image.png

3. Настройка доступа из сети Интернет

Данный способ позволит получить доступ к отчетности с любого устройства с доступом в интернет.

Отчеты могут содержать персональные данные гостей.
Рекомендуется сначала рассмотреть способ с доступом из локальной сети или через корпоративный VPN - это проще и безопаснее!

Минимальная настройка:

  1. Требуется публичный (белый) IP-адрес.
  2. Требуется настроить перенаправление портов на сетевом оборудовании на порт на котором установлена служба (по умолчанию 5001)

Через модуль могут передаваться персональные данные - требуется обязательная настройка https:

  1. Требуется купить доменное имя для публичного сервера.
  2. Настроить ААА-запись указывающую на публичный адрес сервера для которого настроено перенаправление портов.
  3. Требуется купить или самостоятельно выписать SSL сертификат для купленного домена.
  4. Настроить сертификат как указано в разделе 3.1 или 3,2.
3.1. Настройка через reverse-proxy (nginx)

Настройка через nginx выполняется стандартными методами.

Требуется установить сертификаты, открыть порты 80 и 443 и задать proxy_pass (режим обратного прокси) на http адрес службы (например http://127.0.0.1:5001). 


3.2. Настройка через Kestrel

По умолчанию в конфигурационном файле appsettings.json заданы настройки:

  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://127.0.0.1:5001"
      }
    }
  },

Для обеспечения доступа по https требуется:

  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://127.0.0.1:5001"
      },
      "Https": {
        "Url": "https://127.0.0.1:5002",
        "Certificate": {
        "Path": "ваш_файл_сертификата.pfx",
        "Password": "пароль_от_вашего_сертификата"
        }
      }
    }
  },

Сертификат можно:

  1. Выписать самостоятельно.
  2. Получить используя win-acme.
  3. Купить у облачного провайдера.

Способы 2 и 3 требуют наличия доменного имени и настроенных А записей.