Интеграция с Claris: как устроена
Claris — внешний облачный сервис, в котором служба эксплуатации ведёт заявки на парковку. UnSpot умеет создавать в нём заявку автоматически: как только в UnSpot появилась бронь парковочного места, в Claris заводится запись с датой визита, номером и моделью автомобиля. Эта статья отвечает на вопрос «что именно уходит наружу и на каких условиях» — её стоит прочитать службе безопасности до согласования интеграции. Пошаговая настройка — в статье «Настройка интеграции с Claris».
Из чего состоит интеграция
Механизм собран из двух частей, и настраиваются они в разных местах консоли. Работать интеграция начинает только тогда, когда сделаны обе.
| Часть | Где настраивается | Что задаёт |
|---|---|---|
| Подключение к Claris | «Настройка → Интеграции», карточка Claris в блоке «Оборудование» | учётную запись Claris, от имени которой создаются заявки |
| Отправка заявок | «Настройка → Исходящие подписки», подписка на событие «Бронирование создано» | в каких офисах работает отправка |
Если подключения нет, подписка остаётся активной, но заявки не создаются и никакой ошибки не показывается — об этом подробнее в разделе «Когда заявка создаётся и когда нет».
Направление и инициатор обмена
Обмен односторонний: соединение всегда открывает UnSpot, Claris в UnSpot не обращается. Входящие правила на межсетевом экране для этой интеграции не нужны.
| Параметр | Значение |
|---|---|
| Кто инициирует | UnSpot |
| Протокол | HTTPS |
| Адрес авторизации | api.claris.su/main/Token |
| Адрес данных об учётной записи | api.claris.su/main/vNext/v1/users/current |
| Адрес создания заявки | api.claris.su/main/vNext/v1/requests |
| Авторизация запроса | заголовок Authorization с токеном Claris |
| Таймаут запроса | 240 секунд |
Адрес создания заявки UnSpot подставляет сам и запрещает его редактировать — задать вместо Claris другой приёмник через эту опцию нельзя.
Что передаётся в Claris
При появлении брони парковочного места UnSpot отправляет одну заявку со следующим составом полей. Персональные данные и поведение пустых значений указаны отдельно — вторым и третьим столбцом.
| Поле | Что в нём | Когда пусто | ПДн |
|---|---|---|---|
| actualCreationDate | дата и время создания брони | никогда | нет |
| visitDate | дата и время начала брони | никогда | нет |
| arrivalDate | — | всегда | нет |
| departureDate | — | всегда | нет |
| visitorFullName | ФИО гостя, если бронь гостевая; иначе — имя организатора брони, то есть того, для кого она создана | практически никогда: у парковочной брони организатор есть всегда | да |
| carNumber | номер автомобиля в нормализованном виде | если номер не заполнен; при бронировании парковки он обязателен | да |
| carModelText | марка и модель автомобиля, до 50 символов | практически никогда: поле обязательно | да |
| parkingPlace | номер или наименование парковочного места | никогда | нет |
| note | текст поля «Сообщение для приемной», до 255 символов | у всех броней, кроме гостевых: в других случаях поле недоступно | зависит от текста |
| type | код типа заявки в Claris, одинаковый для всех заявок | никогда | нет |
| status | код статуса «создана», одинаковый для всех заявок | никогда | нет |
| author | идентификатор подключённой учётной записи Claris | никогда | нет |
| customer | то же значение, что в author | никогда | нет |
| company | идентификатор компании из учётной записи Claris | никогда | нет |
Четыре уточнения к таблице, каждое из которых меняет то, что увидят в Claris.
- Поля arrivalDate и departureDate всегда уходят пустыми, хотя в форме подписки предпросмотр показывает рядом с ними даты брони. Ориентируйтесь на эту таблицу, а не на предпросмотр: время фактического въезда и выезда UnSpot в Claris не передаёт.
- Имя в поле visitorFullName — это имя организатора, а не того, кто нажал кнопку. Если сотрудник бронирует место коллеге, в Claris уйдёт имя коллеги. Если у сотрудника заполнено «Отображаемое имя», уйдёт оно, а не имя с фамилией. И ещё одна особенность: когда в гостевой брони указан адрес почты, совпадающий с существующим сотрудником, UnSpot делает организатором его, а введённое ФИО гостя стирает — в Claris уйдёт имя сотрудника.
- Номер автомобиля нормализуется перед отправкой: буквы приводятся к верхнему регистру, а кириллические А, В, Е, К, М, Н, О, Р, С, Т, У, Х заменяются латинскими двойниками. То есть номер «а123вс77» уйдёт как «A123BC77». Если на стороне Claris заявки сопоставляются с событиями камер по номеру, учитывайте это при настройке правил сравнения.
- Даты передаются как момент времени с указанием часового пояса и к часовому поясу офиса не приводятся. Сам момент верен всегда, но на границе суток календарная дата в заявке может не совпасть с местной датой офиса — например, для брони на 02:00 по местному времени в офисе восточнее нулевого меридиана.
В ответ Claris возвращает номер созданной заявки. UnSpot сохраняет его в связке с бронью, но нигде не показывает и сам не использует: сверить бронь с заявкой средствами UnSpot нельзя, сверка возможна только в Claris.
Важно не спутать этот состав с обычной подпиской на то же событие. Обычная подписка шлёт на ваш адрес другой набор полей — ФИО и электронную почту сотрудника, номер и модель автомобиля, начало и конец брони, офис и место — отправляет его без заголовка авторизации и передаёт номер автомобиля без нормализации, как его ввёл сотрудник. Состав обычной подписки разобран в «Справочнике исходящих вебхуков».
Что не передаётся
- Электронная почта сотрудника, его отдел, должность и руководитель.
- Название офиса: в заявку идёт только номер парковочного места.
- Любые брони, кроме парковочных: столы, переговорные, локеры в Claris не попадают.
- Отмена и изменение брони. Заявка создаётся один раз и в Claris больше не обновляется — даже если сотрудник отменил бронь в UnSpot.
- Подтверждение прихода (чекин) по парковочной брони.
- Обратная запись из Claris в UnSpot: изменения, сделанные в заявке на стороне Claris, в UnSpot не возвращаются.
Одна операция — сколько заявок
Заявка создаётся не на действие сотрудника, а на каждую появившуюся бронь. Одно действие в интерфейсе может дать несколько броней — и, соответственно, несколько заявок.
| Что произошло в UnSpot | Сколько заявок уйдёт в Claris |
|---|---|
| Бронь на один день | одна |
| Бронь сразу на несколько дней или интервалов | по одной на каждый день или интервал |
| Обмен местами между двумя бронями | две новые. Прежние брони удаляются, но их заявки в Claris остаются |
| Бронь на закреплённом за сотрудником месте | одна на день, создаётся автоматически по расписанию платформы, без участия человека. Если бронь на этот день у сотрудника уже была, новая не создаётся и заявка не уходит |
| Отмена или изменение брони | ни одной: эти события в Claris не передаются |
| Любое из перечисленного при нескольких подписках с отправкой в Claris на один офис | умножьте на число таких подписок — продукт не запрещает завести их несколько |
Последняя строка — самая частая причина дублей в Claris. Правило простое: на один офис держите одну подписку с отправкой в Claris.
Учётные данные и токен
Для подключения администратор вводит логин и пароль учётной записи Claris. UnSpot обменивает их на токен доступа и запоминает и токен, и сами учётные данные.
| Что хранится | Где и как |
|---|---|
| Логин Claris | в базе данных вашей компании, в таблице настроек компании, открытым текстом |
| Пароль Claris | там же, в зашифрованном виде |
| Токен доступа и срок его действия | там же, открытым текстом |
| Идентификатор, имя и компания учётной записи Claris | там же, открытым текстом |
Все четыре строки — это одна запись настроек: значения лежат вместе, одним набором. Отдельного файла с паролем на диске нет.
Как именно зашифрован пароль, если этот вопрос задаёт служба безопасности:
- алгоритм — AES с длиной ключа 256 бит в режиме CBC, вектор инициализации случайный для каждого значения и хранится рядом с шифротекстом;
- проверки целостности у этой схемы нет: она обеспечивает конфиденциальность, но не гарантирует, что значение не подменено;
- ключ задаётся при установке UnSpot и хранится в настройках окружения приложения, а не в базе. Он один на всю инсталляцию, а не на компанию, и тем же ключом закрыты другие секреты продукта — например секреты двухфакторной аутентификации сотрудников и пароли других интеграций.
Пароль хранится именно потому, что он нужен повторно: срок жизни токена задаёт Claris, а если Claris его не сообщил, UnSpot считает токен действительным восемь часов. Когда срок истекает, UnSpot расшифровывает пароль и берёт новый токен — это происходит в момент отправки очередной заявки, а не по расписанию.
Отсюда два следствия для службы безопасности. Первое: заводите под интеграцию отдельную учётную запись Claris с правами только на создание заявок — под её именем будут числиться все заявки от UnSpot. Второе: смена пароля этой учётной записи в Claris ломает интеграцию молча, до следующего подключения в карточке.
Ещё одна особенность: увидеть, подключён ли Claris и под каким именем учётной записи, может любой сотрудник компании, а не только администратор. Менять подключение по-прежнему вправе только администратор интеграций.
Когда заявка создаётся и когда нет
Заявка уходит в Claris, если одновременно выполнены четыре условия: Claris подключён в карточке интеграции, подписка активна, офис брони входит в список офисов подписки и бронь именно парковочная.
| Ситуация | Что происходит |
|---|---|
| Claris не подключён, подписка активна | заявка не создаётся, ошибка не показывается, счётчик сбоев подписки не растёт |
| Пароль учётной записи Claris сменили | то же самое: обновить токен не удаётся, отправка тихо прекращается |
| В подписке не осталось ни одного офиса | подписка не срабатывает ни для какого офиса, оставаясь в статусе «активна». Список пустеет сам, если удалить офис из системы |
| Офис отправили в архив | подписка продолжает срабатывать по нему, хотя в списке офисов подписки архивный офис уже не отображается |
| Бронь отменили в UnSpot | заявка в Claris остаётся, её нужно закрывать вручную |
| Подключение Claris удалили в карточке | все подписки с отправкой в Claris переводятся в статус «отключена» |
| Claris подключили заново | подписки остаются отключёнными — их нужно включить вручную |
Первые четыре строки — главный эксплуатационный риск этой интеграции: со стороны администратора всё выглядит исправным, а заявки не создаются. Поэтому после любых работ с учётной записью Claris, с составом офисов и с архивацией офисов проверяйте интеграцию тестовой бронью.
Как идёт доставка и что бывает при сбоях
Отправка не мгновенная. Создав бронь, UnSpot ставит задачу в очередь, а отправляет её отдельный фоновый процесс. При обычной нагрузке это секунды, но принципиально другое: неудачная попытка не означает, что заявка потеряна.
- Если Claris ответил ошибкой, не вернул номер заявки или оказался недоступен, задача возвращается в очередь. Всего попыток одиннадцать: одна первичная и до десяти повторных. Пауза между попытками начинается с десяти секунд и с каждым разом увеличивается, так что последние попытки приходятся на несколько часов после брони.
- Каждая неуспешная попытка увеличивает счётчик сбоев подписки на единицу — счётчик считает попытки, а не брони. Успешная отправка обнуляет его.
- Когда счётчик доходит до ста, подписка получает статус «сбой» и отправка прекращается до вмешательства администратора. Сто попыток — это примерно девять-десять броней, по которым обмен провалился полностью.
- Когда попытки по конкретной брони исчерпаны, задача отбрасывается. Такая бронь останется без заявки в Claris, и вернуть её отправку из интерфейса нельзя — заявку придётся заводить в Claris руками.
Обратная сторона повторов — возможные дубли. Повторяется вся операция целиком, включая сам запрос. Поэтому если Claris заявку создал, но ответ пришёл без номера или оборвался, следующая попытка создаст вторую заявку на ту же бронь. Признака, по которому Claris мог бы отбросить повтор, UnSpot не передаёт. Если в Claris попадаются парные заявки с одинаковыми данными — это тот самый случай, а не ошибка оператора.
Об отключении подписки по превышению счётчика UnSpot сообщает письмом, но только если в компании заведена активная подписка на событие «Системные ошибки» с указанным адресом почты. Если такой подписки нет, отключение произойдёт молча: статус и счётчик сбоев увидит только тот, кто откроет раздел «Исходящие подписки».
Что попадает в журналы
Раздел для службы безопасности: этот вопрос задают при согласовании почти всегда.
| Событие | Что записывается | Куда |
|---|---|---|
| Заявка создана | тип записи, имя события, поддомен компании, время выполнения запроса, признак успеха | журнал приложения |
| Заявка не создана | то же плюс текст ошибки обмена | журнал приложения и внешняя система сбора ошибок, с тегом компании |
| Не удалось обновить токен | предупреждение с текстом ошибки и поддоменом компании | журнал приложения |
Персональных данных в этих записях нет. ФИО, номер автомобиля и текст сообщения для приемной существуют только внутри самого запроса к Claris и в журналы не выводятся. Логин и пароль учётной записи Claris в журналы также не попадают.
Требования к сети и правам
- Исходящий доступ от сервера UnSpot к api.claris.su по HTTPS. Для установки UnSpot в контуре клиента это единственное сетевое требование интеграции.
- Входящие подключения со стороны Claris не нужны.
- Роль «Администратор интеграций» в UnSpot — чтобы подключить или отключить Claris и настроить исходящую подписку. Эту роль имеют также владельцы компании; отдельные администраторы офисов и персонала её не получают.
- Учётная запись в Claris с правом создавать заявки — по принципу минимальных привилегий, только это право.
