BAS-IP Link API: як інтегрувати системи домофонії та контролю доступу
Нового мешканця спочатку створюють у системі, яку керуюча компанія вже використовує для квартир, мешканців та контактних даних. Потім ту ж саму людину створюють знову, цього разу в системі домофонії. Права доступу змінюються — потрібно оновити дві системи. Мешканець виїжджає — запис потрібно видалити двічі.
На одному об’єкті це просто додаткове адміністрування. У масштабах портфеля нерухомості з регулярними заїздами, змінами доступу та тимчасовими перепустками це перетворюється на окремий процес управління, якого від початку ніхто не хотів.
Що таке BAS-IP Link та Link API?
BAS-IP Link — це централізована платформа BAS-IP для управління об’єктами, користувачами, правами доступу та підключеною інфраструктурою.
BAS-IP Link API — це HTTP REST API, який дозволяє серверній системі третьої сторони програмно взаємодіяти з Link: передавати дані користувачів, керувати правами доступу та обліковими даними, а також отримувати дані з платформи.
Мета полягає не в тому, щоб дати персоналу ще одну систему для роботи. Навпаки: існуюча платформа клієнта може залишатися основним робочим інтерфейсом, тоді як BAS-IP стає частиною процесів, які там вже керуються.
Як це виглядає на практиці? Додавання нового мешканця
Керуюча компанія вже знає ім’я мешканця, квартиру, контактні дані та іншу відповідну інформацію. Ці дані вже існують у її власній системі.
Без інтеграції співробітник повинен відкрити BAS-IP Link і знову створити того ж самого користувача.
Завдяки Link API цей другий крок можна автоматизувати. Головна система передає необхідні дані в Link, користувач розміщується у відповідному об’єкті та квартирі, а потім BAS-IP Link працює з підключеною інфраструктурою домофонії та доступу.
Практична цінність полягає не просто в тому, що дві системи можуть обмінюватися даними. Вона полягає в тому, що персоналу не потрібно змінювати спосіб своєї роботи.
Якщо заїзди, зміни даних мешканців та виїзди вже керуються в головній платформі, ті ж самі дії не потрібно повторювати вручну в системі домофонії.
Чому варто використовувати Link API, якщо пристрої BAS-IP мають власний API?
BAS-IP також підтримує пряму інтеграцію з обладнанням через BAS-IP Device API.
Для локального проєкту це може бути правильним підходом. Якщо системі потрібно працювати з однією або кількома відомими моделями пристроїв і потрібен лише обмежений набір функцій, додатковий серверний рівень може не знадобитися.
Вимоги змінюються в міру масштабування проєкту.
У різних будівлях можуть використовуватися різні панелі виклику, внутрішні монітори та інші пристрої. З часом з’являються нові моделі та версії прошивок. При прямій інтеграції з пристроями команда розробників третьої сторони повинна враховувати характеристики обладнання, з яким вона інтегрується.
BAS-IP Link додає централізований програмний рівень між сторонньою платформою та інфраструктурою домофонії.
Замість того, щоб будувати свою бізнес-логіку навколо конкретної панелі виклику, зовнішня платформа працює з центральною моделлю Link, що включає користувачів, об’єкти, квартири, права доступу та інші сутності.
Зазвичай це більш природна модель для платформи управління житловою нерухомістю. Як правило, їй не потрібно знати, яка саме панель виклику встановлена на певних дверях. Їй потрібно знати, що певний мешканець належить до певної квартири і повинен мати доступ до відповідних зон.
BAS-IP Link з’єднує цю бізнес-логіку з фізичною інфраструктурою домофонії та контролю доступу.
Що можна робити за допомогою BAS-IP Link API?
Конкретна інтеграція зазвичай використовуватиме лише частину функціоналу, доступного в Link.
Через API стороння система може працювати з:
- користувачами та структурою об’єкта;
- правами доступу;
- постійними та тимчасовими обліковими даними доступу, включаючи картки, брелоки, PIN-коди, QR-коди, Face ID, UKEY та номерні знаки автомобілів;
- гостьовим доступом і відвідувачами;
- повідомленнями та опитуваннями;
- віртуальними номерами та переадресацією викликів;
- віддаленим налаштуванням пристроїв;
- подіями та журналами.
Проте проєкт інтеграції зазвичай краще визначається іншим питанням, аніж «Які методи API доступні?».
Які завдання сьогодні виконуються вручну, і які з них повинні відбуватися автоматично після інтеграції систем?
Для однієї платформи основним варіантом використання може бути управління мешканцями. Для іншої — це може бути тимчасовий доступ підрядників. Третій можуть бути потрібні переважно дані про події.
Управління всім життєвим циклом користувача, а не лише його створенням
Створення користувача — це лише перший крок.
Після додавання мешканця йому можна призначити відповідні права доступу та ідентифікатори. Якщо мешканець переїжджає в іншу квартиру, змінює транспортний засіб, отримує додаткові дозволи або втрачає доступ, ці зміни також можуть стати частиною робочого процесу в головній платформі.
Той самий принцип стосується і тимчасових користувачів.
Якщо існуюча система вже керує відвідувачами, підрядниками або обслуговуючим персоналом, немає потреби створювати окремий адміністративний процес суто для BAS-IP.
Наприклад, головна платформа може визначити, що підрядник повинен мати змогу увійти до будівлі у вівторок з 10:00 до 14:00. У цьому сценарії BAS-IP стає рівнем доступу, який виконує процес, вже визначений в іншому місці.
Отже, домофонія та контроль доступу стають частиною ширшої операційної моделі будівлі, а не окремою системою, якою потрібно керувати незалежно.
Що робити, якщо об’єкт вже працює і має велику базу користувачів?
Інтеграція не обов’язково починається з порожньої бази даних.
Якщо існуюча система вже містить сотні або тисячі мешканців, їх не потрібно вводити в BAS-IP Link вручну по одному.
При використанні BAS-IP Link API метод створення користувача може додавати кількох користувачів одним запитом.
Гарантована максимальна кількість записів на одну операцію та дозволена частота послідовних запитів наразі не вказані. Тому для великої міграції ці параметри слід перевірити в тестовому середовищі проєкту перед перенесенням усієї бази користувачів.
Деталі реалізації методу API надаються партнерам з інтеграції в технічній документації.
Існує також вбудована опція для масового створення користувачів без розробки інтеграції API.
BAS-IP Link може експортувати структуру об’єкта у файл XLS. Потім дані користувача та ліцензії заповнюються в електронній таблиці та імпортуються назад у Link. Після імпорту користувачі автоматично розподіляються до вказаних груп об’єктів. Коли кілька користувачів належать до однієї квартири або іншої групи об’єкта, окремі рядки можуть використовувати один і той же ідентифікатор групи.
Для початкового впровадження в житловому комплексі не обов’язково збирати електронні адреси кожного члена сім’ї. Достатньо однієї електронної адреси на квартиру: запрошений користувач отримує електронний лист, завершує реєстрацію і потім може самостійно додати членів сім’ї.
Таким чином, для існуючого комплексу команда проєкту може вибирати між автоматизованою міграцією API та вбудованим у Link процесом масового завантаження, залежно від архітектури системи та місця зберігання вихідної бази даних користувачів.
Чи можна використовувати події BAS-IP в іншій системі?
Так. Дані та події, що зберігаються в Link, можуть використовуватися сторонньою системою.
Наприклад, служба безпеки вже може працювати з єдиного інтерфейсу, який об’єднує інформацію з контролю доступу, відеоспостереження та інших систем будівлі. Дані BAS-IP можуть стати частиною того ж робочого процесу.
Однак є важлива технічна відмінність.
BAS-IP Link наразі не надає вебхуків (webhooks) для надсилання подій до сторонніх систем. Зовнішня система отримує необхідні дані, роблячи запити до Link API.
Якщо проєкт вимагає, щоб певні події доставлялися безпосередньо з обладнання через вебхуки, цей сценарій доступний на підтримуваних панелях виклику на базі Android через BAS-IP Device API.
Тому проєкт може поєднувати централізовану інтеграцію через Link з прямою взаємодією з вибраними пристроями, де це необхідно.
Яка система має бути джерелом істини?
Одне з ключових рішень в інтеграції — яка система відповідає за кожен тип даних.
Якщо того ж самого користувача можна змінювати незалежно як у платформі управління нерухомістю, так і в BAS-IP Link, записи зрештою можуть стати неузгодженими.
Наприклад, платформа управління нерухомістю може залишатися відповідальною за мешканців і квартири, BAS-IP Link може застосовувати цю інформацію для домофонії та контролю доступу, тоді як окрема платформа безпеки споживає дані про події, необхідні операторам.
Інший проєкт може розподілити обов’язки інакше.
Важливо не те, що BAS-IP або стороння платформа повинні завжди бути «головною» системою. Важливо те, що авторитетне джерело для кожної сутності та напрямок синхронізації мають бути чітко визначені.
Саме це усуває дублювання адміністрування, а не просте з’єднання двох баз даних.
Де Link API є найбільш корисним?
Link API особливо актуальний там, де BAS-IP має стати частиною існуючої екосистеми програмного забезпечення.
Типові приклади включають:
- платформи управління житловою нерухомістю та комплексами;
- великі системи контролю доступу;
- BMS та платформи розумних будівель;
- продукти PropTech;
- власні програмні платформи інтеграторів;
- платформи управління кількома будівлями або об’єктами.
Чим більше в проєкті користувачів, будівель і регулярних змін доступу, тим більше дублюється адміністрування, коли системи залишаються окремими.
Тому цінність Link API зазвичай визначається не кількістю доступних методів API, а кількістю окремих робочих процесів, які можна об’єднати.
Безпека та дозволи на інтеграцію
Стороння система не потребує необмеженого адміністративного доступу до Link.
У BAS-IP Link Self-Hosted можна створити виділений обліковий запис для інтеграції та обмежити його дозволи як за функціями, так і за окремим об’єктом.
Наприклад, інтеграція, яка використовується певним оператором нерухомості, може бути обмежена будівлями, якими керує ця організація.
Для аутентифікації використовуються токени доступу, а зв’язок з API відбувається через HTTPS.
Детальний процес аутентифікації та структури запитів описані в технічній документації Link API.
BAS-IP Link Self-Hosted та Link Cloud
На момент публікації серверні інтеграції третіх сторін через BAS-IP Link API підтримуються в BAS-IP Link Self-Hosted.
BAS-IP розробляє окремий шлюз API для BAS-IP Link Cloud.
Тому, якщо проєкт конкретно вимагає інтеграції третьої сторони з Link Cloud, пропоновану архітектуру слід обговорити з BAS-IP до початку розробки.
Як розпочати інтеграцію
Проєкт Link API починається з варіанту використання, а не зі списку викликів API.
Наприклад:
«Коли ми створюємо мешканця в нашій платформі, ми хочемо, щоб користувач автоматично створювався у правильному об’єкті BAS-IP».
Цього достатньо, щоб почати обговорення архітектури.
Після узгодження сценарію інтеграції партнер підписує NDA (угоду про нерозголошення) і отримує відповідні технічні матеріали.
Сама інтеграція зазвичай розробляється командою партнера. Для типового проєкту зазвичай потрібен back-end або full-stack розробник. Великі розгортання також можуть вимагати експертизи DevOps.
Для розробки та тестування BAS-IP Link Self-Hosted можна розгорнути у власному середовищі партнера. Наразі не існує спільної публічної пісочниці (sandbox) для Link API. Тестова ліцензія та апаратне забезпечення узгоджуються відповідно до вимог індивідуального проєкту.
BAS-IP надає документацію, відповідає на технічні питання щодо власних продуктів і допомагає досліджувати випадки, коли реалізація на основі документації поводиться не так, як очікувалося.
Якщо проєкт вимагає функціоналу, який наразі недоступний у продукті, ці вимоги можна обговорити з командою продукту. Спершу оцінюється обсяг роботи та її місце в плані розробки. Така оцінка сама по собі не є зобов’язанням щодо конкретної дати випуску.
Скільки часу займає інтеграція Link API?
Не існує єдиних часових рамок, які застосовуються до кожного проєкту.
Для відносно стандартної інтеграції як загальний орієнтир можна використовувати близько одного місяця сфокусованої розробки, хоча календарна тривалість часто буває довшою.
Команді розробників партнера потрібен час, щоб зрозуміти модель даних Link, реалізувати свою частину інтеграції, протестувати її та вписати цю роботу у власний графік розробки.
Тому обґрунтовану оцінку можна зробити лише після визначення фактичного сценарію інтеграції.
Чи стягується додаткова плата за BAS-IP Link API?
BAS-IP зазвичай не стягує окремої плати за доступ до документації та інструментів інтеграції.
Сам BAS-IP Link ліцензується за стандартною моделлю ліцензування продукту. Партнер розробляє власну частину інтеграції, тоді як нестандартні роботи з розробки BAS-IP або прохання змінити пріоритет таких робіт можуть обговорюватися окремо, якщо це необхідно.
З цієї причини називати саму інтеграцію «безкоштовною» може бути оманливим.
Більш точне твердження полягає в тому, що зазвичай не стягується окрема плата за доступ до інструментів інтеграції BAS-IP.
Коли Link API не є правильним підходом?
Link API в першу чергу призначений для серверної інтеграції з BAS-IP Link.
Якщо вимога полягає в прямій роботі з конкретним обладнанням або в отриманні певних подій безпосередньо з панелі виклику, BAS-IP Device API може бути більш доречним. Документація з інтеграції пристроїв доступна на публічному порталі розробників BAS-IP.
Якщо організація вже має власний мобільний додаток і хоче додати виклики домофона, відео та відкриття дверей у цей додаток, для цього варіанту використання призначений BAS-IP Mobile SDK.
А там, де достатньо стандартної взаємодії через SIP, RTSP або Wiegand, розробка спеціального програмного забезпечення для інтеграції може взагалі не знадобитися.
Різні підходи більш детально розглядаються в статті «Інтеграція IP-домофонії BAS-IP з існуючими системами будівлі».
Часті питання
Чи є BAS-IP Link API REST API?
Так. BAS-IP Link API — це HTTP REST API, який дозволяє серверній системі третьої сторони програмно взаємодіяти з BAS-IP Link.
Чи потрібен мені BAS-IP Link для використання Link API?
Так. Link API — це програмний інтерфейс для платформи BAS-IP Link.
Чи працює BAS-IP Link API з Link Cloud?
На момент публікації серверні інтеграції третіх сторін через Link API підтримуються в BAS-IP Link Self-Hosted. BAS-IP розробляє окремий шлюз API для Link Cloud.
Як отримати документацію, і чи потрібен NDA?
Спочатку узгоджується варіант використання інтеграції. Потім партнер підписує NDA і отримує відповідні технічні матеріали Link API.
Яка різниця між Link API та Mobile SDK?
Link API призначений для серверної інтеграції з BAS-IP Link, включаючи користувачів, об’єкти, права доступу та інші централізовані сутності платформи.
BAS-IP Mobile SDK служить іншій меті: додавання функціональності домофонії безпосередньо до існуючого мобільного додатку.
Обидва інструменти можна використовувати в рамках одного проєкту, якщо це необхідно.
Бажаєте інтегрувати свою платформу з BAS-IP Link?
Вам не потрібно готувати детальну специфікацію API до першого обговорення.
Почніть з опису системи, яку ви вже маєте, і процесу, який ви хочете автоматизувати.
Наприклад:
«Ми створюємо мешканців у нашій власній платформі і хочемо, щоб вони автоматично переносилися в BAS-IP».
або:
«Ми керуємо доступом відвідувачів у нашій власній системі і хочемо пов’язати цей процес з BAS-IP».
Команда BAS-IP може допомогти визначити, чи є Link API правильним підходом, які можливості платформи знадобляться та як має бути структурована інтеграція.